# Context Graphs

## List context graphs

> List context graphs in a workspace with pagination. Requires \`ContextGraph.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SearchString":{"type":"string","maxLength":200,"minLength":1},"PaginatedResponse_ContextGraphResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ContextGraphResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[ContextGraphResponse]"},"ContextGraphResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"type":"integer","title":"Latest Version","default":0},"state_count":{"type":"integer","title":"State Count","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","description","created_at","updated_at"],"title":"ContextGraphResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/context-graphs":{"get":{"tags":["Context Graphs"],"summary":"List context graphs","description":"List context graphs in a workspace with pagination. Requires `ContextGraph.view` permission.","operationId":"list-context_graphs","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchString"},{"type":"null"}],"title":"Search"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_ContextGraphResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a context graph

> Create a new context graph in a workspace. Requires \`ContextGraph.create\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateContextGraphRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""}},"type":"object","required":["name"],"title":"CreateContextGraphRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"ContextGraphResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"type":"integer","title":"Latest Version","default":0},"state_count":{"type":"integer","title":"State Count","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","description","created_at","updated_at"],"title":"ContextGraphResponse"}}},"paths":{"/v1/{workspace_id}/context-graphs":{"post":{"tags":["Context Graphs"],"summary":"Create a context graph","description":"Create a new context graph in a workspace. Requires `ContextGraph.create` permission.","operationId":"create-context_graph","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContextGraphRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextGraphResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"409":{"description":"Name already taken."},"422":{"description":"Invalid request body."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get a context graph

> Retrieve a context graph by ID. Requires \`ContextGraph.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ContextGraphResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"type":"integer","title":"Latest Version","default":0},"state_count":{"type":"integer","title":"State Count","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","description","created_at","updated_at"],"title":"ContextGraphResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/context-graphs/{context_graph_id}":{"get":{"tags":["Context Graphs"],"summary":"Get a context graph","description":"Retrieve a context graph by ID. Requires `ContextGraph.view` permission.","operationId":"get-context_graph","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"context_graph_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Context Graph Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextGraphResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a context graph

> Update a context graph's name or description. Requires \`ContextGraph.update\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UpdateContextGraphRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","title":"UpdateContextGraphRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"ContextGraphResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"type":"integer","title":"Latest Version","default":0},"state_count":{"type":"integer","title":"State Count","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","name","description","created_at","updated_at"],"title":"ContextGraphResponse"}}},"paths":{"/v1/{workspace_id}/context-graphs/{context_graph_id}":{"put":{"tags":["Context Graphs"],"summary":"Update a context graph","description":"Update a context graph's name or description. Requires `ContextGraph.update` permission.","operationId":"update-context_graph","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"context_graph_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Context Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContextGraphRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextGraphResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"409":{"description":"Name already taken."},"422":{"description":"Invalid request body."}}}}}}
```

## Delete a context graph

