# 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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Version"},"state_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"State Count"},"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":"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":20,"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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Version"},"state_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"State Count"},"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."}}}}}}
```

## 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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Version"},"state_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"State Count"},"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":"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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"latest_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Version"},"state_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"State Count"},"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":"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":"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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"context_graph_id":{"type":"string","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"},{"$ref":"#/components/schemas/DecisionState"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState","decision":"#/components/schemas/DecisionState"}}},"ActionState":{"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"}]}},"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":""}},"type":"object","required":["tool_id"],"title":"ToolCallSpec","description":"A tool call that the agent can make in a state."},"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":[]},"suppress_filler":{"type":"boolean","title":"Suppress Filler","default":false}},"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)."},"DecisionState":{"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":{"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":"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":20,"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.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":{"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"},{"$ref":"#/components/schemas/DecisionState"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState","decision":"#/components/schemas/DecisionState"}}},"ActionState":{"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"}]}},"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":""}},"type":"object","required":["tool_id"],"title":"ToolCallSpec","description":"A tool call that the agent can make in a state."},"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":[]},"suppress_filler":{"type":"boolean","title":"Suppress Filler","default":false}},"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)."},"DecisionState":{"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":{"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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"context_graph_id":{"type":"string","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"},{"$ref":"#/components/schemas/DecisionState"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState","decision":"#/components/schemas/DecisionState"}}}}},"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.update` permission.","operationId":"create-context_graph-version","parameters":[{"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","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"context_graph_id":{"type":"string","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"},{"$ref":"#/components/schemas/DecisionState"},{"$ref":"#/components/schemas/AnnotationState"},{"$ref":"#/components/schemas/DataCollectionState"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionState","annotation":"#/components/schemas/AnnotationState","data_collection":"#/components/schemas/DataCollectionState","decision":"#/components/schemas/DecisionState"}}},"ActionState":{"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"}]}},"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":""}},"type":"object","required":["tool_id"],"title":"ToolCallSpec","description":"A tool call that the agent can make in a state."},"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":[]},"suppress_filler":{"type":"boolean","title":"Suppress Filler","default":false}},"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)."},"DecisionState":{"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":{"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":"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"}}}}}}}}}
```