> Delete a context graph. context graph versions are retained. Requires \`ContextGraph.delete\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/context-graphs/{context_graph_id}":{"delete":{"tags":["Context Graphs"],"summary":"Delete a context graph","description":"Delete a context graph. context graph versions are retained. Requires `ContextGraph.delete` permission.","operationId":"delete-context_graph","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"context_graph_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Context Graph Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List context graph versions

> List versions of a context graph with pagination. Requires \`ContextGraph.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_ContextGraphVersionResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ContextGraphVersionResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[ContextGraphVersionResponse]"},"ContextGraphVersionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"version":{"type":"integer","title":"Version"},"description":{"type":"string","title":"Description"},"states":{"items":{"$ref":"#/components/schemas/ContextGraphState-Output"},"type":"array","title":"States"},"new_user_initial_state":{"type":"string","title":"New User Initial State"},"returning_user_initial_state":{"type":"string","title":"Returning User Initial State"},"terminal_state":{"type":"string","title":"Terminal State"},"global_intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Intra State Navigation Guidelines"},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines"},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints"},"topology_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topology Description"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","context_graph_id","version","description","states","new_user_initial_state","returning_user_initial_state","terminal_state","global_intra_state_navigation_guidelines","global_action_guidelines","global_boundary_constraints","topology_description","created_at","updated_at"],"title":"ContextGraphVersionResponse"},"ContextGraphState-Output":{"oneOf":[{"$ref":"#/components/schemas/ActionState-Output"},{"$ref":"#/components/schemas/DecisionState-Output"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState-Output"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState-Output","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState-Output","decision":"#/components/schemas/DecisionState-Output"}}},"ActionState-Output":{"properties":{"type":{"type":"string","const":"action","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Intra State Navigation Guidelines"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines"},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"action_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Action Tool Call Specs","default":[]},"exit_condition_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Exit Condition Tool Call Specs","default":[]},"escalation_config":{"anyOf":[{"$ref":"#/components/schemas/StateRiskOverride"},{"type":"null"}]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"surface_spec_template":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Surface Spec Template"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"preload":{"items":{"$ref":"#/components/schemas/PreloadSpec"},"type":"array","maxItems":20,"title":"Preload"}},"type":"object","required":["type","name","objective","actions","intra_state_navigation_guidelines","action_guidelines","boundary_constraints","exit_conditions"],"title":"ActionState","description":"User-facing engagement state with actions and exit conditions."},"Action":{"properties":{"description":{"type":"string","title":"Description"},"filler_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Hint"}},"type":"object","required":["description"],"title":"Action","description":"A single action the agent can take within a state."},"ExitCondition":{"properties":{"description":{"type":"string","title":"Description"},"next_state":{"type":"string","title":"Next State"},"filler_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Hint"}},"type":"object","required":["description","next_state"],"title":"ExitCondition"},"ToolCallSpec":{"properties":{"tool_id":{"type":"string","title":"Tool Id"},"additional_instruction":{"type":"string","title":"Additional Instruction","default":""},"navigate_on_completion":{"type":"boolean","title":"Navigate On Completion","default":false},"progress":{"anyOf":[{"$ref":"#/components/schemas/ProgressHint"},{"type":"null"}]},"result_persistence":{"type":"string","enum":["accumulate","override"],"title":"Result Persistence","default":"accumulate"},"audio_fillers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Audio Fillers"},"audio_filler_triggered_after":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Filler Triggered After"}},"type":"object","required":["tool_id"],"title":"ToolCallSpec","description":"A tool call that the agent can make in a state."},"ProgressHint":{"properties":{"deterministic":{"type":"boolean","title":"Deterministic","default":false},"phrases":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"description":"Filler phrases. deterministic=true: played verbatim in order. deterministic=false: used as hints for early attempts."},{"type":"null"}],"title":"Phrases"},"trigger_delay_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":0},{"type":"null"}],"title":"Trigger Delay Ms"},"interval_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":100},{"type":"null"}],"title":"Interval Ms"},"mode":{"type":"string","enum":["auto","silent","backchannel","verbal"],"title":"Mode","default":"auto"},"progress_class":{"anyOf":[{"type":"string","enum":["lookup","write","external_call","compute","multi_step"]},{"type":"null"}],"title":"Progress Class"},"expected_latency_ms":{"anyOf":[{"type":"integer","maximum":60000,"minimum":0},{"type":"null"}],"title":"Expected Latency Ms"},"custom_phrase":{"anyOf":[{"type":"string","maxLength":500,"description":"Legacy: use phrases instead."},{"type":"null"}],"title":"Custom Phrase"}},"additionalProperties":false,"type":"object","title":"ProgressHint","description":"How the agent narrates waiting on a tool.\n\n``deterministic=true``: scripted — ``phrases`` play verbatim in order.\n``deterministic=false``: engine picks — ``phrases`` are hints.\n``trigger_delay_ms``: milliseconds before first filler (0 = immediate).\n``interval_ms``: milliseconds between subsequent fillers."},"StateRiskOverride":{"properties":{"topic_risk_score":{"type":"number","title":"Topic Risk Score","default":0},"auto_escalate_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Auto Escalate Threshold"},"max_loop_count":{"type":"integer","title":"Max Loop Count","default":3},"operator_skill":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Skill"}},"type":"object","title":"StateRiskOverride","description":"Per-state escalation tuning. Stored on ActionState."},"Guardrail":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":1000,"title":"Description"},"enforcement":{"type":"string","enum":["hard","soft"],"title":"Enforcement","default":"hard"}},"type":"object","required":["name","description"],"title":"Guardrail","description":"Typed safety rule enforced per-state (not just global freetext guidelines)."},"ChannelOverride":{"properties":{"objective":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Objective"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"progress":{"anyOf":[{"$ref":"#/components/schemas/ProgressHint"},{"type":"null"}]}},"type":"object","title":"ChannelOverride","description":"Per-channel behavior override for a state."},"TurnPolicy":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","summarize","compact"],"title":"Context Strategy","default":"full"},"degradation_threshold":{"type":"integer","minimum":-1,"title":"Degradation Threshold","default":-1},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","minimum":-1,"title":"Block Forward Call After Turns","default":-1},"stt_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Eot Threshold"},"stt_eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Eager Eot Threshold"},"stt_eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stt Eot Timeout Ms"}},"type":"object","title":"TurnPolicy","description":"Voice pipeline parameters declared per HSM state.\n\nLives on ActionState/DecisionState alongside guardrails, wait_for, and\nchannel_overrides.  The HSM state IS the policy — no shadow state machine.\nAll fields optional with safe defaults (production behavior unchanged\nwhen no turn_policy is set)."},"PreloadSpec":{"properties":{"tool_id":{"type":"string","maxLength":256,"title":"Tool Id"},"params":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Params"}},"type":"object","required":["tool_id"],"title":"PreloadSpec","description":"A tool call executed deterministically by the engine on state entry.\n\nUnlike LLM-driven tool calls, preloads run before any LLM turn —\nthe results appear in the interaction log so the engage LLM sees\nthem as pre-loaded context.  All preloads in a state execute in\nparallel.  Param values support ``{caller_mrn}`` and ``{entity_id}``\ntemplate variables resolved from the session's caller context."},"DecisionState-Output":{"properties":{"type":{"type":"string","const":"decision","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"decision_guidelines":{"items":{"type":"string"},"type":"array","title":"Decision Guidelines","default":[]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]}},"type":"object","required":["type","name","objective","exit_conditions"],"title":"DecisionState","description":"Passthrough routing state — Agent picks an exit condition, no user interaction."},"AnnotationState":{"properties":{"type":{"type":"string","const":"annotation","title":"Type"},"name":{"type":"string","title":"Name"},"inner_thought":{"type":"string","title":"Inner Thought"},"next_state":{"type":"string","title":"Next State"}},"type":"object","required":["type","name","inner_thought","next_state"],"title":"AnnotationState","description":"Injects a hardcoded inner thought (no LLM call)."},"DataCollectionState-Output":{"properties":{"type":{"type":"string","const":"data_collection","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"fields":{"items":{"$ref":"#/components/schemas/CollectionField"},"type":"array","title":"Fields"},"on_complete":{"type":"string","title":"On Complete"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"surface_fallback":{"type":"boolean","title":"Surface Fallback","default":false},"surface_fallback_after_turns":{"type":"integer","title":"Surface Fallback After Turns","default":6},"max_turns":{"type":"integer","title":"Max Turns","default":10},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]}},"type":"object","required":["type","name","objective","fields","on_complete"],"title":"DataCollectionState","description":"Structured voice/text data collection with field tracking.\n\nThe engine presents fields conversationally, tracks completion, and\noptionally falls back to a Surface form after N turns. Each collected\nfield produces a world.event with confidence 0.5."},"CollectionField":{"properties":{"key":{"type":"string","title":"Key"},"type":{"type":"string","title":"Type"},"label":{"type":"string","title":"Label"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"validation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation"},"ask_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ask Prompt"},"fhir_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Path"}},"type":"object","required":["key","type","label"],"title":"CollectionField","description":"A single field to collect during a data collection state."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/context-graphs/{context_graph_id}/versions":{"get":{"tags":["Context Graphs"],"summary":"List context graph versions","description":"List versions of a context graph with pagination. Requires `ContextGraph.view` permission.","operationId":"list-context_graph-versions","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"context_graph_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Context Graph Id"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_ContextGraphVersionResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a context graph version

> Create a new version of a context graph. Version number is auto-incremented. Requires \`ContextGraph.create\` permission for the first version and \`ContextGraph.update\` permission afterward.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateContextGraphVersionRequest":{"properties":{"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"states":{"items":{"$ref":"#/components/schemas/ContextGraphState-Input"},"type":"array","title":"States"},"new_user_initial_state":{"type":"string","title":"New User Initial State"},"returning_user_initial_state":{"type":"string","title":"Returning User Initial State"},"terminal_state":{"type":"string","title":"Terminal State"},"global_intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Intra State Navigation Guidelines","default":[]},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines","default":[]},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints","default":[]},"topology_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topology Description"}},"type":"object","required":["states","new_user_initial_state","returning_user_initial_state","terminal_state"],"title":"CreateContextGraphVersionRequest"},"DescriptionString":{"type":"string","maxLength":2000},"ContextGraphState-Input":{"oneOf":[{"$ref":"#/components/schemas/ActionState-Input"},{"$ref":"#/components/schemas/DecisionState-Input"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState-Input"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState-Input","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState-Input","decision":"#/components/schemas/DecisionState-Input"}}},"ActionState-Input":{"properties":{"type":{"type":"string","const":"action","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Intra State Navigation Guidelines"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines"},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"action_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Action Tool Call Specs","default":[]},"exit_condition_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Exit Condition Tool Call Specs","default":[]},"escalation_config":{"anyOf":[{"$ref":"#/components/schemas/StateRiskOverride"},{"type":"null"}]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"surface_spec_template":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Surface Spec Template"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"preload":{"items":{"$ref":"#/components/schemas/PreloadSpec"},"type":"array","maxItems":20,"title":"Preload"}},"type":"object","required":["type","name","objective","actions","intra_state_navigation_guidelines","action_guidelines","boundary_constraints","exit_conditions"],"title":"ActionState","description":"User-facing engagement state with actions and exit conditions."},"Action":{"properties":{"description":{"type":"string","title":"Description"},"filler_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Hint"}},"type":"object","required":["description"],"title":"Action","description":"A single action the agent can take within a state."},"ExitCondition":{"properties":{"description":{"type":"string","title":"Description"},"next_state":{"type":"string","title":"Next State"},"filler_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Hint"}},"type":"object","required":["description","next_state"],"title":"ExitCondition"},"ToolCallSpec":{"properties":{"tool_id":{"type":"string","title":"Tool Id"},"additional_instruction":{"type":"string","title":"Additional Instruction","default":""},"navigate_on_completion":{"type":"boolean","title":"Navigate On Completion","default":false},"progress":{"anyOf":[{"$ref":"#/components/schemas/ProgressHint"},{"type":"null"}]},"result_persistence":{"type":"string","enum":["accumulate","override"],"title":"Result Persistence","default":"accumulate"},"audio_fillers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Audio Fillers"},"audio_filler_triggered_after":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Filler Triggered After"}},"type":"object","required":["tool_id"],"title":"ToolCallSpec","description":"A tool call that the agent can make in a state."},"ProgressHint":{"properties":{"deterministic":{"type":"boolean","title":"Deterministic","default":false},"phrases":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"description":"Filler phrases. deterministic=true: played verbatim in order. deterministic=false: used as hints for early attempts."},{"type":"null"}],"title":"Phrases"},"trigger_delay_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":0},{"type":"null"}],"title":"Trigger Delay Ms"},"interval_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":100},{"type":"null"}],"title":"Interval Ms"},"mode":{"type":"string","enum":["auto","silent","backchannel","verbal"],"title":"Mode","default":"auto"},"progress_class":{"anyOf":[{"type":"string","enum":["lookup","write","external_call","compute","multi_step"]},{"type":"null"}],"title":"Progress Class"},"expected_latency_ms":{"anyOf":[{"type":"integer","maximum":60000,"minimum":0},{"type":"null"}],"title":"Expected Latency Ms"},"custom_phrase":{"anyOf":[{"type":"string","maxLength":500,"description":"Legacy: use phrases instead."},{"type":"null"}],"title":"Custom Phrase"}},"additionalProperties":false,"type":"object","title":"ProgressHint","description":"How the agent narrates waiting on a tool.\n\n``deterministic=true``: scripted — ``phrases`` play verbatim in order.\n``deterministic=false``: engine picks — ``phrases`` are hints.\n``trigger_delay_ms``: milliseconds before first filler (0 = immediate).\n``interval_ms``: milliseconds between subsequent fillers."},"StateRiskOverride":{"properties":{"topic_risk_score":{"type":"number","title":"Topic Risk Score","default":0},"auto_escalate_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Auto Escalate Threshold"},"max_loop_count":{"type":"integer","title":"Max Loop Count","default":3},"operator_skill":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Skill"}},"type":"object","title":"StateRiskOverride","description":"Per-state escalation tuning. Stored on ActionState."},"Guardrail":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":1000,"title":"Description"},"enforcement":{"type":"string","enum":["hard","soft"],"title":"Enforcement","default":"hard"}},"type":"object","required":["name","description"],"title":"Guardrail","description":"Typed safety rule enforced per-state (not just global freetext guidelines)."},"ChannelOverride":{"properties":{"objective":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Objective"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"progress":{"anyOf":[{"$ref":"#/components/schemas/ProgressHint"},{"type":"null"}]}},"type":"object","title":"ChannelOverride","description":"Per-channel behavior override for a state."},"TurnPolicy":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","summarize","compact"],"title":"Context Strategy","default":"full"},"degradation_threshold":{"type":"integer","minimum":-1,"title":"Degradation Threshold","default":-1},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","minimum":-1,"title":"Block Forward Call After Turns","default":-1},"stt_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Eot Threshold"},"stt_eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Eager Eot Threshold"},"stt_eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stt Eot Timeout Ms"}},"type":"object","title":"TurnPolicy","description":"Voice pipeline parameters declared per HSM state.\n\nLives on ActionState/DecisionState alongside guardrails, wait_for, and\nchannel_overrides.  The HSM state IS the policy — no shadow state machine.\nAll fields optional with safe defaults (production behavior unchanged\nwhen no turn_policy is set)."},"PreloadSpec":{"properties":{"tool_id":{"type":"string","maxLength":256,"title":"Tool Id"},"params":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Params"}},"type":"object","required":["tool_id"],"title":"PreloadSpec","description":"A tool call executed deterministically by the engine on state entry.\n\nUnlike LLM-driven tool calls, preloads run before any LLM turn —\nthe results appear in the interaction log so the engage LLM sees\nthem as pre-loaded context.  All preloads in a state execute in\nparallel.  Param values support ``{caller_mrn}`` and ``{entity_id}``\ntemplate variables resolved from the session's caller context."},"DecisionState-Input":{"properties":{"type":{"type":"string","const":"decision","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"decision_guidelines":{"items":{"type":"string"},"type":"array","title":"Decision Guidelines","default":[]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]}},"type":"object","required":["type","name","objective","exit_conditions"],"title":"DecisionState","description":"Passthrough routing state — Agent picks an exit condition, no user interaction."},"AnnotationState":{"properties":{"type":{"type":"string","const":"annotation","title":"Type"},"name":{"type":"string","title":"Name"},"inner_thought":{"type":"string","title":"Inner Thought"},"next_state":{"type":"string","title":"Next State"}},"type":"object","required":["type","name","inner_thought","next_state"],"title":"AnnotationState","description":"Injects a hardcoded inner thought (no LLM call)."},"DataCollectionState-Input":{"properties":{"type":{"type":"string","const":"data_collection","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"fields":{"items":{"$ref":"#/components/schemas/CollectionField"},"type":"array","title":"Fields"},"on_complete":{"type":"string","title":"On Complete"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"surface_fallback":{"type":"boolean","title":"Surface Fallback","default":false},"surface_fallback_after_turns":{"type":"integer","title":"Surface Fallback After Turns","default":6},"max_turns":{"type":"integer","title":"Max Turns","default":10},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]}},"type":"object","required":["type","name","objective","fields","on_complete"],"title":"DataCollectionState","description":"Structured voice/text data collection with field tracking.\n\nThe engine presents fields conversationally, tracks completion, and\noptionally falls back to a Surface form after N turns. Each collected\nfield produces a world.event with confidence 0.5."},"CollectionField":{"properties":{"key":{"type":"string","title":"Key"},"type":{"type":"string","title":"Type"},"label":{"type":"string","title":"Label"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"validation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation"},"ask_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ask Prompt"},"fhir_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Path"}},"type":"object","required":["key","type","label"],"title":"CollectionField","description":"A single field to collect during a data collection state."},"ContextGraphVersionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"version":{"type":"integer","title":"Version"},"description":{"type":"string","title":"Description"},"states":{"items":{"$ref":"#/components/schemas/ContextGraphState-Output"},"type":"array","title":"States"},"new_user_initial_state":{"type":"string","title":"New User Initial State"},"returning_user_initial_state":{"type":"string","title":"Returning User Initial State"},"terminal_state":{"type":"string","title":"Terminal State"},"global_intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Intra State Navigation Guidelines"},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines"},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints"},"topology_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topology Description"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","context_graph_id","version","description","states","new_user_initial_state","returning_user_initial_state","terminal_state","global_intra_state_navigation_guidelines","global_action_guidelines","global_boundary_constraints","topology_description","created_at","updated_at"],"title":"ContextGraphVersionResponse"},"ContextGraphState-Output":{"oneOf":[{"$ref":"#/components/schemas/ActionState-Output"},{"$ref":"#/components/schemas/DecisionState-Output"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState-Output"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState-Output","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState-Output","decision":"#/components/schemas/DecisionState-Output"}}},"ActionState-Output":{"properties":{"type":{"type":"string","const":"action","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Intra State Navigation Guidelines"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines"},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"action_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Action Tool Call Specs","default":[]},"exit_condition_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Exit Condition Tool Call Specs","default":[]},"escalation_config":{"anyOf":[{"$ref":"#/components/schemas/StateRiskOverride"},{"type":"null"}]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"surface_spec_template":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Surface Spec Template"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"preload":{"items":{"$ref":"#/components/schemas/PreloadSpec"},"type":"array","maxItems":20,"title":"Preload"}},"type":"object","required":["type","name","objective","actions","intra_state_navigation_guidelines","action_guidelines","boundary_constraints","exit_conditions"],"title":"ActionState","description":"User-facing engagement state with actions and exit conditions."},"DecisionState-Output":{"properties":{"type":{"type":"string","const":"decision","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"decision_guidelines":{"items":{"type":"string"},"type":"array","title":"Decision Guidelines","default":[]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]}},"type":"object","required":["type","name","objective","exit_conditions"],"title":"DecisionState","description":"Passthrough routing state — Agent picks an exit condition, no user interaction."},"DataCollectionState-Output":{"properties":{"type":{"type":"string","const":"data_collection","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"fields":{"items":{"$ref":"#/components/schemas/CollectionField"},"type":"array","title":"Fields"},"on_complete":{"type":"string","title":"On Complete"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"surface_fallback":{"type":"boolean","title":"Surface Fallback","default":false},"surface_fallback_after_turns":{"type":"integer","title":"Surface Fallback After Turns","default":6},"max_turns":{"type":"integer","title":"Max Turns","default":10},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]}},"type":"object","required":["type","name","objective","fields","on_complete"],"title":"DataCollectionState","description":"Structured voice/text data collection with field tracking.\n\nThe engine presents fields conversationally, tracks completion, and\noptionally falls back to a Surface form after N turns. Each collected\nfield produces a world.event with confidence 0.5."}}},"paths":{"/v1/{workspace_id}/context-graphs/{context_graph_id}/versions":{"post":{"tags":["Context Graphs"],"summary":"Create a context graph version","description":"Create a new version of a context graph. Version number is auto-incremented. Requires `ContextGraph.create` permission for the first version and `ContextGraph.update` permission afterward.","operationId":"create-context_graph-version","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"context_graph_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Context Graph Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContextGraphVersionRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextGraphVersionResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"409":{"description":"Name already taken."},"422":{"description":"Invalid request body."}}}}}}
```

## Get a context graph version

> Retrieve a specific context graph version by number, or 'latest'. Requires \`ContextGraph.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ContextGraphVersionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"version":{"type":"integer","title":"Version"},"description":{"type":"string","title":"Description"},"states":{"items":{"$ref":"#/components/schemas/ContextGraphState-Output"},"type":"array","title":"States"},"new_user_initial_state":{"type":"string","title":"New User Initial State"},"returning_user_initial_state":{"type":"string","title":"Returning User Initial State"},"terminal_state":{"type":"string","title":"Terminal State"},"global_intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Intra State Navigation Guidelines"},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines"},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints"},"topology_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topology Description"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","context_graph_id","version","description","states","new_user_initial_state","returning_user_initial_state","terminal_state","global_intra_state_navigation_guidelines","global_action_guidelines","global_boundary_constraints","topology_description","created_at","updated_at"],"title":"ContextGraphVersionResponse"},"ContextGraphState-Output":{"oneOf":[{"$ref":"#/components/schemas/ActionState-Output"},{"$ref":"#/components/schemas/DecisionState-Output"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState-Output"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState-Output","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState-Output","decision":"#/components/schemas/DecisionState-Output"}}},"ActionState-Output":{"properties":{"type":{"type":"string","const":"action","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"intra_state_navigation_guidelines":{"items":{"type":"string"},"type":"array","title":"Intra State Navigation Guidelines"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines"},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"action_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Action Tool Call Specs","default":[]},"exit_condition_tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Exit Condition Tool Call Specs","default":[]},"escalation_config":{"anyOf":[{"$ref":"#/components/schemas/StateRiskOverride"},{"type":"null"}]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"surface_spec_template":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Surface Spec Template"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"preload":{"items":{"$ref":"#/components/schemas/PreloadSpec"},"type":"array","maxItems":20,"title":"Preload"}},"type":"object","required":["type","name","objective","actions","intra_state_navigation_guidelines","action_guidelines","boundary_constraints","exit_conditions"],"title":"ActionState","description":"User-facing engagement state with actions and exit conditions."},"Action":{"properties":{"description":{"type":"string","title":"Description"},"filler_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Hint"}},"type":"object","required":["description"],"title":"Action","description":"A single action the agent can take within a state."},"ExitCondition":{"properties":{"description":{"type":"string","title":"Description"},"next_state":{"type":"string","title":"Next State"},"filler_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Hint"}},"type":"object","required":["description","next_state"],"title":"ExitCondition"},"ToolCallSpec":{"properties":{"tool_id":{"type":"string","title":"Tool Id"},"additional_instruction":{"type":"string","title":"Additional Instruction","default":""},"navigate_on_completion":{"type":"boolean","title":"Navigate On Completion","default":false},"progress":{"anyOf":[{"$ref":"#/components/schemas/ProgressHint"},{"type":"null"}]},"result_persistence":{"type":"string","enum":["accumulate","override"],"title":"Result Persistence","default":"accumulate"},"audio_fillers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Audio Fillers"},"audio_filler_triggered_after":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Filler Triggered After"}},"type":"object","required":["tool_id"],"title":"ToolCallSpec","description":"A tool call that the agent can make in a state."},"ProgressHint":{"properties":{"deterministic":{"type":"boolean","title":"Deterministic","default":false},"phrases":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"description":"Filler phrases. deterministic=true: played verbatim in order. deterministic=false: used as hints for early attempts."},{"type":"null"}],"title":"Phrases"},"trigger_delay_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":0},{"type":"null"}],"title":"Trigger Delay Ms"},"interval_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":100},{"type":"null"}],"title":"Interval Ms"},"mode":{"type":"string","enum":["auto","silent","backchannel","verbal"],"title":"Mode","default":"auto"},"progress_class":{"anyOf":[{"type":"string","enum":["lookup","write","external_call","compute","multi_step"]},{"type":"null"}],"title":"Progress Class"},"expected_latency_ms":{"anyOf":[{"type":"integer","maximum":60000,"minimum":0},{"type":"null"}],"title":"Expected Latency Ms"},"custom_phrase":{"anyOf":[{"type":"string","maxLength":500,"description":"Legacy: use phrases instead."},{"type":"null"}],"title":"Custom Phrase"}},"additionalProperties":false,"type":"object","title":"ProgressHint","description":"How the agent narrates waiting on a tool.\n\n``deterministic=true``: scripted — ``phrases`` play verbatim in order.\n``deterministic=false``: engine picks — ``phrases`` are hints.\n``trigger_delay_ms``: milliseconds before first filler (0 = immediate).\n``interval_ms``: milliseconds between subsequent fillers."},"StateRiskOverride":{"properties":{"topic_risk_score":{"type":"number","title":"Topic Risk Score","default":0},"auto_escalate_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Auto Escalate Threshold"},"max_loop_count":{"type":"integer","title":"Max Loop Count","default":3},"operator_skill":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Skill"}},"type":"object","title":"StateRiskOverride","description":"Per-state escalation tuning. Stored on ActionState."},"Guardrail":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":1000,"title":"Description"},"enforcement":{"type":"string","enum":["hard","soft"],"title":"Enforcement","default":"hard"}},"type":"object","required":["name","description"],"title":"Guardrail","description":"Typed safety rule enforced per-state (not just global freetext guidelines)."},"ChannelOverride":{"properties":{"objective":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Objective"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"progress":{"anyOf":[{"$ref":"#/components/schemas/ProgressHint"},{"type":"null"}]}},"type":"object","title":"ChannelOverride","description":"Per-channel behavior override for a state."},"TurnPolicy":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","summarize","compact"],"title":"Context Strategy","default":"full"},"degradation_threshold":{"type":"integer","minimum":-1,"title":"Degradation Threshold","default":-1},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","minimum":-1,"title":"Block Forward Call After Turns","default":-1},"stt_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Eot Threshold"},"stt_eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Eager Eot Threshold"},"stt_eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stt Eot Timeout Ms"}},"type":"object","title":"TurnPolicy","description":"Voice pipeline parameters declared per HSM state.\n\nLives on ActionState/DecisionState alongside guardrails, wait_for, and\nchannel_overrides.  The HSM state IS the policy — no shadow state machine.\nAll fields optional with safe defaults (production behavior unchanged\nwhen no turn_policy is set)."},"PreloadSpec":{"properties":{"tool_id":{"type":"string","maxLength":256,"title":"Tool Id"},"params":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Params"}},"type":"object","required":["tool_id"],"title":"PreloadSpec","description":"A tool call executed deterministically by the engine on state entry.\n\nUnlike LLM-driven tool calls, preloads run before any LLM turn —\nthe results appear in the interaction log so the engage LLM sees\nthem as pre-loaded context.  All preloads in a state execute in\nparallel.  Param values support ``{caller_mrn}`` and ``{entity_id}``\ntemplate variables resolved from the session's caller context."},"DecisionState-Output":{"properties":{"type":{"type":"string","const":"decision","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"exit_conditions":{"items":{"$ref":"#/components/schemas/ExitCondition"},"type":"array","title":"Exit Conditions"},"decision_guidelines":{"items":{"type":"string"},"type":"array","title":"Decision Guidelines","default":[]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]},"wait_for":{"anyOf":[{"type":"string","enum":["surface_submission","human_approval"]},{"type":"null"}],"title":"Wait For"},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]}},"type":"object","required":["type","name","objective","exit_conditions"],"title":"DecisionState","description":"Passthrough routing state — Agent picks an exit condition, no user interaction."},"AnnotationState":{"properties":{"type":{"type":"string","const":"annotation","title":"Type"},"name":{"type":"string","title":"Name"},"inner_thought":{"type":"string","title":"Inner Thought"},"next_state":{"type":"string","title":"Next State"}},"type":"object","required":["type","name","inner_thought","next_state"],"title":"AnnotationState","description":"Injects a hardcoded inner thought (no LLM call)."},"DataCollectionState-Output":{"properties":{"type":{"type":"string","const":"data_collection","title":"Type"},"name":{"type":"string","title":"Name"},"objective":{"type":"string","title":"Objective"},"fields":{"items":{"$ref":"#/components/schemas/CollectionField"},"type":"array","title":"Fields"},"on_complete":{"type":"string","title":"On Complete"},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"surface_fallback":{"type":"boolean","title":"Surface Fallback","default":false},"surface_fallback_after_turns":{"type":"integer","title":"Surface Fallback After Turns","default":6},"max_turns":{"type":"integer","title":"Max Turns","default":10},"guardrails":{"items":{"$ref":"#/components/schemas/Guardrail"},"type":"array","title":"Guardrails","default":[]},"channel_overrides":{"additionalProperties":{"$ref":"#/components/schemas/ChannelOverride"},"type":"object","title":"Channel Overrides"},"turn_policy":{"anyOf":[{"$ref":"#/components/schemas/TurnPolicy"},{"type":"null"}]},"tool_call_specs":{"items":{"$ref":"#/components/schemas/ToolCallSpec"},"type":"array","title":"Tool Call Specs","default":[]}},"type":"object","required":["type","name","objective","fields","on_complete"],"title":"DataCollectionState","description":"Structured voice/text data collection with field tracking.\n\nThe engine presents fields conversationally, tracks completion, and\noptionally falls back to a Surface form after N turns. Each collected\nfield produces a world.event with confidence 0.5."},"CollectionField":{"properties":{"key":{"type":"string","title":"Key"},"type":{"type":"string","title":"Type"},"label":{"type":"string","title":"Label"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"validation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation"},"ask_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ask Prompt"},"fhir_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Path"}},"type":"object","required":["key","type","label"],"title":"CollectionField","description":"A single field to collect during a data collection state."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/context-graphs/{context_graph_id}/versions/{version}":{"get":{"tags":["Context Graphs"],"summary":"Get a context graph version","description":"Retrieve a specific context graph version by number, or 'latest'. Requires `ContextGraph.view` permission.","operationId":"get-context_graph-version","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"context_graph_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Context Graph Id"}},{"name":"version","in":"path","required":true,"schema":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextGraphVersionResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/context-graphs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.