> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/api-reference/readme/platform/models.md). # Models ## The AccessReviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AccessReviewResponse":{"properties":{"generated_at":{"type":"string","title":"Generated At"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"credentials":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Credentials"},"total_credentials":{"type":"integer","title":"Total Credentials"},"jwt_credentials_note":{"type":"string","title":"Jwt Credentials Note"}},"type":"object","required":["generated_at","workspace_id","credentials","total_credentials","jwt_credentials_note"],"title":"AccessReviewResponse"}}}} ``` ## The Action object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."}}}} ``` ## The ActionState-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ActionState-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ActiveEscalationItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ActiveEscalationItem":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id","description":"Escalation event ID"},"status":{"type":"string","maxLength":64,"title":"Status","description":"Current escalation state"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"What triggered the escalation"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source","description":"Source system of the trigger"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept","description":"Clinical concept that triggered escalation"},"operator_type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Operator Type","description":"Required operator specialization"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis","description":"Regulatory reason for escalation"},"immediate":{"type":"boolean","title":"Immediate","description":"Whether the escalation requires immediate attention"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score","description":"Risk score 0.0 to 1.0"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At","description":"ISO-8601 timestamp when escalation was requested"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At","description":"ISO-8601 timestamp when operator connected"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds","description":"Seconds the caller waited for an operator"},"operator_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Operator Entity Id","description":"Entity ID of the connected operator"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"ISO-8601 timestamp when the call started"}},"type":"object","required":["call_entity_id","status","immediate"],"title":"ActiveEscalationItem","description":"A call with an active escalation, enriched from projected state."}}}} ``` ## The ActiveEscalationListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ActiveEscalationListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ActiveEscalationItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ActiveEscalationListResponse"},"ActiveEscalationItem":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id","description":"Escalation event ID"},"status":{"type":"string","maxLength":64,"title":"Status","description":"Current escalation state"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"What triggered the escalation"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source","description":"Source system of the trigger"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept","description":"Clinical concept that triggered escalation"},"operator_type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Operator Type","description":"Required operator specialization"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis","description":"Regulatory reason for escalation"},"immediate":{"type":"boolean","title":"Immediate","description":"Whether the escalation requires immediate attention"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score","description":"Risk score 0.0 to 1.0"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At","description":"ISO-8601 timestamp when escalation was requested"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At","description":"ISO-8601 timestamp when operator connected"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds","description":"Seconds the caller waited for an operator"},"operator_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Operator Entity Id","description":"Entity ID of the connected operator"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"ISO-8601 timestamp when the call started"}},"type":"object","required":["call_entity_id","status","immediate"],"title":"ActiveEscalationItem","description":"A call with an active escalation, enriched from projected state."}}}} ``` ## The ActiveSession object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ActiveSession":{"properties":{"call_sid":{"type":"string","title":"Call Sid"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id"},"caller_id":{"type":"string","title":"Caller Id"},"direction":{"type":"string","title":"Direction"},"duration_seconds":{"type":"number","title":"Duration Seconds"},"current_state":{"type":"string","title":"Current State","default":""},"scenario":{"type":"string","title":"Scenario","default":""}},"type":"object","required":["call_sid","caller_id","direction","duration_seconds"],"title":"ActiveSession"}}}} ``` ## The AddColumnAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AddColumnAction":{"properties":{"op":{"type":"string","const":"add_column","title":"Op"},"column":{"$ref":"#/components/schemas/Column-Input"}},"type":"object","required":["op","column"],"title":"AddColumnAction"},"Column-Input":{"properties":{"name":{"$ref":"#/components/schemas/IdentifierString"},"type":{"$ref":"#/components/schemas/ColumnType"},"nullable":{"type":"boolean","title":"Nullable","default":true},"default":{"anyOf":[{"$ref":"#/components/schemas/Default"},{"type":"null"}]}},"type":"object","required":["name","type"],"title":"Column"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]},"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"}}}} ``` ## The AddIndexAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AddIndexAction":{"properties":{"op":{"type":"string","const":"add_index","title":"Op"},"index_name":{"$ref":"#/components/schemas/IdentifierString"},"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"}},"type":"object","required":["op","index_name","columns"],"title":"AddIndexAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The AddUniqueAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AddUniqueAction":{"properties":{"op":{"type":"string","const":"add_unique","title":"Op"},"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"},"constraint_name":{"anyOf":[{"$ref":"#/components/schemas/IdentifierString"},{"type":"null"}]}},"type":"object","required":["op","columns"],"title":"AddUniqueAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The AgentAnalyticsEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentAnalyticsEntry":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"agent_name":{"type":"string","title":"Agent Name"},"total_calls":{"type":"integer","title":"Total Calls"},"completed_calls":{"type":"integer","title":"Completed Calls"},"avg_duration_seconds":{"type":"number","title":"Avg Duration Seconds"},"completion_rate":{"type":"number","title":"Completion Rate"}},"type":"object","required":["agent_id","agent_name","total_calls","completed_calls","avg_duration_seconds","completion_rate"],"title":"AgentAnalyticsEntry"}}}} ``` ## The AgentAnalyticsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentAnalyticsResponse":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/AgentAnalyticsEntry"},"type":"array","title":"Agents"},"period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period"}},"type":"object","required":["agents"],"title":"AgentAnalyticsResponse"},"AgentAnalyticsEntry":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"agent_name":{"type":"string","title":"Agent Name"},"total_calls":{"type":"integer","title":"Total Calls"},"completed_calls":{"type":"integer","title":"Completed Calls"},"avg_duration_seconds":{"type":"number","title":"Avg Duration Seconds"},"completion_rate":{"type":"number","title":"Completion Rate"}},"type":"object","required":["agent_id","agent_name","total_calls","completed_calls","avg_duration_seconds","completion_rate"],"title":"AgentAnalyticsEntry"}}}} ``` ## The AgentIdentity object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentIdentity":{"properties":{"entry_actor_name":{"type":"string","title":"Entry Actor Name","default":""},"name":{"type":"string","title":"Name","default":""},"role":{"type":"string","title":"Role","default":""},"developed_by":{"type":"string","title":"Developed By","default":""},"instructions":{"type":"string","title":"Instructions","default":""},"initial_state":{"type":"string","title":"Initial State","default":""}},"type":"object","title":"AgentIdentity","description":"Who the agent IS — platform-authored only; ``None`` for native runs\n(a customer's own definition carries its own identity). Named\n``AgentIdentity`` (not ``Identity``) to avoid colliding with the existing\n``config.models.Identity`` OpenAPI schema (a same-name collision would\nforce-rename that shipped schema — a breaking spec change)."}}}} ``` ## The AgentListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AgentResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"AgentListResponse"},"AgentResponse":{"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},"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":"AgentResponse"}}}} ``` ## The AgentResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentResponse":{"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},"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":"AgentResponse"}}}} ``` ## The AgentVersion object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentVersion":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"version":{"type":"integer","title":"Version"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"initials":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initials"},"identity":{"$ref":"#/components/schemas/Identity"},"background":{"type":"string","title":"Background"},"behaviors":{"items":{"type":"string"},"type":"array","title":"Behaviors"},"communication_patterns":{"items":{"type":"string"},"type":"array","title":"Communication Patterns"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/VoiceConfig"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","agent_id","version","identity","background","behaviors","communication_patterns"],"title":"AgentVersion","description":"A version of an Agent document."},"Identity":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"default_spoken_language":{"type":"string","title":"Default Spoken Language"},"relationship_to_developer":{"$ref":"#/components/schemas/RelationshipToDeveloper"}},"type":"object","required":["name","role","developed_by","default_spoken_language"],"title":"Identity"},"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"},"VoiceConfig":{"properties":{"voice_id":{"type":"string","title":"Voice Id"},"stability":{"type":"number","title":"Stability","default":0},"similarity_boost":{"type":"number","title":"Similarity Boost","default":0},"style":{"type":"number","title":"Style","default":0},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"}},"type":"object","required":["voice_id"],"title":"VoiceConfig"},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The AgentVersionListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentVersionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AgentVersionResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"AgentVersionListResponse"},"AgentVersionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"version":{"type":"integer","title":"Version"},"name":{"type":"string","title":"Name"},"initials":{"type":"string","title":"Initials"},"identity":{"$ref":"#/components/schemas/Identity"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/VoiceConfig"},{"type":"null"}]},"background":{"type":"string","title":"Background"},"behaviors":{"items":{"type":"string"},"type":"array","title":"Behaviors"},"communication_patterns":{"items":{"type":"string"},"type":"array","title":"Communication Patterns"},"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","agent_id","version","name","initials","identity","voice_config","background","behaviors","communication_patterns","created_at","updated_at"],"title":"AgentVersionResponse"},"Identity":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"default_spoken_language":{"type":"string","title":"Default Spoken Language"},"relationship_to_developer":{"$ref":"#/components/schemas/RelationshipToDeveloper"}},"type":"object","required":["name","role","developed_by","default_spoken_language"],"title":"Identity"},"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"},"VoiceConfig":{"properties":{"voice_id":{"type":"string","title":"Voice Id"},"stability":{"type":"number","title":"Stability","default":0},"similarity_boost":{"type":"number","title":"Similarity Boost","default":0},"style":{"type":"number","title":"Style","default":0},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"}},"type":"object","required":["voice_id"],"title":"VoiceConfig"},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The AgentVersionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentVersionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"version":{"type":"integer","title":"Version"},"name":{"type":"string","title":"Name"},"initials":{"type":"string","title":"Initials"},"identity":{"$ref":"#/components/schemas/Identity"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/VoiceConfig"},{"type":"null"}]},"background":{"type":"string","title":"Background"},"behaviors":{"items":{"type":"string"},"type":"array","title":"Behaviors"},"communication_patterns":{"items":{"type":"string"},"type":"array","title":"Communication Patterns"},"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","agent_id","version","name","initials","identity","voice_config","background","behaviors","communication_patterns","created_at","updated_at"],"title":"AgentVersionResponse"},"Identity":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"default_spoken_language":{"type":"string","title":"Default Spoken Language"},"relationship_to_developer":{"$ref":"#/components/schemas/RelationshipToDeveloper"}},"type":"object","required":["name","role","developed_by","default_spoken_language"],"title":"Identity"},"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"},"VoiceConfig":{"properties":{"voice_id":{"type":"string","title":"Voice Id"},"stability":{"type":"number","title":"Stability","default":0},"similarity_boost":{"type":"number","title":"Similarity Boost","default":0},"style":{"type":"number","title":"Style","default":0},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"}},"type":"object","required":["voice_id"],"title":"VoiceConfig"},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The AlterAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AlterAction":{"anyOf":[{"$ref":"#/components/schemas/AddColumnAction"},{"$ref":"#/components/schemas/DropColumnAction"},{"$ref":"#/components/schemas/RenameColumnAction"},{"$ref":"#/components/schemas/ChangeColumnTypeAction"},{"$ref":"#/components/schemas/SetColumnNullableAction"},{"$ref":"#/components/schemas/SetColumnDefaultAction"},{"$ref":"#/components/schemas/DropColumnDefaultAction"},{"$ref":"#/components/schemas/AddUniqueAction"},{"$ref":"#/components/schemas/DropConstraintAction"},{"$ref":"#/components/schemas/AddIndexAction"},{"$ref":"#/components/schemas/DropIndexAction"}]},"AddColumnAction":{"properties":{"op":{"type":"string","const":"add_column","title":"Op"},"column":{"$ref":"#/components/schemas/Column-Input"}},"type":"object","required":["op","column"],"title":"AddColumnAction"},"Column-Input":{"properties":{"name":{"$ref":"#/components/schemas/IdentifierString"},"type":{"$ref":"#/components/schemas/ColumnType"},"nullable":{"type":"boolean","title":"Nullable","default":true},"default":{"anyOf":[{"$ref":"#/components/schemas/Default"},{"type":"null"}]}},"type":"object","required":["name","type"],"title":"Column"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]},"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"},"DropColumnAction":{"properties":{"op":{"type":"string","const":"drop_column","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropColumnAction"},"RenameColumnAction":{"properties":{"op":{"type":"string","const":"rename_column","title":"Op"},"from":{"$ref":"#/components/schemas/IdentifierString"},"to":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","from","to"],"title":"RenameColumnAction"},"ChangeColumnTypeAction":{"properties":{"op":{"type":"string","const":"change_column_type","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"new_type":{"$ref":"#/components/schemas/ColumnType"}},"type":"object","required":["op","name","new_type"],"title":"ChangeColumnTypeAction"},"SetColumnNullableAction":{"properties":{"op":{"type":"string","const":"set_column_nullable","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"nullable":{"type":"boolean","title":"Nullable"}},"type":"object","required":["op","name","nullable"],"title":"SetColumnNullableAction"},"SetColumnDefaultAction":{"properties":{"op":{"type":"string","const":"set_column_default","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"default":{"$ref":"#/components/schemas/Default"}},"type":"object","required":["op","name","default"],"title":"SetColumnDefaultAction"},"DropColumnDefaultAction":{"properties":{"op":{"type":"string","const":"drop_column_default","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropColumnDefaultAction"},"AddUniqueAction":{"properties":{"op":{"type":"string","const":"add_unique","title":"Op"},"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"},"constraint_name":{"anyOf":[{"$ref":"#/components/schemas/IdentifierString"},{"type":"null"}]}},"type":"object","required":["op","columns"],"title":"AddUniqueAction"},"DropConstraintAction":{"properties":{"op":{"type":"string","const":"drop_constraint","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropConstraintAction"},"AddIndexAction":{"properties":{"op":{"type":"string","const":"add_index","title":"Op"},"index_name":{"$ref":"#/components/schemas/IdentifierString"},"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"}},"type":"object","required":["op","index_name","columns"],"title":"AddIndexAction"},"DropIndexAction":{"properties":{"op":{"type":"string","const":"drop_index","title":"Op"},"index_name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","index_name"],"title":"DropIndexAction"}}}} ``` ## The AnalyticsDashboardResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AnalyticsDashboardResponse":{"properties":{"call_volume":{"$ref":"#/components/schemas/AnalyticsKpi","description":"Total calls in the period"},"avg_quality":{"$ref":"#/components/schemas/AnalyticsKpi","description":"Average quality score (0-100); higher is better"},"avg_ttfb_ms":{"$ref":"#/components/schemas/AnalyticsKpi","description":"Average audio time-to-first-byte in ms; lower is better"},"escalation_rate":{"$ref":"#/components/schemas/AnalyticsKpi","description":"Fraction of calls escalated; lower is better"},"tool_success_rate":{"$ref":"#/components/schemas/AnalyticsKpi","description":"Fraction of tool calls that succeeded; higher is better"},"avg_duration_s":{"$ref":"#/components/schemas/AnalyticsKpi","description":"Average call duration in seconds"},"period_days":{"type":"integer","title":"Period Days","description":"Length of the reporting period in days"}},"type":"object","required":["call_volume","avg_quality","avg_ttfb_ms","escalation_rate","tool_success_rate","avg_duration_s","period_days"],"title":"AnalyticsDashboardResponse","description":"Composite dashboard — six headline KPIs, each with a delta, plus the period length.\n\nHigher-is-better for ``call_volume``, ``avg_quality``, ``tool_success_rate``;\nhigher-is-worse for ``escalation_rate``, ``avg_ttfb_ms``, ``avg_duration_s``.\nConsumers must color deltas by that per-KPI polarity, not by delta sign alone."},"AnalyticsKpi":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Current-period value (None when no data)"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta Pct","description":"Percent change vs the previous period, or None"}},"type":"object","title":"AnalyticsKpi","description":"A single headline KPI with its period-over-period change.\n\n``value`` is left broad (int for counts, float for rates/scores/durations,\n``None`` when the metric has no data for the period). ``delta_pct`` is the\nsigned percent change vs the previous equal-length period, or ``None`` when\na prior-period comparison is unavailable."}}}} ``` ## The AnalyticsKpi object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AnalyticsKpi":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Current-period value (None when no data)"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta Pct","description":"Percent change vs the previous period, or None"}},"type":"object","title":"AnalyticsKpi","description":"A single headline KPI with its period-over-period change.\n\n``value`` is left broad (int for counts, float for rates/scores/durations,\n``None`` when the metric has no data for the period). ``delta_pct`` is the\nsigned percent change vs the previous equal-length period, or ``None`` when\na prior-period comparison is unavailable."}}}} ``` ## The AnnotationState object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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)."}}}} ``` ## The AnyValue object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AnyValue":{"additionalProperties":true,"type":"object"}}}} ``` ## The ApiKeyListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ApiKeyListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ApiKeyResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ApiKeyListResponse"},"ApiKeyResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"created_by_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Credential Id"},"key_id":{"type":"string","title":"Key Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"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","created_by_entity_id","created_by_credential_id","key_id","name","role","permissions","expires_at","last_used_at","created_at","updated_at"],"title":"ApiKeyResponse"}}}} ``` ## The ApiKeyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ApiKeyResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"created_by_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Credential Id"},"key_id":{"type":"string","title":"Key Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"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","created_by_entity_id","created_by_credential_id","key_id","name","role","permissions","expires_at","last_used_at","created_at","updated_at"],"title":"ApiKeyResponse"}}}} ``` ## The AppliedRate object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AppliedRate":{"properties":{"input_rate_effective_from":{"type":"string","format":"date","title":"Input Rate Effective From","description":"Inclusive first usage date for the input rate."},"input_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Input Rate Effective To","description":"Exclusive end usage date for the input rate; null means no end date."},"output_rate_effective_from":{"type":"string","format":"date","title":"Output Rate Effective From","description":"Inclusive first usage date for the output rate."},"output_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Output Rate Effective To","description":"Exclusive end usage date for the output rate; null means no end date."},"cached_rate_effective_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective From","description":"Inclusive first usage date for the cached-input rate; null if no cached rate applied."},"cached_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective To","description":"Exclusive end usage date for the cached-input rate; null if unbounded or no cached rate applied."},"min_input_tokens":{"type":"integer","title":"Min Input Tokens","description":"Inclusive lower bound on per-request context input tokens for the input-rate band."},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens","description":"Inclusive upper bound on per-request context input tokens; null means unbounded."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["input_rate_effective_from","input_rate_effective_to","output_rate_effective_from","output_rate_effective_to","cached_rate_effective_from","cached_rate_effective_to","min_input_tokens","max_input_tokens","input_per_million","cached_input_per_million","output_per_million"],"title":"AppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The ArchiveResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ArchiveResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"type":"string","const":"archived","title":"Status"}},"type":"object","required":["surface_id","status"],"title":"ArchiveResponse"}}}} ``` ## The ArchiveWorkspaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ArchiveWorkspaceRequest":{"properties":{"slug":{"$ref":"#/components/schemas/SlugString"}},"type":"object","required":["slug"],"title":"ArchiveWorkspaceRequest"},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"}}}} ``` ## The AuditEventsListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditEventsListResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/src__routes__audit__AuditEventResponse"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["events","total","limit","offset","has_more"],"title":"AuditEventsListResponse"},"src__routes__audit__AuditEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"title":"AuditEventResponse"}}}} ``` ## The AuditExportChunk object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditExportChunk":{"properties":{"chunk_index":{"type":"integer","title":"Chunk Index"},"row_count":{"type":"integer","title":"Row Count"},"byte_count":{"type":"integer","title":"Byte Count"},"external_link":{"type":"string","title":"External Link","description":"Short-lived presigned URL — download directly, do not proxy."},"expiration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expiration","description":"ISO-8601 expiry of the presigned link."}},"type":"object","required":["chunk_index","row_count","byte_count","external_link"],"title":"AuditExportChunk"}}}} ``` ## The AuditExportRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditExportRequest":{"properties":{"date_from":{"type":"string","format":"date-time","title":"Date From"},"date_to":{"type":"string","format":"date-time","title":"Date To"},"service":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Service","description":"Filter by service name."},"action":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Action","description":"Filter by action type."},"phi_only":{"type":"boolean","title":"Phi Only","default":false}},"type":"object","required":["date_from","date_to"],"title":"AuditExportRequest"}}}} ``` ## The AuditExportResultResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditExportResultResponse":{"properties":{"statement_id":{"type":"string","title":"Statement Id"},"status":{"type":"string","enum":["pending","ready"],"title":"Status"},"result_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Format","description":"Result file format (CSV)."},"total_row_count":{"type":"integer","title":"Total Row Count","default":0},"chunks":{"items":{"$ref":"#/components/schemas/AuditExportChunk"},"type":"array","title":"Chunks"}},"type":"object","required":["statement_id","status"],"title":"AuditExportResultResponse"},"AuditExportChunk":{"properties":{"chunk_index":{"type":"integer","title":"Chunk Index"},"row_count":{"type":"integer","title":"Row Count"},"byte_count":{"type":"integer","title":"Byte Count"},"external_link":{"type":"string","title":"External Link","description":"Short-lived presigned URL — download directly, do not proxy."},"expiration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expiration","description":"ISO-8601 expiry of the presigned link."}},"type":"object","required":["chunk_index","row_count","byte_count","external_link"],"title":"AuditExportChunk"}}}} ``` ## The AuditExportSubmitResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditExportSubmitResponse":{"properties":{"statement_id":{"type":"string","title":"Statement Id","description":"Databricks statement handle — poll GET /export/{statement_id} for links."},"status":{"type":"string","enum":["pending","ready"],"title":"Status","description":"pending: still running. ready: links available immediately."}},"type":"object","required":["statement_id","status"],"title":"AuditExportSubmitResponse"}}}} ``` ## The AuditLogListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditLogListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/src__routes__operators_models__AuditEventResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"AuditLogListResponse"},"src__routes__operators_models__AuditEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"event_type":{"type":"string","title":"Event Type","description":"Audit event type (e.g. operator.status_change)"},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Audit payload — shape varies by event_type"},"source":{"type":"string","title":"Source","description":"System that emitted the event"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At","description":"When the event was ingested"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event occurred"}},"type":"object","required":["id","workspace_id","event_type","data","source"],"title":"AuditEventResponse"}}}} ``` ## The AuditSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditSummary":{"properties":{"event_count":{"type":"integer","title":"Event Count","default":0},"latest_event":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latest Event"}},"type":"object","title":"AuditSummary"}}}} ``` ## The AuditSummaryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuditSummaryResponse":{"properties":{"total_events":{"type":"integer","title":"Total Events"},"phi_access_events":{"type":"integer","title":"Phi Access Events"},"unique_actors":{"type":"integer","title":"Unique Actors"},"services_with_events":{"type":"integer","title":"Services With Events"}},"type":"object","required":["total_events","phi_access_events","unique_actors","services_with_events"],"title":"AuditSummaryResponse"}}}} ``` ## The AuthInfoResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AuthInfoResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"key_id":{"type":"string","title":"Key Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"expires_in_seconds":{"type":"integer","title":"Expires In Seconds"}},"type":"object","required":["workspace_id","key_id","name","expires_at","expires_in_seconds"],"title":"AuthInfoResponse"}}}} ``` ## The AvailabilityDate object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AvailabilityDate":{"properties":{"date":{"type":"string","maxLength":16,"title":"Date"},"slots":{"items":{"$ref":"#/components/schemas/AvailabilitySlot"},"type":"array","maxItems":200,"title":"Slots"}},"type":"object","required":["date"],"title":"AvailabilityDate"},"AvailabilitySlot":{"properties":{"id":{"type":"string","maxLength":128,"title":"Id"},"start":{"type":"string","maxLength":16,"title":"Start"},"end":{"type":"string","maxLength":16,"title":"End"},"provider":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider"}},"type":"object","required":["id","start","end"],"title":"AvailabilitySlot"}}}} ``` ## The AvailabilityResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AvailabilityResponse":{"properties":{"dates":{"items":{"$ref":"#/components/schemas/AvailabilityDate"},"type":"array","maxItems":64,"title":"Dates"}},"type":"object","title":"AvailabilityResponse","description":"Available appointment slots grouped by date."},"AvailabilityDate":{"properties":{"date":{"type":"string","maxLength":16,"title":"Date"},"slots":{"items":{"$ref":"#/components/schemas/AvailabilitySlot"},"type":"array","maxItems":200,"title":"Slots"}},"type":"object","required":["date"],"title":"AvailabilityDate"},"AvailabilitySlot":{"properties":{"id":{"type":"string","maxLength":128,"title":"Id"},"start":{"type":"string","maxLength":16,"title":"Start"},"end":{"type":"string","maxLength":16,"title":"End"},"provider":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider"}},"type":"object","required":["id","start","end"],"title":"AvailabilitySlot"}}}} ``` ## The AvailabilitySlot object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AvailabilitySlot":{"properties":{"id":{"type":"string","maxLength":128,"title":"Id"},"start":{"type":"string","maxLength":16,"title":"Start"},"end":{"type":"string","maxLength":16,"title":"End"},"provider":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider"}},"type":"object","required":["id","start","end"],"title":"AvailabilitySlot"}}}} ``` ## The BackgroundString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BackgroundString":{"type":"string","maxLength":10000}}}} ``` ## The BargeInEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BargeInEvent":{"properties":{"type":{"const":"barge_in","default":"barge_in","title":"Type","type":"string"},"interrupted_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupted Text"},"discarded_texts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Discarded Texts"},"interrupted_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupted Speaker Id"},"interrupting_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupting Speaker Id"},"total_barge_ins":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Barge Ins"}},"title":"BargeInEvent","type":"object"}}}} ``` ## The BatchDetail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BatchDetail":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"batch_id."},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"type":"string","title":"Status","description":"discovered | ready | processing | completed | failed."},"files_found":{"type":"integer","title":"Files Found"},"created_ts":{"type":"string","title":"Created Ts"},"files":{"items":{"$ref":"#/components/schemas/IntakeFileRow"},"type":"array","title":"Files","default":[]}},"type":"object","required":["id","dataset","status","files_found","created_ts"],"title":"BatchDetail"},"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]}}}} ``` ## The BatchProcessingManifest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BatchProcessingManifest":{"properties":{"document_processing":{"additionalProperties":true,"type":"object","title":"Document Processing"},"files":{"items":{"$ref":"#/components/schemas/FileEntry"},"type":"array","title":"Files"}},"type":"object","required":["document_processing","files"],"title":"BatchProcessingManifest","description":"Per-file extraction params for a document batch's still-``received`` files —\nconsumed by the batch-extract job, which runs ONCE per batch and extracts\nevery file (instead of one run-now per file, which blows the request/gateway\ntimeout for large batches). Authenticated by the same short-lived\nworkspace-scoped token as the status write-back. ``document_processing`` is\ndataset-wide (the contract); ``file_type`` is per-file (V265 multi-type).\n\nSource provenance mirrors the single-file path (resolve_source_identity, PHI\ngate): source_file_id/source_url (opaque ids) always populate; source_folder_path\n+ filename (operator-named free text) populate ONLY for contains_phi=false\ndatasets — otherwise they stay None, so PHI never leaves the Lakebase row."},"FileEntry":{"properties":{"file_id":{"type":"string","format":"uuid","title":"File Id"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"},"version":{"type":"integer","title":"Version"},"source_path":{"type":"string","title":"Source Path"},"file_type":{"type":"string","title":"File Type"},"content_type":{"type":"string","title":"Content Type"},"sha256":{"type":"string","title":"Sha256"},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At"},"contract_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contract Id"},"contract_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract Version"},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"}},"type":"object","required":["file_id","version","source_path","file_type","content_type","sha256","size_bytes","ingested_at"],"title":"FileEntry"}}}} ``` ## The BatchRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BatchRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"batch_id."},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"type":"string","title":"Status","description":"discovered | ready | processing | completed | failed."},"files_found":{"type":"integer","title":"Files Found"},"created_ts":{"type":"string","title":"Created Ts"}},"type":"object","required":["id","dataset","status","files_found","created_ts"],"title":"BatchRow","description":"A source-sync batch (Batches list / detail)."}}}} ``` ## The BindingUpsertRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BindingUpsertRequest":{"properties":{"external_integration_id":{"type":"string","format":"uuid","title":"External Integration Id"},"external_subject_key":{"type":"string","maxLength":512,"minLength":1,"title":"External Subject Key"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"source":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Source","deprecated":true},"display_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Display Name"}},"additionalProperties":false,"type":"object","required":["external_integration_id","external_subject_key","entity_id"],"title":"BindingUpsertRequest"}}}} ``` ## The Body\_upload\_intake\_file\_v1\_\_workspace\_id\_\_intake\_files\_post object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Body_upload_intake_file_v1__workspace_id__intake_files_post":{"properties":{"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"}},"type":"object","required":["dataset","file"],"title":"Body_upload_intake_file_v1__workspace_id__intake_files_post"}}}} ``` ## The Body\_voice-turn object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Body_voice-turn":{"properties":{"audio":{"type":"string","contentMediaType":"application/octet-stream","title":"Audio"},"phone_number":{"type":"string","maxLength":16,"pattern":"^\\+[1-9]\\d{1,14}$","title":"Phone Number"}},"type":"object","required":["audio","phone_number"],"title":"Body_voice-turn"}}}} ``` ## The BookingRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BookingRequest":{"properties":{"slot_id":{"type":"string","maxLength":256,"minLength":1,"title":"Slot Id","description":"The FHIR Slot ID to book"}},"type":"object","required":["slot_id"],"title":"BookingRequest"}}}} ``` ## The BookingResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BookingResponse":{"properties":{"status":{"type":"string","const":"pending","title":"Status","description":"Booking lifecycle status."},"message":{"type":"string","maxLength":512,"title":"Message"},"slot_id":{"type":"string","maxLength":256,"title":"Slot Id"}},"type":"object","required":["status","message","slot_id"],"title":"BookingResponse","description":"Acknowledgement returned when a booking request is accepted."}}}} ``` ## The BooleanMetricValueResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BooleanMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"boolean","title":"Metric Type"},"value":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"BooleanMetricValueResponse"}}}} ``` ## The BrandingConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The BrandingSettingsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BrandingSettingsRequest":{"properties":{"branding":{"$ref":"#/components/schemas/BrandingConfig"}},"type":"object","required":["branding"],"title":"BrandingSettingsRequest","description":"Update workspace branding. All fields are optional — only provided\nfields are changed."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The BrandingSettingsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BrandingSettingsResponse":{"properties":{"branding":{"$ref":"#/components/schemas/BrandingConfig"}},"type":"object","required":["branding"],"title":"BrandingSettingsResponse"},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The BridgeRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BridgeRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"objective":{"type":"string","maxLength":2000,"minLength":1,"title":"Objective"},"num_scenarios":{"type":"integer","maximum":50,"minimum":1,"title":"Num Scenarios","default":5},"max_turns":{"type":"integer","maximum":40,"minimum":1,"title":"Max Turns","default":20},"concurrency":{"type":"integer","maximum":20,"minimum":1,"title":"Concurrency","default":3},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Optional world entity UUID to bind caller context for every scenario session created by this bridge run. The value is forwarded to each scenario's session-create call and inherited by any forks; identical precedence rules apply per-session (entity match wins over phone, stale UUID falls back to phone lookup, malformed UUID returns 422). Use this to pin an entire regression suite to a specific test patient."},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"target_spec":{"anyOf":[{"$ref":"#/components/schemas/TargetSpec"},{"type":"null"}]},"exploration":{"anyOf":[{"$ref":"#/components/schemas/ExplorationConfig"},{"type":"null"}]},"auto_target_spec":{"type":"boolean","title":"Auto Target Spec","default":false},"async_generation":{"type":"boolean","title":"Async Generation","default":false}},"type":"object","required":["service_id","objective"],"title":"BridgeRequest"},"TargetSpec":{"properties":{"desired_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Desired States"},"non_desired_states":{"items":{"$ref":"#/components/schemas/NonDesiredState"},"type":"array","maxItems":50,"title":"Non Desired States"},"ordered_pathways":{"items":{"$ref":"#/components/schemas/OrderedPathway"},"type":"array","maxItems":20,"title":"Ordered Pathways"},"completion_criteria":{"$ref":"#/components/schemas/CompletionCriteria"}},"type":"object","title":"TargetSpec"},"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"},"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"},"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"},"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"}}}} ``` ## The BridgeResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BridgeResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"scenarios":{"items":{"$ref":"#/components/schemas/Scenario"},"type":"array","title":"Scenarios"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"inferred_target_spec":{"anyOf":[{"$ref":"#/components/schemas/TargetSpec"},{"type":"null"}]},"inferred_target_spec_rationale":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Inferred Target Spec Rationale"}},"type":"object","required":["run_id","status","scenarios"],"title":"BridgeResponse"},"Scenario":{"properties":{"description":{"type":"string","maxLength":512,"title":"Description"},"temperament":{"type":"string","maxLength":32,"title":"Temperament","default":"neutral"},"initial_message":{"type":"string","maxLength":1000,"title":"Initial Message"},"scenario_instructions":{"type":"string","maxLength":2000,"title":"Scenario Instructions"},"persona":{"$ref":"#/components/schemas/ScenarioPersona"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"}},"type":"object","required":["description","initial_message","scenario_instructions"],"title":"Scenario"},"ScenarioPersona":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name","default":""},"role":{"type":"string","maxLength":64,"title":"Role","default":"patient"},"communication_style":{"type":"string","maxLength":512,"title":"Communication Style","default":""},"default_language":{"type":"string","maxLength":16,"title":"Default Language","default":"en-US"},"background":{"type":"string","maxLength":2000,"title":"Background","default":""}},"type":"object","title":"ScenarioPersona"},"TargetSpec":{"properties":{"desired_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Desired States"},"non_desired_states":{"items":{"$ref":"#/components/schemas/NonDesiredState"},"type":"array","maxItems":50,"title":"Non Desired States"},"ordered_pathways":{"items":{"$ref":"#/components/schemas/OrderedPathway"},"type":"array","maxItems":20,"title":"Ordered Pathways"},"completion_criteria":{"$ref":"#/components/schemas/CompletionCriteria"}},"type":"object","title":"TargetSpec"},"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"},"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"},"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"}}}} ``` ## The BriefResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BriefResponse":{"properties":{"event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Event Id"},"target_entity_id":{"type":"string","format":"uuid","title":"Target Entity Id"},"target_entity_type":{"type":"string","enum":["patient","cohort","workspace","territory","emirate","district"],"title":"Target Entity Type"},"content_md":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Content Md"},"content_json":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Content Json"},"version":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Version"},"evidence_event_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500,"title":"Evidence Event Ids"},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence"},"event_count":{"type":"integer","minimum":0,"title":"Event Count"},"model_name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Model Name"},"truncated":{"type":"boolean","title":"Truncated","default":false},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"}},"type":"object","required":["event_id","target_entity_id","target_entity_type","content_json","confidence","event_count","generated_at"],"title":"BriefResponse","description":"Wire shape for a Self-Image brief.\n\n``event_id`` is null when no brief has ever been generated for the\nentity. All other fields are nullable in that case so the UI can\nrender a consistent empty state."}}}} ``` ## The BriefingRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BriefingRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"}},"type":"object","required":["call_sid"],"title":"BriefingRequest","description":"Request for operator briefing on a specific call."}}}} ``` ## The BriefingResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BriefingResponse":{"properties":{"call_sid":{"type":"string","title":"Call Sid"},"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"sections":{"items":{"$ref":"#/components/schemas/BriefingSection"},"type":"array","title":"Sections"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"}},"type":"object","required":["call_sid","operator_id","sections","generated_at"],"title":"BriefingResponse","description":"Structured operator briefing for a call."},"BriefingSection":{"properties":{"title":{"type":"string","title":"Title"},"content":{"type":"string","title":"Content"}},"type":"object","required":["title","content"],"title":"BriefingSection","description":"A named section of the operator briefing."}}}} ``` ## The BriefingSection object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"BriefingSection":{"properties":{"title":{"type":"string","title":"Title"},"content":{"type":"string","title":"Content"}},"type":"object","required":["title","content"],"title":"BriefingSection","description":"A named section of the operator briefing."}}}} ``` ## The CallDetailResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction"},"status":{"type":"string","title":"Status","default":"completed"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"call_start_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Call Start Time"},"call_end_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Call End Time"},"call_duration_seconds":{"type":"number","title":"Call Duration Seconds","default":0},"media_start_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Media Start Time"},"config":{"anyOf":[{"$ref":"#/components/schemas/ConversationConfig"},{"type":"null"}]},"turns":{"items":{"$ref":"#/components/schemas/Turn"},"type":"array","title":"Turns","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"triggered_behaviors":{"items":{"type":"string"},"type":"array","title":"Triggered Behaviors","default":[]},"completion_reason":{"anyOf":[{"type":"string","enum":["completed","abandoned","escalated","transferred","timeout","error","voicemail","no_answer","caller_hangup","forwarded","terminal_state","warm_transfer_completed","no_inbound_audio","cancelled"]},{"type":"null"}],"title":"Completion Reason"},"emotional_summary":{"anyOf":[{"$ref":"#/components/schemas/EmotionalSummary"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ForwardingDetails"},{"type":"null"}]},"conference_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conference Sid"},"participants":{"items":{"$ref":"#/components/schemas/Participant"},"type":"array","title":"Participants","default":[]},"barge_in_events":{"items":{"$ref":"#/components/schemas/BargeInEvent"},"type":"array","title":"Barge In Events","default":[]},"recording_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recording Path"},"twilio_recording_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twilio Recording Sid"},"twilio_recording_duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Twilio Recording Duration"},"has_recording":{"type":"boolean","title":"Has Recording","default":false},"timeline":{"anyOf":[{"$ref":"#/components/schemas/PlaybackTimeline"},{"type":"null"}]},"call_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Call Analysis"},"source":{"anyOf":[{"type":"string","enum":["real","simulation","playground"]},{"type":"null"}],"title":"Source"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Rationale"},"parent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Session Id"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index"},"escalation":{"anyOf":[{"$ref":"#/components/schemas/EscalationState"},{"type":"null"}]},"safety":{"anyOf":[{"$ref":"#/components/schemas/SafetyState"},{"type":"null"}]},"human_segments":{"items":{"$ref":"#/components/schemas/HumanSegment"},"type":"array","title":"Human Segments","default":[]},"audit":{"anyOf":[{"$ref":"#/components/schemas/AuditSummary"},{"type":"null"}]},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"conversation_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conversation Summary"},"safety_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety Summary"}},"type":"object","required":["id"],"title":"CallDetailResponse","description":"Full call detail — the canonical response for GET /calls/{call_id}.\n\nThis is the single source of truth for the call detail shape. The OpenAPI\nspec is generated from this model. The SDK TypeScript types are generated\nfrom the spec. The developer-console consumes SDK types directly."},"ConversationConfig":{"properties":{"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id"},"agent_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Context Graph Id"},"context_graph_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version"},"initial_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initial State"},"gpt_audio_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gpt Audio Model"},"navigation_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Navigation Model"}},"type":"object","title":"ConversationConfig"},"Turn":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string"},{"type":"null"}],"title":"Id"},"trigger":{"type":"string","title":"Trigger","default":""},"user_transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Transcript"},"agent_transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Transcript"},"agent_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Action"},"interrupted":{"type":"boolean","title":"Interrupted","default":false},"filler_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Type"},"speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker Id"},"speaker_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker Role"},"emotion_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emotion Label"},"emotion_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Emotion Valence"},"compound_emotions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Compound Emotions"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eot Confidence"},"state":{"type":"string","title":"State","default":""},"tool_calls":{"items":{"$ref":"#/components/schemas/ToolCall"},"type":"array","title":"Tool Calls","default":[]},"state_transitions":{"items":{"$ref":"#/components/schemas/StateTransition"},"type":"array","title":"State Transitions","default":[]},"inner_thoughts":{"items":{"type":"string"},"type":"array","title":"Inner Thoughts","default":[]},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp"},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"user_speech_start_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"User Speech Start Ms"},"user_speech_end_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"User Speech End Ms"},"agent_speech_start_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Speech Start Ms"},"agent_speech_end_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Speech End Ms"},"audio_window_start_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window Start Ms"},"audio_window_end_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window End Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Render Ms"},"audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Ttfb Ms"},"signal_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Kind"},"signal_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Source"},"state_before":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Before"},"state_after":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State After"},"primary_effect_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Effect Kind"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"tool_succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tool Succeeded"},"tool_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tool Ms"},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality"},"empathy_tier":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Tier"},"decision_bearing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Decision Bearing"}},"type":"object","title":"Turn"},"ToolCall":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output"},"output_truncated":{"type":"boolean","title":"Output Truncated","default":false},"output_original_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Original Length"},"output_truncated_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Truncated To"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name"},"endpoint_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Name"},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"}},"type":"object","required":["tool_name"],"title":"ToolCall"},"StateTransition":{"properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"previous_state":{"type":"string","title":"Previous State","default":""},"next_state":{"type":"string","title":"Next State","default":""},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"from_state":{"type":"string","title":"From State","readOnly":true},"to_state":{"type":"string","title":"To State","readOnly":true}},"type":"object","required":["from_state","to_state"],"title":"StateTransition"},"EmotionalSummary":{"properties":{"dominant_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dominant Emotion"},"average_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Valence"},"average_arousal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Arousal"},"peak_negative_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Peak Negative Valence"},"peak_negative_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Peak Negative Emotion"},"emotional_shifts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Emotional Shifts"},"final_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Trend"},"segment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Segment Count"},"barge_in_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Barge In Count"},"compound_emotions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Compound Emotions"}},"type":"object","title":"EmotionalSummary"},"ForwardingDetails":{"properties":{"forward_to":{"type":"string","title":"Forward To"},"warm_transfer":{"type":"boolean","title":"Warm Transfer"},"forwarded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Forwarded At"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ForwardingDetails"},"Participant":{"properties":{"participant_id":{"type":"string","title":"Participant Id"},"role":{"type":"string","enum":["caller","agent","operator"],"title":"Role"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"joined_at":{"type":"string","format":"date-time","title":"Joined At"},"left_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Left At"}},"type":"object","required":["participant_id","role","joined_at"],"title":"Participant"},"BargeInEvent":{"properties":{"type":{"const":"barge_in","default":"barge_in","title":"Type","type":"string"},"interrupted_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupted Text"},"discarded_texts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Discarded Texts"},"interrupted_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupted Speaker Id"},"interrupting_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupting Speaker Id"},"total_barge_ins":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Barge Ins"}},"title":"BargeInEvent","type":"object"},"PlaybackTimeline":{"properties":{"turns":{"items":{"$ref":"#/components/schemas/TurnTimeline"},"type":"array","title":"Turns"},"segments":{"items":{"$ref":"#/components/schemas/TimelineSegment"},"type":"array","title":"Segments"},"duration_seconds":{"type":"number","title":"Duration Seconds"},"timebase":{"anyOf":[{"$ref":"#/components/schemas/TimelineTimebase"},{"type":"null"}],"description":"Canonical timebase shared by waveform, overlays, seek state, zoom, and scroll transforms."},"lanes":{"items":{"$ref":"#/components/schemas/TimelineLaneDefinition"},"type":"array","title":"Lanes","description":"Canonical actor/system lane model. Every segment lane_id resolves against this collection.","default":[]},"total_user_speech_seconds":{"type":"number","title":"Total User Speech Seconds","default":0},"total_agent_speech_seconds":{"type":"number","title":"Total Agent Speech Seconds","default":0},"total_silence_seconds":{"type":"number","title":"Total Silence Seconds","default":0},"avg_processing_gap_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Processing Gap Ms"},"max_processing_gap_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Processing Gap Ms"},"avg_perceived_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Perceived Latency Ms"}},"type":"object","required":["turns","segments","duration_seconds"],"title":"PlaybackTimeline"},"TurnTimeline":{"properties":{"turn_index":{"type":"integer","title":"Turn Index"},"seek_to":{"type":"number","title":"Seek To"},"active_start":{"type":"number","title":"Active Start"},"active_end":{"type":"number","title":"Active End"}},"type":"object","required":["turn_index","seek_to","active_start","active_end"],"title":"TurnTimeline"},"TimelineSegment":{"properties":{"type":{"type":"string","enum":["agent_speech","barge_in","caller_speech","filler_hesitation","filler_nav","greeting","interrupted_speech","processing_gap","silence","silence_check","state_transition","tool_call"],"title":"Type"},"lane":{"type":"string","enum":["agent","caller","events","operator","system","tool"],"title":"Lane"},"track":{"anyOf":[{"type":"string","enum":["agent","caller","operator","system","tool"]},{"type":"null"}],"title":"Track","description":"Actor-semantic display track for the segment. Inferred for legacy producers."},"lane_id":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Lane Id","description":"Canonical lane id. Must match PlaybackTimeline.lanes[].id after platform normalization."},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order","description":"Canonical event order after platform time/lane normalization."},"actor":{"anyOf":[{"$ref":"#/components/schemas/TimelineActor"},{"type":"null"}],"description":"Actor responsible for the segment. Inferred for legacy producers."},"start":{"type":"number","title":"Start"},"end":{"type":"number","title":"End"},"label":{"type":"string","title":"Label"},"turn_index":{"type":"integer","title":"Turn Index"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eot Confidence"},"audio_window_start":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window Start"},"audio_window_end":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window End"},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Render Ms"},"audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Ttfb Ms"},"e2e_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"E2E Ttfb Ms"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"parent_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Call Id"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name"},"endpoint_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Name"},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"},"succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Succeeded"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"from_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From State"},"to_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To State"},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valence"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"type":"object","required":["type","lane","start","end","label","turn_index"],"title":"TimelineSegment"},"TimelineActor":{"properties":{"kind":{"type":"string","enum":["agent","human","operator","system","tool"],"title":"Kind"},"role":{"type":"string","enum":["agent","caller","operator","runtime","state","tool"],"title":"Role"},"label":{"type":"string","title":"Label"},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Id"}},"type":"object","required":["kind","role","label"],"title":"TimelineActor"},"TimelineTimebase":{"properties":{"unit":{"type":"string","const":"seconds","title":"Unit","description":"Timeline offsets are always seconds.","default":"seconds"},"origin":{"type":"string","enum":["media_start","call_start","synthetic"],"title":"Origin","description":"Zero point used for segment start/end offsets.","default":"media_start"},"start":{"type":"number","title":"Start","description":"Visible/canonical timeline range start in seconds.","default":0},"end":{"type":"number","title":"End","description":"Visible/canonical timeline range end in seconds.","default":0}},"type":"object","title":"TimelineTimebase"},"TimelineLaneDefinition":{"properties":{"id":{"type":"string","maxLength":160,"minLength":1,"title":"Id","description":"Stable canonical lane id used by timeline visualizations. Segments attach via TimelineSegment.lane_id; consumers should not re-infer lanes from CSS or pixel positions."},"track":{"type":"string","enum":["agent","caller","operator","system","tool"],"title":"Track","description":"High-level actor-semantic track for styling and grouping."},"label":{"type":"string","title":"Label","description":"Display label for the lane."},"order":{"type":"integer","title":"Order","description":"Stable vertical order within the timeline lane model."},"actor":{"anyOf":[{"$ref":"#/components/schemas/TimelineActor"},{"type":"null"}],"description":"Actor represented by this lane when applicable."}},"type":"object","required":["id","track","label","order"],"title":"TimelineLaneDefinition"},"EscalationState":{"properties":{"status":{"type":"string","title":"Status","default":"none"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id"},"requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Requested At"},"connected_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Connected At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Completed At"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity"},"agent_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Confidence"},"operator_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Type"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis"},"immediate":{"type":"boolean","title":"Immediate","default":false},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"operator_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Entity Id"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds"},"handle_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Handle Time Seconds"},"human_segment_turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Human Segment Turn Count"}},"type":"object","title":"EscalationState"},"SafetyState":{"properties":{"peak_concern_level":{"type":"integer","title":"Peak Concern Level","default":0},"concern_turn_count":{"type":"integer","title":"Concern Turn Count","default":0},"trajectory":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trajectory"},"triage_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Triage History","default":[]},"concept_matches":{"items":{"$ref":"#/components/schemas/ConceptMatch"},"type":"array","title":"Concept Matches","default":[]}},"type":"object","title":"SafetyState"},"ConceptMatch":{"properties":{"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity"},"agent_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Action"},"agent_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Confidence"},"agent_reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Reasoning"},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"At"}},"type":"object","title":"ConceptMatch"},"HumanSegment":{"properties":{"speaker_role":{"type":"string","title":"Speaker Role"},"transcript":{"type":"string","title":"Transcript"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp"}},"type":"object","required":["speaker_role","transcript"],"title":"HumanSegment"},"AuditSummary":{"properties":{"event_count":{"type":"integer","title":"Event Count","default":0},"latest_event":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latest Event"}},"type":"object","title":"AuditSummary"}}}} ``` ## The CallEvalResult object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallEvalResult":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"title":"Expected"},"actual":{"title":"Actual"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Justification"},"cited_turns":{"items":{},"type":"array","title":"Cited Turns"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["workspace_id","conversation_id","eval_key","eval_type","status"],"title":"CallEvalResult","description":"One eval verdict for one production call, keyed by ``conversation_id``.\nMirrors the sim eval-result shape. ``justification`` and ``cited_turns`` come\nfrom the justified ai_query metric compute. PHI: ``justification`` / ``actual``\ncan echo live transcript content; never log them."}}}} ``` ## The CallEvalResultsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallEvalResultsResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"results":{"items":{"$ref":"#/components/schemas/CallEvalResult"},"type":"array","title":"Results"}},"type":"object","required":["conversation_id","results"],"title":"CallEvalResultsResponse"},"CallEvalResult":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"title":"Expected"},"actual":{"title":"Actual"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Justification"},"cited_turns":{"items":{},"type":"array","title":"Cited Turns"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["workspace_id","conversation_id","eval_key","eval_type","status"],"title":"CallEvalResult","description":"One eval verdict for one production call, keyed by ``conversation_id``.\nMirrors the sim eval-result shape. ``justification`` and ``cited_turns`` come\nfrom the justified ai_query metric compute. PHI: ``justification`` / ``actual``\ncan echo live transcript content; never log them."}}}} ``` ## The CallIntelligenceDetail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallIntelligenceDetail":{"properties":{"call_id":{"type":"string","title":"Call Id","description":"World entity ID for the call"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"direction":{"type":"string","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","description":"Call direction","default":"inbound"},"duration_seconds":{"type":"number","title":"Duration Seconds","description":"Call duration in seconds","default":0},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score","description":"Quality score 0.0 to 1.0"},"quality_breakdown":{"anyOf":[{"$ref":"#/components/schemas/QualityBreakdown"},{"type":"null"}],"description":"Detailed quality breakdown"},"key_moments":{"items":{"$ref":"#/components/schemas/KeyMoment"},"type":"array","title":"Key Moments","description":"Notable call events"},"emotion_summary":{"anyOf":[{"$ref":"#/components/schemas/EmotionSummary"},{"type":"null"}],"description":"Emotional analysis"},"risk_summary":{"anyOf":[{"$ref":"#/components/schemas/RiskSummary"},{"type":"null"}],"description":"Risk assessment"},"latency_summary":{"anyOf":[{"$ref":"#/components/schemas/LatencySummary"},{"type":"null"}],"description":"Audio latency metrics"},"conversation_summary":{"anyOf":[{"$ref":"#/components/schemas/ConversationSummary"},{"type":"null"}],"description":"Conversation flow metrics"},"tool_summary":{"anyOf":[{"$ref":"#/components/schemas/ToolSummary"},{"type":"null"}],"description":"Tool usage statistics"},"safety_summary":{"anyOf":[{"$ref":"#/components/schemas/SafetySummary"},{"type":"null"}],"description":"Safety filter results"},"operator_summary":{"anyOf":[{"$ref":"#/components/schemas/OperatorIntelligenceSummary"},{"type":"null"}],"description":"Operator intervention"},"completion_reason":{"anyOf":[{"type":"string","enum":["completed","abandoned","escalated","transferred","timeout","error","voicemail","no_answer","caller_hangup","forwarded","terminal_state","warm_transfer_completed","no_inbound_audio","cancelled"]},{"type":"null"}],"title":"Completion Reason","description":"Why the call ended"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State","description":"Final conversation state name"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When intelligence was computed"}},"type":"object","required":["call_id"],"title":"CallIntelligenceDetail","description":"Layer 4 (Narrative) intelligence for a completed call.\n\nAggregated summaries, quality breakdown, and key moments — the\ninterpretive layer. Per-turn visualization data lives on the unified\ntimeline (call detail → PlaybackTimeline.segments), not here."},"QualityBreakdown":{"properties":{"score":{"type":"number","title":"Score"},"components":{"items":{"$ref":"#/components/schemas/QualityComponent"},"type":"array","title":"Components"},"workspace_avg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Workspace Avg"},"workspace_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Workspace Percentile"}},"type":"object","required":["score","components"],"title":"QualityBreakdown","description":"Structured breakdown of how quality score was computed."},"QualityComponent":{"properties":{"name":{"type":"string","enum":["latency","silence","barge_ins","loops","escalation","tool_failures"],"title":"Name","description":"Quality dimension"},"penalty":{"type":"number","title":"Penalty","description":"Penalty subtracted from the score"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Raw measured value"},"threshold":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Threshold","description":"Threshold that was exceeded"},"severity":{"type":"string","enum":["none","minor","major","critical"],"title":"Severity","description":"Severity of the penalty","default":"none"}},"type":"object","required":["name","penalty"],"title":"QualityComponent","description":"Single quality score component with penalty and context."},"KeyMoment":{"properties":{"turn":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn","description":"Turn index where the moment occurred"},"type":{"type":"string","enum":["latency_spike","silence","barge_in","loop","tool_failure","escalation","safety_flag","high_risk","elevated_risk"],"title":"Type","description":"Category of the moment"},"severity":{"type":"string","enum":["info","warning","error"],"title":"Severity","description":"Severity level","default":"warning"},"description":{"type":"string","title":"Description","description":"Human-readable description"}},"type":"object","required":["type","description"],"title":"KeyMoment","description":"Notable event during the call worth highlighting."},"EmotionSummary":{"properties":{"dominant_emotion":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Dominant Emotion","description":"Most frequent emotion (e.g. 'neutral', 'happy', 'angry')"},"average_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Valence","description":"Average emotional valence -1.0 to 1.0"},"average_arousal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Arousal","description":"Average emotional arousal 0.0 to 1.0"},"peak_negative_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Peak Negative Valence","description":"Most negative valence observed"},"barge_in_count":{"type":"integer","title":"Barge In Count","description":"Number of caller interruptions (emotion-tagged)","default":0}},"type":"object","title":"EmotionSummary","description":"Aggregated emotional analysis across the call.\n\nFree-form residual on the raw ``emotion_summary`` JSONB:\n``compound_emotions: list[{name, score}]``. Not exposed via this\ntyped shape — readers wanting it consume the JSONB endpoint."},"RiskSummary":{"properties":{"composite_score":{"type":"number","title":"Composite Score","description":"Overall risk score 0.0 to 1.0","default":0},"level":{"type":"string","enum":["low","medium","high","critical"],"title":"Level","description":"Risk level","default":"low"}},"type":"object","title":"RiskSummary","description":"Aggregated risk signals across the call.\n\nFree-form residual on the raw ``risk_summary`` JSONB:\n``signals: list[{name, raw_score, weight, weighted_score, detail}]``\n— the per-signal breakdown that aggregates into ``composite_score``.\nNot exposed via this typed shape; consumers needing per-signal\ndetail read the JSONB endpoint."},"LatencySummary":{"properties":{"avg_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Engine Ms","description":"Average reasoning-engine latency (ms)"},"p50_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Engine Ms","description":"Median engine latency (ms)"},"p95_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Engine Ms","description":"95th percentile engine latency (ms)"},"avg_audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Audio Ttfb Ms","description":"Average audio time-to-first-byte (ms)"},"p50_audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Audio Ttfb Ms","description":"Median audio TTFB (ms)"},"p95_audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Audio Ttfb Ms","description":"95th percentile audio TTFB (ms)"},"avg_nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Nav Ms","description":"Average navigation latency (ms)"},"avg_render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Render Ms","description":"Average render latency (ms)"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Count","description":"Number of turns the latency averages were computed over"},"silence_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Silence Ratio","description":"Fraction of call spent in silence"}},"type":"object","title":"LatencySummary","description":"Audio + engine latency metrics (one entry per turn averaged)."},"ConversationSummary":{"properties":{"turn_count":{"type":"integer","title":"Turn Count","description":"Total turn count for the call","default":0},"states_visited_count":{"type":"integer","title":"States Visited Count","description":"Number of states visited (including repeats)","default":0},"unique_states":{"type":"integer","title":"Unique States","description":"Number of distinct states visited","default":0},"loop_count":{"type":"integer","title":"Loop Count","description":"Number of detected state loops","default":0},"barge_in_count":{"type":"integer","title":"Barge In Count","description":"Number of caller interruptions","default":0}},"type":"object","title":"ConversationSummary","description":"Conversation flow metrics.\n\nFree-form residual on the raw ``conversation_summary`` JSONB:\n``text_intelligence: dict`` (text-channel intelligence\nsub-payload), and on the simulation path ``transcript_text:\nstr`` (PHI), ``tool_calls: list``, ``score``,\n``score_rationale``, ``terminal_reached``, ``states_visited``.\nNot exposed via this typed shape."},"ToolSummary":{"properties":{"total_calls":{"type":"integer","title":"Total Calls","description":"Total tool invocations","default":0},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful tool invocations","default":0},"failed":{"type":"integer","title":"Failed","description":"Failed tool invocations","default":0},"failure_rate":{"type":"number","title":"Failure Rate","description":"Tool failure rate 0.0 to 1.0","default":0}},"type":"object","title":"ToolSummary","description":"Tool usage statistics.\n\nFree-form residual on the raw ``tool_summary`` JSONB:\n``by_tool: list[{name, calls, succeeded, failed, avg_duration_ms}]``\n— per-tool breakdown. Not exposed via this typed shape."},"SafetySummary":{"properties":{"match_count":{"type":"integer","title":"Match Count","description":"Number of safety filter matches","default":0}},"type":"object","title":"SafetySummary","description":"Safety filter results.\n\nFree-form residual on the raw ``safety_summary`` JSONB:\n``actions: dict | list`` — escalation handler actions taken\nwhen ``match_count > 0``. Not exposed via this typed shape."},"OperatorIntelligenceSummary":{"properties":{"escalated":{"type":"boolean","title":"Escalated","description":"Whether the call was escalated to a human operator","default":false},"operator_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Operator Active","description":"Whether an operator was active during escalation. True = active; False = escalation occurred but no operator picked up; None = no escalation occurred (do NOT coerce to False)."}},"type":"object","title":"OperatorIntelligenceSummary","description":"Operator intervention summary.\n\nThree-valued semantics on ``operator_active``:\n- ``True`` — escalation occurred and an operator was active.\n- ``False`` — escalation occurred but no operator picked up.\n- ``None`` — no escalation occurred (producer omits the key).\n Readers must distinguish; do not coerce ``None`` → ``False``."}}}} ``` ## The CallIntelligenceMetricProjectionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallIntelligenceMetricProjectionRequest":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"call_sid":{"type":"string","maxLength":128,"minLength":1,"title":"Call Sid"},"service_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Service Id"},"direction":{"type":"string","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction"},"duration_seconds":{"type":"number","minimum":0,"title":"Duration Seconds"},"quality_score":{"type":"number","maximum":100,"minimum":0,"title":"Quality Score"},"completion_reason":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Completion Reason"},"final_state":{"type":"string","maxLength":256,"title":"Final State","default":""},"source":{"type":"string","enum":["real","simulation","playground"],"title":"Source"},"channel_kind":{"type":"string","maxLength":32,"minLength":1,"title":"Channel Kind","default":"voice"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"call_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Call Id"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"emotion_summary":{"additionalProperties":true,"type":"object","title":"Emotion Summary"},"risk_summary":{"additionalProperties":true,"type":"object","title":"Risk Summary"},"latency_summary":{"additionalProperties":true,"type":"object","title":"Latency Summary"},"conversation_summary":{"additionalProperties":true,"type":"object","title":"Conversation Summary"},"tool_summary":{"additionalProperties":true,"type":"object","title":"Tool Summary"},"safety_summary":{"additionalProperties":true,"type":"object","title":"Safety Summary"},"operator_summary":{"additionalProperties":true,"type":"object","title":"Operator Summary"},"simulation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Simulation"}},"additionalProperties":false,"type":"object","required":["workspace_id","call_sid","direction","duration_seconds","quality_score","source","created_at"],"title":"CallIntelligenceMetricProjectionRequest","description":"Internal projection request for the shared terminal artifact."}}}} ``` ## The CallListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CallSummary"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"}},"type":"object","required":["items","total","has_more"],"title":"CallListResponse"},"CallSummary":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id","description":"World entity ID for this call"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the call started"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Call duration in seconds"},"status":{"anyOf":[{"type":"string","enum":["initiated","ringing","in-progress","completed","busy","no-answer","canceled","failed","unknown"]},{"type":"null"}],"title":"Status","description":"Call status"},"escalation_status":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Escalation Status","description":"Escalation state if any"},"turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turns","description":"Number of conversation turns"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording","description":"Whether a recording is available"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score","description":"Quality score 0.0 to 1.0"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State","description":"Final conversation state"},"completion_reason":{"anyOf":[{"type":"string","enum":["completed","abandoned","escalated","transferred","timeout","error","voicemail","no_answer","caller_hangup","forwarded","terminal_state","warm_transfer_completed","no_inbound_audio","cancelled"]},{"type":"null"}],"title":"Completion Reason","description":"Why the call ended"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service ID that handled the call"},"source":{"anyOf":[{"type":"string","enum":["real","simulation","playground"]},{"type":"null"}],"title":"Source","description":"Call source — real, simulation, or playground"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"Simulation run ID (simulation calls only)"},"parent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Session Id","description":"Parent session for forked simulations"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index","description":"Turn index where simulation forked"}},"type":"object","required":["entity_id"],"title":"CallSummary"}}}} ``` ## The CallQualityAnalyticsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallQualityAnalyticsResponse":{"properties":{"summary":{"$ref":"#/components/schemas/CallQualitySummary","description":"Aggregate call-quality metrics for the period"},"trend":{"items":{"$ref":"#/components/schemas/CallQualityTrendPoint"},"type":"array","maxItems":2200,"title":"Trend","description":"Time series of call-quality metrics per interval bucket"},"quality_distribution":{"$ref":"#/components/schemas/CallQualityDistribution","description":"Call counts bucketed by quality-score band"}},"type":"object","required":["summary","trend","quality_distribution"],"title":"CallQualityAnalyticsResponse","description":"Call quality score trends, distribution, and summary over time.\n\nServed from the live Delta projection ``analytics.source_call_intelligence``."},"CallQualitySummary":{"properties":{"avg_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality Score","description":"Mean quality score across calls (0-100)"},"p50_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Quality Score","description":"Median quality score (0-100)"},"p95_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Quality Score","description":"95th-percentile quality score (0-100)"},"total_calls":{"type":"integer","title":"Total Calls","description":"Total number of calls in the period"},"escalation_rate":{"type":"number","title":"Escalation Rate","description":"Fraction of calls escalated to an operator (0.0-1.0)"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average call duration in seconds"}},"type":"object","required":["total_calls","escalation_rate"],"title":"CallQualitySummary","description":"Aggregate call-quality stats for the period."},"CallQualityTrendPoint":{"properties":{"date":{"type":"string","title":"Date","description":"Time bucket as an ISO-8601 timestamp string (granularity follows `interval`)"},"avg_quality":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality","description":"Average quality score in this bucket (0-100)"},"call_count":{"type":"integer","title":"Call Count","description":"Number of calls in this bucket"},"escalation_count":{"type":"integer","title":"Escalation Count","description":"Number of escalated calls in this bucket"}},"type":"object","required":["date","call_count","escalation_count"],"title":"CallQualityTrendPoint","description":"Single time-bucket data point in the call-quality trend series."},"CallQualityDistribution":{"properties":{"excellent_90_100":{"type":"integer","title":"Excellent 90 100","description":"Calls with quality score 90-100"},"good_70_89":{"type":"integer","title":"Good 70 89","description":"Calls with quality score 70-89"},"fair_50_69":{"type":"integer","title":"Fair 50 69","description":"Calls with quality score 50-69"},"poor_0_49":{"type":"integer","title":"Poor 0 49","description":"Calls with quality score 0-49"}},"type":"object","required":["excellent_90_100","good_70_89","fair_50_69","poor_0_49"],"title":"CallQualityDistribution","description":"Call counts bucketed by quality-score band."}}}} ``` ## The CallQualityDistribution object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallQualityDistribution":{"properties":{"excellent_90_100":{"type":"integer","title":"Excellent 90 100","description":"Calls with quality score 90-100"},"good_70_89":{"type":"integer","title":"Good 70 89","description":"Calls with quality score 70-89"},"fair_50_69":{"type":"integer","title":"Fair 50 69","description":"Calls with quality score 50-69"},"poor_0_49":{"type":"integer","title":"Poor 0 49","description":"Calls with quality score 0-49"}},"type":"object","required":["excellent_90_100","good_70_89","fair_50_69","poor_0_49"],"title":"CallQualityDistribution","description":"Call counts bucketed by quality-score band."}}}} ``` ## The CallQualitySummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallQualitySummary":{"properties":{"avg_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality Score","description":"Mean quality score across calls (0-100)"},"p50_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Quality Score","description":"Median quality score (0-100)"},"p95_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Quality Score","description":"95th-percentile quality score (0-100)"},"total_calls":{"type":"integer","title":"Total Calls","description":"Total number of calls in the period"},"escalation_rate":{"type":"number","title":"Escalation Rate","description":"Fraction of calls escalated to an operator (0.0-1.0)"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average call duration in seconds"}},"type":"object","required":["total_calls","escalation_rate"],"title":"CallQualitySummary","description":"Aggregate call-quality stats for the period."}}}} ``` ## The CallQualityTrendPoint object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallQualityTrendPoint":{"properties":{"date":{"type":"string","title":"Date","description":"Time bucket as an ISO-8601 timestamp string (granularity follows `interval`)"},"avg_quality":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality","description":"Average quality score in this bucket (0-100)"},"call_count":{"type":"integer","title":"Call Count","description":"Number of calls in this bucket"},"escalation_count":{"type":"integer","title":"Escalation Count","description":"Number of escalated calls in this bucket"}},"type":"object","required":["date","call_count","escalation_count"],"title":"CallQualityTrendPoint","description":"Single time-bucket data point in the call-quality trend series."}}}} ``` ## The CallStatsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallStatsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace identifier"},"period_start":{"type":"string","format":"date","title":"Period Start","description":"Start of the reporting period"},"period_end":{"type":"string","format":"date","title":"Period End","description":"End of the reporting period"},"total_calls":{"type":"integer","title":"Total Calls","description":"Total number of calls in the period"},"total_duration_seconds":{"type":"number","title":"Total Duration Seconds","description":"Sum of all call durations in seconds"},"avg_duration_seconds":{"type":"number","title":"Avg Duration Seconds","description":"Average call duration in seconds"},"calls_by_date":{"items":{"$ref":"#/components/schemas/DailyCallStat"},"type":"array","title":"Calls By Date","description":"Daily call volume breakdown"}},"type":"object","required":["workspace_id","period_start","period_end","total_calls","total_duration_seconds","avg_duration_seconds","calls_by_date"],"title":"CallStatsResponse"},"DailyCallStat":{"properties":{"date":{"type":"string","title":"Date","description":"Date string (YYYY-MM-DD)"},"count":{"type":"integer","title":"Count","description":"Number of calls on this date"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average call duration in seconds"}},"type":"object","required":["date","count"],"title":"DailyCallStat","description":"Per-day call volume and duration."}}}} ``` ## The CallSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallSummary":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id","description":"World entity ID for this call"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the call started"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Call duration in seconds"},"status":{"anyOf":[{"type":"string","enum":["initiated","ringing","in-progress","completed","busy","no-answer","canceled","failed","unknown"]},{"type":"null"}],"title":"Status","description":"Call status"},"escalation_status":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Escalation Status","description":"Escalation state if any"},"turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turns","description":"Number of conversation turns"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording","description":"Whether a recording is available"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score","description":"Quality score 0.0 to 1.0"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State","description":"Final conversation state"},"completion_reason":{"anyOf":[{"type":"string","enum":["completed","abandoned","escalated","transferred","timeout","error","voicemail","no_answer","caller_hangup","forwarded","terminal_state","warm_transfer_completed","no_inbound_audio","cancelled"]},{"type":"null"}],"title":"Completion Reason","description":"Why the call ended"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service ID that handled the call"},"source":{"anyOf":[{"type":"string","enum":["real","simulation","playground"]},{"type":"null"}],"title":"Source","description":"Call source — real, simulation, or playground"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"Simulation run ID (simulation calls only)"},"parent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Session Id","description":"Parent session for forked simulations"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index","description":"Turn index where simulation forked"}},"type":"object","required":["entity_id"],"title":"CallSummary"}}}} ``` ## The CallTranscriptResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallTranscriptResponse":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"total_segments":{"type":"integer","title":"Total Segments"},"segments":{"items":{"$ref":"#/components/schemas/TranscriptSegment"},"type":"array","title":"Segments"}},"type":"object","required":["call_entity_id","call_sid","total_segments","segments"],"title":"CallTranscriptResponse"},"TranscriptSegment":{"properties":{"speaker_role":{"type":"string","title":"Speaker Role"},"transcript":{"type":"string","title":"Transcript"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"}},"type":"object","required":["speaker_role","transcript","timestamp","escalation_id","confidence"],"title":"TranscriptSegment"}}}} ``` ## The CanonicalIdLookupString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CanonicalIdLookupString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The CanonicalIdString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CanonicalIdString":{"type":"string","maxLength":256,"minLength":3,"pattern":"^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$"}}}} ``` ## The CanonicalInboundEnvelopePayload object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CanonicalInboundEnvelopePayload":{"properties":{"channel_kind":{"$ref":"#/components/schemas/ChannelKind"},"use_case_id":{"type":"string","format":"uuid","title":"Use Case Id"},"inbound_message_ref":{"type":"string","maxLength":256,"minLength":1,"title":"Inbound Message Ref"},"caller_ref":{"type":"string","maxLength":320,"title":"Caller Ref","default":""},"content_parts":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","maxItems":100,"minItems":1,"title":"Content Parts"},"parent_outbound_ref":{"type":"string","maxLength":256,"title":"Parent Outbound Ref","default":""},"subject":{"anyOf":[{"type":"string","maxLength":998},{"type":"null"}],"title":"Subject"},"authenticated":{"type":"boolean","title":"Authenticated","default":false},"idempotency_key":{"type":"string","maxLength":256,"title":"Idempotency Key","default":""},"occurred_at":{"type":"number","title":"Occurred At","default":0}},"type":"object","required":["channel_kind","use_case_id","inbound_message_ref","content_parts"],"title":"CanonicalInboundEnvelopePayload","description":"HTTP wire shape for :class:`CanonicalInboundEnvelope` (channel service → platform-api).\n\nFrozen — it is parsed once and immediately converted to the frozen in-core\ndataclass, so between-parse mutation is a bug."},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."}}}} ``` ## The CatalogEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CatalogEntry":{"properties":{"name":{"type":"string","title":"Name"},"layer":{"type":"string","title":"Layer"},"description":{"type":"string","title":"Description"},"row_count":{"type":"integer","title":"Row Count"},"exists":{"type":"boolean","title":"Exists"}},"type":"object","required":["name","layer","description","row_count","exists"],"title":"CatalogEntry"}}}} ``` ## The CategoricalMetricValueResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CategoricalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"categorical","title":"Metric Type"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"CategoricalMetricValueResponse"}}}} ``` ## The ChangeColumnTypeAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ChangeColumnTypeAction":{"properties":{"op":{"type":"string","const":"change_column_type","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"new_type":{"$ref":"#/components/schemas/ColumnType"}},"type":"object","required":["op","name","new_type"],"title":"ChangeColumnTypeAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]}}}} ``` ## The ChannelKind object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."}}}} ``` ## The ChannelOverride object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."},"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."}}}} ``` ## The ChannelTurnResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ChannelTurnResponse":{"properties":{"status":{"type":"string","enum":["accepted","skipped","duplicate"],"title":"Status"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Event Id"},"is_new_session":{"type":"boolean","title":"Is New Session","default":false}},"type":"object","required":["status"],"title":"ChannelTurnResponse"}}}} ``` ## The ChannelType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The ChatRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ChatRequest":{"properties":{"message":{"type":"string","maxLength":16000,"minLength":1,"title":"Message","description":"Insights chat user message."}},"type":"object","required":["message"],"title":"ChatRequest"}}}} ``` ## The ClaimMappingItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClaimMappingItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"claim_namespace":{"type":"string","title":"Claim Namespace"},"claim_key":{"type":"string","title":"Claim Key"},"external_value":{"type":"string","title":"External Value"},"external_role_id":{"type":"string","format":"uuid","title":"External Role Id"},"status":{"type":"string","enum":["active","superseded"],"title":"Status"},"changed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Changed By"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","claim_namespace","claim_key","external_value","external_role_id","status","created_at"],"title":"ClaimMappingItem"}}}} ``` ## The ClassUsage object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClassUsage":{"properties":{"usage_class":{"type":"string","title":"Usage Class"},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ClassUsage","description":"Usage attributed to one usage class."}}}} ``` ## The ClientArtifact object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClientArtifact":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"payload":{"$ref":"#/components/schemas/ClientArtifactPayload"}},"type":"object","required":["type","schema_version","payload"],"title":"ClientArtifact","description":"A versioned JSON payload that a client can render as a product component."},"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]}}}} ``` ## The ClientArtifactPayload object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]}}}} ``` ## The ClientConfigResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClientConfigResponse":{"properties":{"google_maps_api_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Google Maps Api Key"}},"type":"object","title":"ClientConfigResponse","description":"Client-safe configuration values.\n\nValues returned here are safe to embed in browser-side code.\nAPI keys are restricted by HTTP referrer or similar origin\ncontrols at the provider level."}}}} ``` ## The ClientOutputConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."}}}} ``` ## The ClinicOpenHoursParams object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClinicOpenHoursParams":{"properties":{"rule_kind":{"type":"string","const":"clinic_open_hours","title":"Rule Kind","default":"clinic_open_hours"},"timezone":{"type":"string","maxLength":64,"minLength":1,"title":"Timezone"},"monday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"tuesday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"wednesday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"thursday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"friday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"saturday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"sunday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]}},"type":"object","required":["timezone"],"title":"ClinicOpenHoursParams","description":"Workspace clinic open-hours by weekday.\n\nDays not present mean \"closed.\" Used by the rules engine to skip\nslots outside open hours and (combined with ``weekend_skip``) by the\nTMS-mapping release calculator."},"_DayHours":{"properties":{"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"Start"},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"End"}},"type":"object","required":["start","end"],"title":"_DayHours","description":"Open-hours window for one weekday. Times in 24h ``HH:MM`` form,\ninterpreted in the rule set's ``timezone``."}}}} ``` ## The ClusterForecastPointRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClusterForecastPointRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"cluster_name":{"type":"string","title":"Cluster Name"},"focus_area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Focus Area"},"t":{"type":"number","title":"T"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"lower_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lower 95"},"upper_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Upper 95"},"observed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Observed"},"ym":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ym"},"is_historical":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Historical"}},"type":"object","required":["workspace_id","cluster_name","t"],"title":"ClusterForecastPointRow"}}}} ``` ## The ClusterForecastResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClusterForecastResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/ClusterForecastPointRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"ClusterForecastResponse"},"ClusterForecastPointRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"cluster_name":{"type":"string","title":"Cluster Name"},"focus_area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Focus Area"},"t":{"type":"number","title":"T"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"lower_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lower 95"},"upper_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Upper 95"},"observed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Observed"},"ym":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ym"},"is_historical":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Historical"}},"type":"object","required":["workspace_id","cluster_name","t"],"title":"ClusterForecastPointRow"}}}} ``` ## The ClusterSummaryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClusterSummaryResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/ClusterSummaryRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"ClusterSummaryResponse"},"ClusterSummaryRow":{"properties":{"cluster_name":{"type":"string","title":"Cluster Name"},"cohort_size":{"type":"integer","title":"Cohort Size"},"mean_age":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Age"},"mean_bmi":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Bmi"},"mean_hba1c":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Hba1C"},"pct_male":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Male"},"pct_prediabetes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Prediabetes"},"pct_t2d":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct T2D"},"mean_y_hat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Y Hat"}},"type":"object","required":["cluster_name","cohort_size"],"title":"ClusterSummaryRow"}}}} ``` ## The ClusterSummaryRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ClusterSummaryRow":{"properties":{"cluster_name":{"type":"string","title":"Cluster Name"},"cohort_size":{"type":"integer","title":"Cohort Size"},"mean_age":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Age"},"mean_bmi":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Bmi"},"mean_hba1c":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Hba1C"},"pct_male":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Male"},"pct_prediabetes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Prediabetes"},"pct_t2d":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct T2D"},"mean_y_hat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Y Hat"}},"type":"object","required":["cluster_name","cohort_size"],"title":"ClusterSummaryRow"}}}} ``` ## The CoachingItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CoachingItem":{"properties":{"moment_timestamp":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Moment Timestamp","description":"Position in the recording this coaching applies to (seconds)"},"observation":{"type":"string","maxLength":2000,"minLength":1,"title":"Observation","description":"What was observed in the audio at this moment"},"recommendation":{"type":"string","maxLength":2000,"minLength":1,"title":"Recommendation","description":"Specific improvement the agent should make"},"expected_impact":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Expected Impact","description":"How this improvement would change the interaction"}},"type":"object","required":["observation","recommendation"],"title":"CoachingItem","description":"A specific, actionable improvement tied to an exact moment in the call."}}}} ``` ## The CollectionField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."}}}} ``` ## The Column-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Column-Input":{"properties":{"name":{"$ref":"#/components/schemas/IdentifierString"},"type":{"$ref":"#/components/schemas/ColumnType"},"nullable":{"type":"boolean","title":"Nullable","default":true},"default":{"anyOf":[{"$ref":"#/components/schemas/Default"},{"type":"null"}]}},"type":"object","required":["name","type"],"title":"Column"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]},"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"}}}} ``` ## The Column-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Column-Output":{"properties":{"name":{"type":"string","title":"Name"},"data_type":{"type":"string","title":"Data Type","description":"Postgres-side type as reported by ``information_schema.columns``\n(e.g. ``uuid``, ``text``, ``timestamp with time zone``)."},"is_nullable":{"type":"boolean","title":"Is Nullable"},"default":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default","description":"Postgres-side default expression text, or NULL if no DEFAULT."}},"type":"object","required":["name","data_type","is_nullable","default"],"title":"Column"}}}} ``` ## The ColumnType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]}}}} ``` ## The CommandCenterAlert object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CommandCenterAlert":{"properties":{"level":{"type":"string","enum":["info","warning","critical"],"title":"Level"},"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"section":{"type":"string","title":"Section"}},"type":"object","required":["level","code","message","section"],"title":"CommandCenterAlert"}}}} ``` ## The CommandCenterResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CommandCenterResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"voice":{"$ref":"#/components/schemas/VoiceMetrics","default":{"active_calls":0,"active_escalated":0,"calls_today":0,"escalation_rate_today":0}},"pipeline":{"$ref":"#/components/schemas/PipelineMetrics","default":{"sources_total":0,"sources_healthy":0,"sources_degraded":0,"sources_failing":0,"events_last_hour":0,"outbound_pending":0,"outbound_failed":0,"connector_status":"unavailable"}},"data_quality":{"$ref":"#/components/schemas/DataQualityMetrics","default":{"pending_reviews":0,"entities_total":0,"entities_merged_7d":0}},"identity":{"$ref":"#/components/schemas/IdentityMetrics","default":{"active_api_keys":0}},"alerts":{"items":{"$ref":"#/components/schemas/CommandCenterAlert"},"type":"array","title":"Alerts","default":[]},"degraded_sections":{"items":{"type":"string"},"type":"array","title":"Degraded Sections","default":[]},"generated_at":{"type":"string","title":"Generated At"},"cached":{"type":"boolean","title":"Cached","default":false}},"type":"object","required":["workspace_id","generated_at"],"title":"CommandCenterResponse"},"VoiceMetrics":{"properties":{"active_calls":{"type":"integer","title":"Active Calls","default":0},"active_escalated":{"type":"integer","title":"Active Escalated","default":0},"calls_today":{"type":"integer","title":"Calls Today","default":0},"avg_quality_score_today":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality Score Today"},"escalation_rate_today":{"type":"number","title":"Escalation Rate Today","default":0}},"type":"object","title":"VoiceMetrics"},"PipelineMetrics":{"properties":{"sources_total":{"type":"integer","title":"Sources Total","default":0},"sources_healthy":{"type":"integer","title":"Sources Healthy","default":0},"sources_degraded":{"type":"integer","title":"Sources Degraded","default":0},"sources_failing":{"type":"integer","title":"Sources Failing","default":0},"events_last_hour":{"type":"integer","title":"Events Last Hour","default":0},"outbound_pending":{"type":"integer","title":"Outbound Pending","default":0},"outbound_failed":{"type":"integer","title":"Outbound Failed","default":0},"connector_status":{"type":"string","enum":["healthy","degraded","unavailable"],"title":"Connector Status","default":"unavailable"}},"type":"object","title":"PipelineMetrics"},"DataQualityMetrics":{"properties":{"pending_reviews":{"type":"integer","title":"Pending Reviews","default":0},"approval_rate_7d":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Approval Rate 7D"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"entities_total":{"type":"integer","title":"Entities Total","default":0},"entities_merged_7d":{"type":"integer","title":"Entities Merged 7D","default":0}},"type":"object","title":"DataQualityMetrics"},"IdentityMetrics":{"properties":{"active_api_keys":{"type":"integer","title":"Active Api Keys","default":0},"active_sessions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Sessions"},"failed_auths_1h":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Failed Auths 1H"},"locked_accounts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Locked Accounts"},"mfa_coverage_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mfa Coverage Pct"}},"type":"object","title":"IdentityMetrics"},"CommandCenterAlert":{"properties":{"level":{"type":"string","enum":["info","warning","critical"],"title":"Level"},"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"section":{"type":"string","title":"Section"}},"type":"object","required":["level","code","message","section"],"title":"CommandCenterAlert"}}}} ``` ## The CompletionCriteria object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"}}}} ``` ## The ComplianceDashboardResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ComplianceDashboardResponse":{"properties":{"hipaa_status":{"type":"string","title":"Hipaa Status"},"retention_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retention Days"},"legal_hold":{"type":"boolean","title":"Legal Hold"},"total_credentials":{"type":"integer","title":"Total Credentials"},"active_credentials":{"type":"integer","title":"Active Credentials"},"last_audit_export":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Audit Export"},"generated_at":{"type":"string","title":"Generated At"}},"type":"object","required":["hipaa_status","retention_days","legal_hold","total_credentials","active_credentials","last_audit_export","generated_at"],"title":"ComplianceDashboardResponse","description":"Composite compliance health overview."}}}} ``` ## The ConceptMatch object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConceptMatch":{"properties":{"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity"},"agent_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Action"},"agent_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Confidence"},"agent_reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Reasoning"},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"At"}},"type":"object","title":"ConceptMatch"}}}} ``` ## The ConcurrentStartBlockParams object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConcurrentStartBlockParams":{"properties":{"rule_kind":{"type":"string","const":"concurrent_start_block","title":"Rule Kind","default":"concurrent_start_block"}},"type":"object","title":"ConcurrentStartBlockParams","description":"Disallow two slots starting at the same time within a TMS scope.\nNo additional params — the discriminator is the whole config."}}}} ``` ## The ConfidenceBucket object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConfidenceBucket":{"properties":{"confidence_range":{"type":"string","title":"Confidence Range","description":"Confidence level bucket label (e.g. 'raw', 'verified', 'authoritative')"},"count":{"type":"integer","title":"Count","description":"Number of events in this confidence bucket"}},"type":"object","required":["confidence_range","count"],"title":"ConfidenceBucket"}}}} ``` ## The ConfigToPolicyRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConfigToPolicyRequest":{"properties":{"config":{"additionalProperties":true,"type":"object","title":"Config"}},"type":"object","required":["config"],"title":"ConfigToPolicyRequest"}}}} ``` ## The ConnectorHealthItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConnectorHealthItem":{"properties":{"source":{"type":"string","maxLength":256,"minLength":1,"title":"Source","description":"Operator-defined source identifier as written to Delta world_events.source (e.g. 'charm', 'careclinic', 'hazel'). Enum-like; never user input."},"events_per_minute":{"type":"number","minimum":0,"title":"Events Per Minute","description":"Mean events/min over the last hour (events_last_hour / 60)."},"events_last_hour":{"type":"integer","minimum":0,"title":"Events Last Hour"},"events_last_24h":{"type":"integer","minimum":0,"title":"Events Last 24H","description":"Events ingested in the last 24 hours (rolling, not calendar-day)."},"last_ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Ingested At"},"freshness":{"type":"string","enum":["fresh","stale","quiet","never"],"title":"Freshness","description":"fresh < 5min · stale 5-60min · quiet > 60min · never = no events in 24h"}},"type":"object","required":["source","events_per_minute","events_last_hour","events_last_24h","last_ingested_at","freshness"],"title":"ConnectorHealthItem"}}}} ``` ## The ConnectorHealthResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConnectorHealthResponse":{"properties":{"sources":{"items":{"$ref":"#/components/schemas/ConnectorHealthItem"},"type":"array","maxItems":500,"title":"Sources"},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"Server clock at query time (UTC)."},"read_model_status":{"type":"string","enum":["ready","empty","unavailable"],"title":"Read Model Status","description":"ready = Lakebase projection returned rows; empty = no summary rows; unavailable = read failed."},"read_model_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read Model Synced At","description":"Most recent platform.connector_health_summary synced_at value in this response."}},"type":"object","required":["as_of","read_model_status"],"title":"ConnectorHealthResponse"},"ConnectorHealthItem":{"properties":{"source":{"type":"string","maxLength":256,"minLength":1,"title":"Source","description":"Operator-defined source identifier as written to Delta world_events.source (e.g. 'charm', 'careclinic', 'hazel'). Enum-like; never user input."},"events_per_minute":{"type":"number","minimum":0,"title":"Events Per Minute","description":"Mean events/min over the last hour (events_last_hour / 60)."},"events_last_hour":{"type":"integer","minimum":0,"title":"Events Last Hour"},"events_last_24h":{"type":"integer","minimum":0,"title":"Events Last 24H","description":"Events ingested in the last 24 hours (rolling, not calendar-day)."},"last_ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Ingested At"},"freshness":{"type":"string","enum":["fresh","stale","quiet","never"],"title":"Freshness","description":"fresh < 5min · stale 5-60min · quiet > 60min · never = no events in 24h"}},"type":"object","required":["source","events_per_minute","events_last_hour","events_last_24h","last_ingested_at","freshness"],"title":"ConnectorHealthItem"}}}} ``` ## The ConnectorHeartbeat object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConnectorHeartbeat":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"name":{"type":"string","title":"Name"},"alive":{"type":"boolean","title":"Alive"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen"}},"type":"object","required":["data_source_id","name","alive"],"title":"ConnectorHeartbeat"}}}} ``` ## The ConnectorResourcesResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConnectorResourcesResponse":{"properties":{"resource_type":{"type":"string","maxLength":256,"title":"Resource Type","description":"FHIR resource type (e.g. Patient, Condition, MedicationRequest)"},"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id","description":"UUID of the connected data source"},"total":{"type":"integer","title":"Total","description":"Total number of matching resources"},"entries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":100,"title":"Entries","description":"Raw FHIR resource JSON objects"}},"type":"object","required":["resource_type","data_source_id","total","entries"],"title":"ConnectorResourcesResponse","description":"FHIR resources from a specific connected data source."}}}} ``` ## The Constraint object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Constraint":{"properties":{"name":{"type":"string","title":"Name"},"definition":{"type":"string","title":"Definition","description":"``pg_get_constraintdef(oid)`` — the postgres-rendered definition."}},"type":"object","required":["name","definition"],"title":"Constraint"}}}} ``` ## The ContentPartPayload object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."}}}} ``` ## The ContextGraphListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ContextGraphListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ContextGraphResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ContextGraphListResponse"},"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"}}}} ``` ## The ContextGraphResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"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"}}}} ``` ## The ContextGraphState-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ContextGraphState-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ContextGraphVersion object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ContextGraphVersion":{"properties":{"id":{"type":"string","format":"uuid","title":"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","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"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","context_graph_id","version","description","states","new_user_initial_state","returning_user_initial_state","terminal_state"],"title":"ContextGraphVersion","description":"A version of a hierarchical state machine (context graph)."},"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ContextGraphVersionListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ContextGraphVersionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ContextGraphVersionResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ContextGraphVersionListResponse"},"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ContextGraphVersionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The ContextKeySpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The ConversationApprovalRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationApprovalRequest":{"properties":{"decision":{"type":"string","enum":["approve","reject"],"title":"Decision"},"reason":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Reason"}},"additionalProperties":false,"type":"object","required":["decision"],"title":"ConversationApprovalRequest","description":"An external user's decision on a parked, approval-gated write in their own conversation."}}}} ``` ## The ConversationConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationConfig":{"properties":{"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id"},"agent_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Context Graph Id"},"context_graph_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version"},"initial_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initial State"},"gpt_audio_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gpt Audio Model"},"navigation_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Navigation Model"}},"type":"object","title":"ConversationConfig"}}}} ``` ## The ConversationDetail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationDetail":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"channel_kind":{"$ref":"#/components/schemas/ChannelKind"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed","paused"],"title":"Status"},"lifecycle":{"type":"string","enum":["active","dormant","closed"],"title":"Lifecycle"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"escalation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Status"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"turns":{"items":{"$ref":"#/components/schemas/ConversationTurn"},"type":"array","title":"Turns","default":[]},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"voice":{"anyOf":[{"$ref":"#/components/schemas/VoiceDetail"},{"type":"null"}]}},"type":"object","required":["id","channel_kind","status","lifecycle","created_at","updated_at"],"title":"ConversationDetail"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"ConversationTurn":{"properties":{"turn_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Turn Id","description":"Stable identifier of the user exchange this message belongs to, derived deterministically from (conversation_id, turn_index) — identical across ``POST /turns`` responses and re-reads of the conversation history. User and agent messages from the same exchange share this value. Null on messages that precede the first user turn (proactive greetings, channel-event preludes)."},"turn_index":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Turn Index","description":"Zero-based ordinal of the user exchange this message belongs to (0 = first user turn). Derived server-side from the conversation's user-turn count — never stored. Null exactly when ``turn_id`` is null."},"role":{"type":"string","enum":["agent","user","system"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelKind"},{"type":"null"}],"description":"Channel this turn occurred on. A conversation that switched channels has a self-describing per-turn history; null on turns written before per-turn attribution or on channel-less internal turns."},"content":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","title":"Content","default":[]},"tool_calls":{"items":{"$ref":"#/components/schemas/ConversationToolCallDetail"},"type":"array","title":"Tool Calls","description":"Tool calls executed during this (agent) turn. Populated only when the request opts in via ``include_tool_calls=true``; empty otherwise and on turns that did not invoke tools.","default":[]},"artifacts":{"items":{"$ref":"#/components/schemas/ClientArtifact"},"type":"array","title":"Artifacts","description":"Validated client-safe outputs produced during this agent turn.","default":[]},"selected_action_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action Description","description":"Description of the context-graph action selected for this turn. Null means no action was selected or no selected action was recorded."},"state_transition":{"anyOf":[{"$ref":"#/components/schemas/ConversationTurnStateTransition"},{"type":"null"}],"description":"Context-graph state transition that occurred during this turn. Null means no transition took place or no transition was recorded. Deprecated: use state_transitions instead. If multiple transitions were recorded, this field reports the first source state and final destination state.","deprecated":true},"state_transitions":{"items":{"$ref":"#/components/schemas/ConversationTurnStateTransition"},"type":"array","title":"State Transitions","description":"Ordered context-graph state transitions that occurred during this turn.","default":[]},"available_actions":{"items":{"$ref":"#/components/schemas/ConversationTurnAvailableAction"},"type":"array","title":"Available Actions","description":"Action choices available in the turn's resolved context-graph state. Empty when actions cannot be resolved or the resolved state is not an action state.","default":[]}},"type":"object","required":["role","text"],"title":"ConversationTurn"},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"ConversationToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"type":"string","title":"Call Id"},"input":{"additionalProperties":true,"type":"object","title":"Input"},"result":{"type":"string","title":"Result","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"duration_ms":{"anyOf":[{"type":"number","maximum":3600000,"minimum":0},{"type":"null"}],"title":"Duration Ms","description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Omitted (null) on legacy turns that did not capture timing."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Failure detail recorded for the tool call when ``succeeded`` is false. Null on successful calls or when no message was captured."}},"type":"object","required":["tool_name","call_id"],"title":"ConversationToolCallDetail"},"ClientArtifact":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"payload":{"$ref":"#/components/schemas/ClientArtifactPayload"}},"type":"object","required":["type","schema_version","payload"],"title":"ClientArtifact","description":"A versioned JSON payload that a client can render as a product component."},"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]},"ConversationTurnStateTransition":{"properties":{"from":{"type":"string","title":"From","description":"Source context-graph state before the turn's state transition."},"to":{"type":"string","title":"To","description":"Destination context-graph state after the turn's state transition."}},"type":"object","required":["from","to"],"title":"ConversationTurnStateTransition"},"ConversationTurnAvailableAction":{"properties":{"description":{"type":"string","title":"Description","description":"Human-readable description of an action available in the turn's state."}},"type":"object","required":["description"],"title":"ConversationTurnAvailableAction"},"VoiceDetail":{"properties":{"recording_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recording Path"},"twilio_recording_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twilio Recording Sid"},"twilio_recording_duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Twilio Recording Duration"},"has_recording":{"type":"boolean","title":"Has Recording","default":false},"emotional_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Emotional Summary"},"barge_in_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Barge In Events","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"participants":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Participants","default":[]},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"call_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Call Analysis"},"forwarding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Forwarding"},"escalation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Escalation"},"safety":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety"},"quality_breakdown":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quality Breakdown"},"risk_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Risk Summary"},"latency_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latency Summary"},"conversation_metrics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conversation Metrics"},"tool_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Summary"},"safety_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety Summary"},"operator_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Operator Summary"}},"type":"object","title":"VoiceDetail"}}}} ``` ## The ConversationStatusTransitionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationStatusTransitionRequest":{"properties":{"status":{"type":"string","enum":["completed","closed"],"title":"Status"},"reason":{"type":"string","maxLength":64,"minLength":1,"title":"Reason","description":"Low-cardinality transition tag (e.g. hsm_terminal, use_case_rebind) recorded on the audit event and the conversation world event."}},"type":"object","required":["status","reason"],"title":"ConversationStatusTransitionRequest"}}}} ``` ## The ConversationStatusTransitionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationStatusTransitionResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"status":{"type":"string","enum":["completed","closed"],"title":"Status"}},"type":"object","required":["conversation_id","status"],"title":"ConversationStatusTransitionResponse"}}}} ``` ## The ConversationSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationSummary":{"properties":{"turn_count":{"type":"integer","title":"Turn Count","description":"Total turn count for the call","default":0},"states_visited_count":{"type":"integer","title":"States Visited Count","description":"Number of states visited (including repeats)","default":0},"unique_states":{"type":"integer","title":"Unique States","description":"Number of distinct states visited","default":0},"loop_count":{"type":"integer","title":"Loop Count","description":"Number of detected state loops","default":0},"barge_in_count":{"type":"integer","title":"Barge In Count","description":"Number of caller interruptions","default":0}},"type":"object","title":"ConversationSummary","description":"Conversation flow metrics.\n\nFree-form residual on the raw ``conversation_summary`` JSONB:\n``text_intelligence: dict`` (text-channel intelligence\nsub-payload), and on the simulation path ``transcript_text:\nstr`` (PHI), ``tool_calls: list``, ``score``,\n``score_rationale``, ``terminal_reached``, ``states_visited``.\nNot exposed via this typed shape."}}}} ``` ## The ConversationThreadRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationThreadRequest":{"properties":{"channel_kind":{"$ref":"#/components/schemas/ChannelKind"},"provider":{"$ref":"#/components/schemas/ProviderType"},"provider_thread_id":{"type":"string","maxLength":512,"minLength":1,"title":"Provider Thread Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"context":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}]},"type":"object","title":"Context"}},"type":"object","required":["channel_kind","provider","provider_thread_id"],"title":"ConversationThreadRequest"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"ProviderType":{"type":"string","enum":["twilio","websocket","ses","sendblue","meta"],"title":"ProviderType","description":"Messaging provider that implements a channel.\n\nMultiple providers may serve the same ChannelKind."}}}} ``` ## The ConversationThreadResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationThreadResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"channel_kind":{"$ref":"#/components/schemas/ChannelKind"},"provider":{"$ref":"#/components/schemas/ProviderType"},"provider_thread_id":{"type":"string","maxLength":512,"minLength":1,"title":"Provider Thread Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"status":{"type":"string","const":"active","title":"Status"},"created_at":{"type":"number","title":"Created At"},"created":{"type":"boolean","title":"Created"},"turn_count":{"type":"integer","minimum":0,"title":"Turn Count","default":0}},"type":"object","required":["conversation_id","workspace_id","channel_kind","provider","provider_thread_id","status","created_at","created"],"title":"ConversationThreadResponse"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"ProviderType":{"type":"string","enum":["twilio","websocket","ses","sendblue","meta"],"title":"ProviderType","description":"Messaging provider that implements a channel.\n\nMultiple providers may serve the same ChannelKind."}}}} ``` ## The ConversationToolCallDetail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"type":"string","title":"Call Id"},"input":{"additionalProperties":true,"type":"object","title":"Input"},"result":{"type":"string","title":"Result","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"duration_ms":{"anyOf":[{"type":"number","maximum":3600000,"minimum":0},{"type":"null"}],"title":"Duration Ms","description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Omitted (null) on legacy turns that did not capture timing."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Failure detail recorded for the tool call when ``succeeded`` is false. Null on successful calls or when no message was captured."}},"type":"object","required":["tool_name","call_id"],"title":"ConversationToolCallDetail"}}}} ``` ## The ConversationTurn object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationTurn":{"properties":{"turn_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Turn Id","description":"Stable identifier of the user exchange this message belongs to, derived deterministically from (conversation_id, turn_index) — identical across ``POST /turns`` responses and re-reads of the conversation history. User and agent messages from the same exchange share this value. Null on messages that precede the first user turn (proactive greetings, channel-event preludes)."},"turn_index":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Turn Index","description":"Zero-based ordinal of the user exchange this message belongs to (0 = first user turn). Derived server-side from the conversation's user-turn count — never stored. Null exactly when ``turn_id`` is null."},"role":{"type":"string","enum":["agent","user","system"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelKind"},{"type":"null"}],"description":"Channel this turn occurred on. A conversation that switched channels has a self-describing per-turn history; null on turns written before per-turn attribution or on channel-less internal turns."},"content":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","title":"Content","default":[]},"tool_calls":{"items":{"$ref":"#/components/schemas/ConversationToolCallDetail"},"type":"array","title":"Tool Calls","description":"Tool calls executed during this (agent) turn. Populated only when the request opts in via ``include_tool_calls=true``; empty otherwise and on turns that did not invoke tools.","default":[]},"artifacts":{"items":{"$ref":"#/components/schemas/ClientArtifact"},"type":"array","title":"Artifacts","description":"Validated client-safe outputs produced during this agent turn.","default":[]},"selected_action_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action Description","description":"Description of the context-graph action selected for this turn. Null means no action was selected or no selected action was recorded."},"state_transition":{"anyOf":[{"$ref":"#/components/schemas/ConversationTurnStateTransition"},{"type":"null"}],"description":"Context-graph state transition that occurred during this turn. Null means no transition took place or no transition was recorded. Deprecated: use state_transitions instead. If multiple transitions were recorded, this field reports the first source state and final destination state.","deprecated":true},"state_transitions":{"items":{"$ref":"#/components/schemas/ConversationTurnStateTransition"},"type":"array","title":"State Transitions","description":"Ordered context-graph state transitions that occurred during this turn.","default":[]},"available_actions":{"items":{"$ref":"#/components/schemas/ConversationTurnAvailableAction"},"type":"array","title":"Available Actions","description":"Action choices available in the turn's resolved context-graph state. Empty when actions cannot be resolved or the resolved state is not an action state.","default":[]}},"type":"object","required":["role","text"],"title":"ConversationTurn"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"ConversationToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"type":"string","title":"Call Id"},"input":{"additionalProperties":true,"type":"object","title":"Input"},"result":{"type":"string","title":"Result","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"duration_ms":{"anyOf":[{"type":"number","maximum":3600000,"minimum":0},{"type":"null"}],"title":"Duration Ms","description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Omitted (null) on legacy turns that did not capture timing."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Failure detail recorded for the tool call when ``succeeded`` is false. Null on successful calls or when no message was captured."}},"type":"object","required":["tool_name","call_id"],"title":"ConversationToolCallDetail"},"ClientArtifact":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"payload":{"$ref":"#/components/schemas/ClientArtifactPayload"}},"type":"object","required":["type","schema_version","payload"],"title":"ClientArtifact","description":"A versioned JSON payload that a client can render as a product component."},"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]},"ConversationTurnStateTransition":{"properties":{"from":{"type":"string","title":"From","description":"Source context-graph state before the turn's state transition."},"to":{"type":"string","title":"To","description":"Destination context-graph state after the turn's state transition."}},"type":"object","required":["from","to"],"title":"ConversationTurnStateTransition"},"ConversationTurnAvailableAction":{"properties":{"description":{"type":"string","title":"Description","description":"Human-readable description of an action available in the turn's state."}},"type":"object","required":["description"],"title":"ConversationTurnAvailableAction"}}}} ``` ## The ConversationTurnAvailableAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationTurnAvailableAction":{"properties":{"description":{"type":"string","title":"Description","description":"Human-readable description of an action available in the turn's state."}},"type":"object","required":["description"],"title":"ConversationTurnAvailableAction"}}}} ``` ## The ConversationTurnStateTransition object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ConversationTurnStateTransition":{"properties":{"from":{"type":"string","title":"From","description":"Source context-graph state before the turn's state transition."},"to":{"type":"string","title":"To","description":"Destination context-graph state after the turn's state transition."}},"type":"object","required":["from","to"],"title":"ConversationTurnStateTransition"}}}} ``` ## The CostModelsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CostModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"models":{"items":{"$ref":"#/components/schemas/ModelCost"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","calculation_run_id","models"],"title":"CostModelsResponse","description":"Cost grouped by model, returned for `group_by=model`."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"ModelCost":{"properties":{"model_id":{"type":"string","title":"Model Id"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model priced subtotal rounded to cents; can be partial when is_priced is false. Null if none is priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Model priced subtotal / all model priced subtotals in the selected scope, after any service filter.\nIncludes partial subtotals; null when this model has no priced cost or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced; false can coexist with a priced subtotal."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."},"applied_rates":{"items":{"$ref":"#/components/schemas/AppliedRate"},"type":"array","title":"Applied Rates","description":"Effective-date and context-band rates used for this model."}},"type":"object","required":["model_id","calculated_cost_usd","cost_share","is_priced","unpriced_reason","applied_rates"],"title":"ModelCost","description":"Cost and pricing status for one model."},"AppliedRate":{"properties":{"input_rate_effective_from":{"type":"string","format":"date","title":"Input Rate Effective From","description":"Inclusive first usage date for the input rate."},"input_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Input Rate Effective To","description":"Exclusive end usage date for the input rate; null means no end date."},"output_rate_effective_from":{"type":"string","format":"date","title":"Output Rate Effective From","description":"Inclusive first usage date for the output rate."},"output_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Output Rate Effective To","description":"Exclusive end usage date for the output rate; null means no end date."},"cached_rate_effective_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective From","description":"Inclusive first usage date for the cached-input rate; null if no cached rate applied."},"cached_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective To","description":"Exclusive end usage date for the cached-input rate; null if unbounded or no cached rate applied."},"min_input_tokens":{"type":"integer","title":"Min Input Tokens","description":"Inclusive lower bound on per-request context input tokens for the input-rate band."},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens","description":"Inclusive upper bound on per-request context input tokens; null means unbounded."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["input_rate_effective_from","input_rate_effective_to","output_rate_effective_from","output_rate_effective_to","cached_rate_effective_from","cached_rate_effective_to","min_input_tokens","max_input_tokens","input_per_million","cached_input_per_million","output_per_million"],"title":"AppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The CostOverviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CostOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"totals":{"$ref":"#/components/schemas/CostTotals"},"services":{"items":{"$ref":"#/components/schemas/ServiceCost"},"type":"array","title":"Services","description":"Services ordered by descending calculated cost."}},"type":"object","required":["workspace_id","period","calculation_run_id","totals","services"],"title":"CostOverviewResponse","description":"Cost overview returned when `group_by` is omitted."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"CostTotals":{"properties":{"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost divided by distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"CostTotals","description":"Workspace cost totals for the requested period."},"ServiceCost":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for cost that could not be attributed."},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"This service's priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / total priced cost in the selected scope, after any service filter.\nNull when the service has no priced cost or the denominator is zero or unavailable."}},"type":"object","required":["service_id","calculated_cost_usd","cost_share"],"title":"ServiceCost","description":"Cost attributed to one service."}}}} ``` ## The CostResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CostResponse":{"anyOf":[{"$ref":"#/components/schemas/CostOverviewResponse"},{"$ref":"#/components/schemas/CostModelsResponse"}]},"CostOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"totals":{"$ref":"#/components/schemas/CostTotals"},"services":{"items":{"$ref":"#/components/schemas/ServiceCost"},"type":"array","title":"Services","description":"Services ordered by descending calculated cost."}},"type":"object","required":["workspace_id","period","calculation_run_id","totals","services"],"title":"CostOverviewResponse","description":"Cost overview returned when `group_by` is omitted."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"CostTotals":{"properties":{"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost divided by distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"CostTotals","description":"Workspace cost totals for the requested period."},"ServiceCost":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for cost that could not be attributed."},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"This service's priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / total priced cost in the selected scope, after any service filter.\nNull when the service has no priced cost or the denominator is zero or unavailable."}},"type":"object","required":["service_id","calculated_cost_usd","cost_share"],"title":"ServiceCost","description":"Cost attributed to one service."},"CostModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"models":{"items":{"$ref":"#/components/schemas/ModelCost"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","calculation_run_id","models"],"title":"CostModelsResponse","description":"Cost grouped by model, returned for `group_by=model`."},"ModelCost":{"properties":{"model_id":{"type":"string","title":"Model Id"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model priced subtotal rounded to cents; can be partial when is_priced is false. Null if none is priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Model priced subtotal / all model priced subtotals in the selected scope, after any service filter.\nIncludes partial subtotals; null when this model has no priced cost or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced; false can coexist with a priced subtotal."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."},"applied_rates":{"items":{"$ref":"#/components/schemas/AppliedRate"},"type":"array","title":"Applied Rates","description":"Effective-date and context-band rates used for this model."}},"type":"object","required":["model_id","calculated_cost_usd","cost_share","is_priced","unpriced_reason","applied_rates"],"title":"ModelCost","description":"Cost and pricing status for one model."},"AppliedRate":{"properties":{"input_rate_effective_from":{"type":"string","format":"date","title":"Input Rate Effective From","description":"Inclusive first usage date for the input rate."},"input_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Input Rate Effective To","description":"Exclusive end usage date for the input rate; null means no end date."},"output_rate_effective_from":{"type":"string","format":"date","title":"Output Rate Effective From","description":"Inclusive first usage date for the output rate."},"output_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Output Rate Effective To","description":"Exclusive end usage date for the output rate; null means no end date."},"cached_rate_effective_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective From","description":"Inclusive first usage date for the cached-input rate; null if no cached rate applied."},"cached_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective To","description":"Exclusive end usage date for the cached-input rate; null if unbounded or no cached rate applied."},"min_input_tokens":{"type":"integer","title":"Min Input Tokens","description":"Inclusive lower bound on per-request context input tokens for the input-rate band."},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens","description":"Inclusive upper bound on per-request context input tokens; null means unbounded."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["input_rate_effective_from","input_rate_effective_to","output_rate_effective_from","output_rate_effective_to","cached_rate_effective_from","cached_rate_effective_to","min_input_tokens","max_input_tokens","input_per_million","cached_input_per_million","output_per_million"],"title":"AppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The CostTotals object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CostTotals":{"properties":{"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost divided by distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"CostTotals","description":"Workspace cost totals for the requested period."}}}} ``` ## The Counterfactual object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Counterfactual":{"properties":{"timestamp_seconds":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Timestamp Seconds","description":"When the alternative action was available (seconds)"},"actual":{"type":"string","maxLength":2000,"minLength":1,"title":"Actual","description":"What the agent actually did"},"alternative":{"type":"string","maxLength":2000,"minLength":1,"title":"Alternative","description":"What it could have done instead"},"predicted_impact":{"type":"string","maxLength":2000,"minLength":1,"title":"Predicted Impact","description":"How the call would have gone differently"}},"type":"object","required":["actual","alternative","predicted_impact"],"title":"Counterfactual","description":"An alternative action that would have meaningfully changed the call outcome."}}}} ``` ## The CreateAgentRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateAgentRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""}},"type":"object","required":["name"],"title":"CreateAgentRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The CreateAgentVersionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateAgentVersionRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"initials":{"type":"string","maxLength":10,"title":"Initials","default":""},"identity":{"$ref":"#/components/schemas/Identity"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/VoiceConfig"},{"type":"null"}]},"background":{"$ref":"#/components/schemas/BackgroundString","default":""},"behaviors":{"items":{"type":"string","maxLength":2000},"type":"array","maxItems":200,"title":"Behaviors"},"communication_patterns":{"items":{"type":"string","maxLength":2000},"type":"array","maxItems":200,"title":"Communication Patterns"}},"type":"object","required":["name","identity"],"title":"CreateAgentVersionRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"Identity":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"default_spoken_language":{"type":"string","title":"Default Spoken Language"},"relationship_to_developer":{"$ref":"#/components/schemas/RelationshipToDeveloper"}},"type":"object","required":["name","role","developed_by","default_spoken_language"],"title":"Identity"},"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"},"VoiceConfig":{"properties":{"voice_id":{"type":"string","title":"Voice Id"},"stability":{"type":"number","title":"Stability","default":0},"similarity_boost":{"type":"number","title":"Similarity Boost","default":0},"style":{"type":"number","title":"Style","default":0},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"}},"type":"object","required":["voice_id"],"title":"VoiceConfig"},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"BackgroundString":{"type":"string","maxLength":10000}}}} ``` ## The CreateApiKeyRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateApiKeyRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"duration_days":{"type":"integer","maximum":90,"minimum":1,"title":"Duration Days"},"role":{"type":"string","maxLength":64,"title":"Role","default":"member"},"permissions":{"items":{"type":"string"},"type":"array","maxItems":128,"title":"Permissions","description":"Permission names. Max 128 entries; each entry up to 128 chars."}},"type":"object","required":["duration_days"],"title":"CreateApiKeyRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The CreateApiKeyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateApiKeyResponse":{"properties":{"key_id":{"type":"string","title":"Key Id"},"api_key":{"type":"string","title":"Api Key"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"created_by_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Credential Id"}},"type":"object","required":["key_id","api_key","name","role","permissions","expires_at","created_by_entity_id","created_by_credential_id"],"title":"CreateApiKeyResponse"}}}} ``` ## The CreateContextGraphRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"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}}}} ``` ## The CreateContextGraphVersionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The CreateConversationRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateConversationRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"channel":{"$ref":"#/components/schemas/ChannelKind","default":"web"},"recipient":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}],"description":"Destination address for an outbound conversation (E.164 for sms/imessage). Required for non-web."},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id","description":"Channel-manager use case the outbound conversation is sent through. Required for non-web; channel-manager resolves the sender (FROM) from it (never caller-supplied). Must be owned by this workspace."},"instruction":{"anyOf":[{"$ref":"#/components/schemas/BackgroundString"},{"type":"null"}],"description":"Optional context steering what the agent opens with on an outbound conversation."},"force_new":{"type":"boolean","title":"Force New","description":"Outbound thread-keyed channels (sms/imessage) only: close any existing ACTIVE conversation on the computed provider thread (recipient + use case) before dispatching, so the opener materializes a brand-new conversation instead of continuing the old thread. Rejected with 422 on channel=web — every web create already starts a new conversation, so force_new is meaningless there.","default":false},"context":{"additionalProperties":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string","maxLength":8192}]},"type":"object","maxProperties":50,"title":"Context","description":"Start-time context (key-value pairs) for the conversation. Validated against the owning service's accepted_context schema: unknown keys, missing required keys, or type mismatches are rejected with 422. Tools may bind individual keys to their parameters."}},"type":"object","required":["service_id"],"title":"CreateConversationRequest"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"BackgroundString":{"type":"string","maxLength":10000}}}} ``` ## The CreateDashboardRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateDashboardRequest":{"properties":{"slug":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9\\-]*$","title":"Slug"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"page_context":{"anyOf":[{"type":"string","enum":["home","patients","calls","data","analytics","pipeline","operators","surfaces","compliance","custom"]},{"type":"null"}],"title":"Page Context"},"panels":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50,"title":"Panels"},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":20,"title":"Filters"},"refresh_interval":{"type":"integer","maximum":86400,"minimum":10,"title":"Refresh Interval","default":300}},"type":"object","required":["slug","title"],"title":"CreateDashboardRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The CreateDataSourceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateDataSourceRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"display_name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"connection_config":{"additionalProperties":true,"type":"object","title":"Connection Config"},"entity_types":{"items":{"type":"string","maxLength":64,"minLength":1},"type":"array","maxItems":100,"title":"Entity Types"},"field_mappings":{"additionalProperties":true,"type":"object","title":"Field Mappings"},"sync_strategy":{"type":"string","enum":["manual","scheduled","webhook","continuous"],"title":"Sync Strategy","default":"manual"},"sync_schedule":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Sync Schedule"}},"type":"object","required":["name","source_type"],"title":"CreateDataSourceRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The CreateOperatorRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateOperatorRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"email":{"type":"string","format":"email","title":"Email"},"type":{"type":"string","enum":["clinical","administrative","crisis_counselor"],"title":"Type","default":"clinical"},"skills":{"items":{"type":"string","maxLength":64,"minLength":1},"type":"array","maxItems":50,"title":"Skills"},"connection_method":{"type":"string","enum":["browser","phone"],"title":"Connection Method","default":"phone"},"phone_number":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"role":{"type":"string","enum":["operator","supervisor","admin"],"title":"Role","default":"operator"}},"type":"object","required":["name","email"],"title":"CreateOperatorRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"PhoneE164":{"type":"string","maxLength":16,"minLength":2}}}} ``` ## The CreateOutboundCallRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateOutboundCallRequest":{"properties":{"phone_to":{"$ref":"#/components/schemas/PhoneE164","description":"Destination phone number in E.164 format."},"use_case_id":{"type":"string","format":"uuid","title":"Use Case Id","description":"Channel-manager use case ID. channel-manager selects the optimal outbound phone number bound to this use case."},"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id","description":"Patient entity UUID in the world model. Must exist in workspace as a person entity. Provide either patient_entity_id or patient_canonical_id."},"patient_canonical_id":{"anyOf":[{"$ref":"#/components/schemas/CanonicalIdString"},{"type":"null"}],"description":"Patient world model canonical_id of the form 'source:resource_type:id' (e.g. 'charmhealth:Patient:67890'). The structural regex on CanonicalIdString rejects spaces, names, DOBs, and similar regulated content so PHI cannot leak into audit events or pipeline projections. The raw value is deliberately not recorded in the outbound.initiated event — correlation back to the source system is via the resolved entity_id joined to world.entities_synced.canonical_id. Resolved against the SDP-projected world.entities_synced table; an entity created moments ago may not yet be visible if the projection is lagging. Provide either patient_entity_id or patient_canonical_id, not both."},"reason":{"$ref":"#/components/schemas/NameString","description":"Why the call is being made (e.g. appointment_reminder, follow_up, lab_results)."},"system_prompt":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"System Prompt","description":"Optional system prompt override for this call."},"goal":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}],"description":"What the call should accomplish. Injected into agent context."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10},{"type":"null"}],"title":"Tags","description":"Classification tags for analytics."},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata","description":"Arbitrary key-value pairs for external system correlation."},"context":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}]},"type":"object","title":"Context","description":"Start-time key-value context; validated against the service's accepted_context and injected into bound tool params."},"derived_from_call_sid":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Derived From Call Sid","description":"Prior call_sid if this is a callback from a previous call."},"idempotency_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Idempotency Key","description":"Client-provided idempotency key. Auto-generated if omitted."},"outbound_task_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Outbound Task Entity Id","description":"World model outbound_task entity ID for completion feedback."}},"type":"object","required":["phone_to","use_case_id","reason"],"title":"CreateOutboundCallRequest","description":"Request body for creating an outbound call.\n\n``use_case_id`` is required: channel-manager selects the optimal outbound\nphone number bound to that use case (the sole caller-ID resolution path)."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"CanonicalIdString":{"type":"string","maxLength":256,"minLength":3,"pattern":"^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The CreateOutboundCallResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateOutboundCallResponse":{"properties":{"call_sid":{"type":"string","title":"Call Sid","description":"Twilio call SID for the outbound call"},"status":{"type":"string","title":"Status","description":"Initial call status (typically 'queued')"},"phone_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone From","description":"Resolved caller ID when use_case_id was used."},"setup_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Setup Id","description":"Channel-manager setup ID when use_case_id was used."},"event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Event Id","description":"World event ID for the outbound.initiated event."}},"type":"object","required":["call_sid","status"],"title":"CreateOutboundCallResponse","description":"Response from creating an outbound call."}}}} ``` ## The CreateProductionEvalDefinitionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateProductionEvalDefinitionRequest":{"properties":{"eval_key":{"type":"string","maxLength":128,"minLength":1,"title":"Eval Key"},"eval_type":{"$ref":"#/components/schemas/ProductionEvalType"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"expected":{"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"active":{"type":"boolean","title":"Active","default":true}},"type":"object","required":["eval_key","eval_type"],"title":"CreateProductionEvalDefinitionRequest"},"ProductionEvalType":{"type":"string","enum":["metric"],"title":"ProductionEvalType"}}}} ``` ## The CreateRunRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateRunRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags"}},"type":"object","required":["service_id"],"title":"CreateRunRequest"}}}} ``` ## The CreateSchedulingRuleSetRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSchedulingRuleSetRequest":{"properties":{"agent_kind":{"type":"string","enum":["tms","ketamine","general"],"title":"Agent Kind"},"params":{"oneOf":[{"$ref":"#/components/schemas/ClinicOpenHoursParams"},{"$ref":"#/components/schemas/TMSMappingReleaseParams"},{"$ref":"#/components/schemas/TMSSessionGridParams"},{"$ref":"#/components/schemas/KetamineBlockOverlapParams"},{"$ref":"#/components/schemas/NinetyDayRollingParams"},{"$ref":"#/components/schemas/ConcurrentStartBlockParams"}],"title":"Params","description":"Per-rule-kind typed parameters. The ``rule_kind`` discriminator field selects the params shape; one row per (agent_kind, rule_kind) per workspace.","discriminator":{"propertyName":"rule_kind","mapping":{"clinic_open_hours":"#/components/schemas/ClinicOpenHoursParams","concurrent_start_block":"#/components/schemas/ConcurrentStartBlockParams","ketamine_block_overlap":"#/components/schemas/KetamineBlockOverlapParams","ninety_day_rolling":"#/components/schemas/NinetyDayRollingParams","tms_mapping_release":"#/components/schemas/TMSMappingReleaseParams","tms_session_grid":"#/components/schemas/TMSSessionGridParams"}}},"is_active":{"type":"boolean","title":"Is Active","default":true}},"type":"object","required":["agent_kind","params"],"title":"CreateSchedulingRuleSetRequest"},"ClinicOpenHoursParams":{"properties":{"rule_kind":{"type":"string","const":"clinic_open_hours","title":"Rule Kind","default":"clinic_open_hours"},"timezone":{"type":"string","maxLength":64,"minLength":1,"title":"Timezone"},"monday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"tuesday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"wednesday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"thursday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"friday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"saturday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"sunday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]}},"type":"object","required":["timezone"],"title":"ClinicOpenHoursParams","description":"Workspace clinic open-hours by weekday.\n\nDays not present mean \"closed.\" Used by the rules engine to skip\nslots outside open hours and (combined with ``weekend_skip``) by the\nTMS-mapping release calculator."},"_DayHours":{"properties":{"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"Start"},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"End"}},"type":"object","required":["start","end"],"title":"_DayHours","description":"Open-hours window for one weekday. Times in 24h ``HH:MM`` form,\ninterpreted in the rule set's ``timezone``."},"TMSMappingReleaseParams":{"properties":{"rule_kind":{"type":"string","const":"tms_mapping_release","title":"Rule Kind","default":"tms_mapping_release"},"reservation_window_hours":{"type":"integer","maximum":720,"minimum":0,"title":"Reservation Window Hours"},"weekend_skip":{"type":"boolean","title":"Weekend Skip","default":true}},"type":"object","required":["reservation_window_hours"],"title":"TMSMappingReleaseParams","description":"How long before a TMS mapping appointment its slot is released\nback to the pool. ``weekend_skip=True`` adds Saturday + Sunday days\nto the wall-clock countdown (clinic doesn't release on weekends)."},"TMSSessionGridParams":{"properties":{"rule_kind":{"type":"string","const":"tms_session_grid","title":"Rule Kind","default":"tms_session_grid"},"interval_minutes":{"type":"integer","maximum":120,"minimum":5,"title":"Interval Minutes"},"boundary_minutes":{"items":{"type":"integer"},"type":"array","maxItems":60,"minItems":1,"title":"Boundary Minutes"}},"type":"object","required":["interval_minutes","boundary_minutes"],"title":"TMSSessionGridParams","description":"TMS sessions only start at fixed minute-of-hour boundaries\n(e.g. ``:00`` and ``:30``) so the technician can run them\nback-to-back without gaps."},"KetamineBlockOverlapParams":{"properties":{"rule_kind":{"type":"string","const":"ketamine_block_overlap","title":"Rule Kind","default":"ketamine_block_overlap"},"window_days":{"type":"integer","maximum":365,"minimum":1,"title":"Window Days"}},"type":"object","required":["window_days"],"title":"KetamineBlockOverlapParams","description":"How many days after a ketamine session to block follow-up\nappointments (clinical safety window)."},"NinetyDayRollingParams":{"properties":{"rule_kind":{"type":"string","const":"ninety_day_rolling","title":"Rule Kind","default":"ninety_day_rolling"},"days":{"type":"integer","maximum":365,"minimum":1,"title":"Days"}},"type":"object","required":["days"],"title":"NinetyDayRollingParams","description":"Rolling-window cap on appointments per patient (e.g. 90 days\nbetween TMS sessions)."},"ConcurrentStartBlockParams":{"properties":{"rule_kind":{"type":"string","const":"concurrent_start_block","title":"Rule Kind","default":"concurrent_start_block"}},"type":"object","title":"ConcurrentStartBlockParams","description":"Disallow two slots starting at the same time within a TMS scope.\nNo additional params — the discriminator is the whole config."}}}} ``` ## The CreateServiceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateServiceRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"keyterms":{"items":{"type":"string","maxLength":128,"minLength":1},"type":"array","maxItems":500,"title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active","default":true},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet-Input"},"type":"object","title":"Version Sets","default":{}},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","maxItems":50,"title":"Tags"},"tool_capacity":{"type":"integer","maximum":10,"minimum":1,"title":"Tool Capacity","default":3},"channel_type":{"type":"string","enum":["voice","text"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig-Input"},{"type":"null"}]},"accepted_context":{"items":{"$ref":"#/components/schemas/ContextKeySpec"},"type":"array","maxItems":100,"title":"Accepted Context"}},"type":"object","required":["name","agent_id","context_graph_id"],"title":"CreateServiceRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"VersionSet-Input":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig-Input":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"}}}} ``` ## The CreateSessionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSessionRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags"},"caller_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Caller Id","description":"Simulated caller phone number used to resolve patient context when `entity_id` is not provided (or does not match a row). Omitted/blank values are normalized to the `sim-orchestrator` sentinel, which yields no phone match and an empty caller context — same default the voice test-call WebSocket uses, so patient lookups resolve consistently across modalities."},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Optional world entity UUID to bind caller context directly. Precedence rules: (1) when this resolves to a world entity in the workspace, it WINS — `caller_id` is not used for identity resolution, and the resolution provenance is `entity_id_lookup`; (2) when this is a well-formed UUID with no matching entity (stale, deleted, wrong workspace), the session falls back to phone lookup against `caller_id` (provenance `phone_lookup`) — no error is raised, the sim is survivable; (3) malformed UUIDs are rejected with HTTP 422 before the request reaches agent-engine. The supplied `caller_id` is still recorded on the active call and surfaced in the greeting metadata in case (1)."}},"type":"object","required":["service_id"],"title":"CreateSessionRequest"}}}} ``` ## The CreateSimulationCaseItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSimulationCaseItem":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","maxItems":100,"title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"additionalProperties":false,"type":"object","required":["description","scenario"],"title":"CreateSimulationCaseItem","description":"One durable simulation case to create."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The CreateSimulationCasesRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSimulationCasesRequest":{"properties":{"cases":{"items":{"$ref":"#/components/schemas/CreateSimulationCaseItem"},"type":"array","maxItems":100,"minItems":1,"title":"Cases"}},"additionalProperties":false,"type":"object","required":["cases"],"title":"CreateSimulationCasesRequest"},"CreateSimulationCaseItem":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","maxItems":100,"title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"additionalProperties":false,"type":"object","required":["description","scenario"],"title":"CreateSimulationCaseItem","description":"One durable simulation case to create."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The CreateSimulationCasesResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSimulationCasesResponse":{"properties":{"cases":{"items":{"$ref":"#/components/schemas/SimulationCaseResponse"},"type":"array","title":"Cases"}},"type":"object","required":["cases"],"title":"CreateSimulationCasesResponse"},"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The CreateSimulationSuiteRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSimulationSuiteRequest":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500,"title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"additionalProperties":false,"type":"object","required":["name"],"title":"CreateSimulationSuiteRequest"}}}} ``` ## The CreateSkillRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSkillRequest":{"properties":{"slug":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Slug"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"$ref":"#/components/schemas/DescriptionString"},"system_prompt":{"anyOf":[{"$ref":"#/components/schemas/BackgroundString"},{"type":"null"}]},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","maxLength":128,"minLength":1,"title":"Model","default":"claude-sonnet-5"},"max_tokens":{"type":"integer","maximum":200000,"minimum":1,"title":"Max Tokens","default":4096},"max_result_chars":{"type":"integer","maximum":200000,"minimum":1,"title":"Max Result Chars","default":2000},"max_input_tokens":{"anyOf":[{"type":"integer","maximum":2000000,"minimum":1},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","maximum":900,"minimum":0.1,"title":"Timeout S","default":60},"thinking_effort":{"anyOf":[{"$ref":"#/components/schemas/ThinkingEffort"},{"type":"null"}]},"temperature":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Temperature","description":"Anthropic sampling temperature (0-1). Ignored on models that reject sampling params (Opus 4.7+/Fable, which 400 otherwise). Set at most one of temperature/top_p -- Claude 4+ rejects both; the runtime keeps temperature and drops top_p."},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P","description":"Anthropic nucleus sampling (0-1). Ignored on sampling-param-rejecting models; see temperature."},"enable_caching":{"type":"boolean","title":"Enable Caching","default":true},"enable_citations":{"type":"boolean","title":"Enable Citations","default":false},"use_structured_output":{"type":"boolean","title":"Use Structured Output","default":false},"integration_tools":{"items":{"$ref":"#/components/schemas/IntegrationToolRef-Input"},"type":"array","maxItems":50,"title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/StaticToolDef-Input"},"type":"array","maxItems":50,"title":"Static Tools"},"enabled":{"type":"boolean","title":"Enabled","default":true},"max_agent_turns":{"type":"integer","maximum":200,"minimum":1,"title":"Max Agent Turns","default":20},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled","default":true},"approval_required":{"type":"boolean","title":"Approval Required","default":false}},"type":"object","required":["slug","name","description","input_schema"],"title":"CreateSkillRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"BackgroundString":{"type":"string","maxLength":10000},"ThinkingEffort":{"type":"string","enum":["low","medium","high"]},"IntegrationToolRef-Input":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"StaticToolDef-Input":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}}} ``` ## The CreateSurfaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSurfaceRequest":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"fields":{"items":{"$ref":"#/components/schemas/SurfaceField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"web"},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"expires_in_hours":{"type":"integer","maximum":8760,"minimum":1,"title":"Expires In Hours","default":168},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"resource_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Resource Type"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/SurfaceSection"},"type":"array"},{"type":"null"}],"title":"Sections"},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"}},"type":"object","required":["entity_id","title","fields"],"title":"CreateSurfaceRequest","description":"Request to create a new surface.\n\nThe agent generates a SurfaceSpec and sends it here."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"SurfaceField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"prefill_value":{"anyOf":[{},{"type":"null"}],"title":"Prefill Value"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"}},"type":"object","required":["key","label","field_type"],"title":"SurfaceField","description":"A single data collection field in a surface spec.\n\nGenerated by agents from HSM analysis. Each field maps\nto a specific piece of data the world model needs."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."},"SurfaceSection":{"properties":{"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["title","field_keys"],"title":"SurfaceSection","description":"A page/step in a multi-page surface form."}}}} ``` ## The CreateSurfaceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateSurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"$ref":"#/components/schemas/ChannelType"},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"expires_at":{"type":"string","title":"Expires At"},"created_at":{"type":"string","title":"Created At"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","event_id","entity_id","title","status","channel","fields_count","expires_at","created_at"],"title":"CreateSurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The CreateTriggerRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateTriggerRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"event_type":{"$ref":"#/components/schemas/TriggerableEvent"},"event_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Event Filter"},"action_id":{"type":"string","format":"uuid","title":"Action Id"},"input_template":{"additionalProperties":true,"type":"object","title":"Input Template"},"schedule":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Schedule"},"timezone":{"type":"string","maxLength":64,"minLength":1,"title":"Timezone","default":"UTC"}},"type":"object","required":["name","event_type","action_id"],"title":"CreateTriggerRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"TriggerableEvent":{"type":"string","enum":["amigo.trigger.cron","appointment.booked","appointment.cancelled","appointment.confirmed","booking.requested","call.ended","call.intelligence","call.outcome","channel.message.received","conversation.channel_switched","conversation.started","conversation.turn_recorded","coverage.created","entity.enriched","entity.resolved","medication.refill_requested","outbound.initiated","outbound.scheduled","patient.created","patient.updated","relationship.established","review.approve","review.correct","review.reject","surface.created","surface.submitted","ticket.created","triage.completed","trigger.completed","trigger.failed","trigger.fired"],"title":"TriggerableEvent","description":"Closed set of world events that trigger definitions may subscribe to.\n\nThe database column intentionally remains text for compatibility with old\nrows, but API writes must choose from this list so typoed event names do\nnot silently create never-matching triggers."}}}} ``` ## The CreateWorkspaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CreateWorkspaceRequest":{"properties":{"slug":{"$ref":"#/components/schemas/SlugString"},"name":{"$ref":"#/components/schemas/StrippedNonemptyString"},"backend_org_id":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]}},"type":"object","required":["slug","name"],"title":"CreateWorkspaceRequest","description":"Request body for ``POST /v1/me/workspaces``."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"StrippedNonemptyString":{"type":"string","minLength":1}}}} ``` ## The CustomTokenExchangeAuthDict object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}}} ``` ## The CustomTokenExchangeAuthRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CustomTokenExchangeAuthRequest":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type","default":"custom_token_exchange"},"exchange_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding","description":"``json`` (default) sends static_body_fields + param_body_fields as JSON; ``form`` sends as application/x-www-form-urlencoded.","default":"json"},"static_headers":{"patternProperties":{"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$":{"type":"string"}},"propertyNames":{"maxLength":256,"minLength":1},"type":"object","title":"Static Headers","description":"Workspace-level headers on the exchange request (keys are RFC 7230 tchar). Values may contain ``{secret}`` placeholder.","default":{}},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Workspace-level body fields keyed by RFC 6901 JSON Pointer (e.g. ``/meta/tool_name``\nfor nested fields, or ``/foo`` for a root-level field). Values may contain ``{secret}``\nplaceholder.","default":{}},"param_headers":{"patternProperties":{"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$":{"$ref":"#/components/schemas/ParamValueRequest"}},"propertyNames":{"maxLength":256,"minLength":1},"type":"object","title":"Param Headers","description":"Per-request params routed to headers on the exchange request, keyed by wire-name.","default":{}},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueRequest"},"type":"object","title":"Param Body Fields","description":"Per-request params routed to body fields on the exchange request, keyed by RFC 6901 JSON Pointer.","default":{}},"identity_bindings":{"additionalProperties":{"type":"string","enum":["principal.subject_key","principal.subject_id","external_user.subject_key"]},"type":"object","maxProperties":50,"title":"Identity Bindings","description":"Maps a declared ``param_name`` to the verified identity attribute that supplies it\nat dispatch. A bound param is dropped from the LLM-facing tool schema and injected from the\nverified session context (never model-supplied), closing the per-user-identity impersonation hole.\nKeys MUST reference a ``param_name`` declared on ``param_headers`` / ``param_body_fields``.","default":{}},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values","description":"Author-configured test values for identity-bound params.\n\nOnly ``external_user.subject_key`` bindings may carry test values. Runtime\ndispatch uses them only when a backend execution path explicitly opts in.","default":{}},"response_token_path":{"type":"string","title":"Response Token Path","description":"RFC 6901 JSON Pointer into the exchange response body that extracts the bearer token\n(e.g. ``/access_token`` or ``/data/bearer``). NO default — every config commits explicitly."}},"type":"object","required":["exchange_url","response_token_path"],"title":"CustomTokenExchangeAuthRequest","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nPath-shaped fields (``response_token_path``, ``static_body_fields`` keys,\n``param_body_fields`` keys) MUST be valid RFC 6901 JSON Pointer — one\nsyntax throughout."},"ParamValueRequest":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueRequest","description":"Routing target for a single per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthRequest.param_headers`` / ``param_body_fields``."}}}} ``` ## The DailyCallStat object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DailyCallStat":{"properties":{"date":{"type":"string","title":"Date","description":"Date string (YYYY-MM-DD)"},"count":{"type":"integer","title":"Count","description":"Number of calls on this date"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average call duration in seconds"}},"type":"object","required":["date","count"],"title":"DailyCallStat","description":"Per-day call volume and duration."}}}} ``` ## The DailyCallVolume object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DailyCallVolume":{"properties":{"date":{"type":"string","title":"Date","description":"ISO-8601 date (YYYY-MM-DD)"},"count":{"type":"integer","title":"Count","description":"Number of calls on this date"}},"type":"object","required":["date","count"],"title":"DailyCallVolume","description":"Call volume for a single date."}}}} ``` ## The DailyUsage object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DailyUsage":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"DailyUsage","description":"Token usage for one calendar date."}}}} ``` ## The DashboardDefinitionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DashboardDefinitionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id"},"slug":{"type":"string","title":"Slug","description":"URL-safe identifier"},"title":{"type":"string","title":"Title","description":"Dashboard display title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description"},"page_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Context","description":"Developer console page where this dashboard renders"},"panels":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Panels","description":"Ordered list of panel definitions"},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Filters","description":"Dashboard-level filter controls"},"refresh_interval":{"type":"integer","title":"Refresh Interval","description":"Auto-refresh interval in seconds"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the dashboard is active"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Creator identifier"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the dashboard was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the dashboard was last updated"}},"type":"object","required":["id","slug","title","panels","filters","refresh_interval","is_active"],"title":"DashboardDefinitionResponse"}}}} ``` ## The DashboardExecuteResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DashboardExecuteResponse":{"properties":{"dashboard_id":{"type":"string","format":"uuid","title":"Dashboard Id"},"results":{"items":{"$ref":"#/components/schemas/PanelResultResponse"},"type":"array","title":"Results"}},"type":"object","required":["dashboard_id","results"],"title":"DashboardExecuteResponse"},"PanelResultResponse":{"properties":{"panel_id":{"type":"string","title":"Panel Id","description":"Panel identifier from the definition"},"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names"},"rows":{"items":{"items":{},"type":"array"},"type":"array","title":"Rows","description":"Result rows"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if query failed"}},"type":"object","required":["panel_id","columns","rows"],"title":"PanelResultResponse"}}}} ``` ## The DashboardListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DashboardListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DashboardDefinitionResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"DashboardListResponse"},"DashboardDefinitionResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id"},"slug":{"type":"string","title":"Slug","description":"URL-safe identifier"},"title":{"type":"string","title":"Title","description":"Dashboard display title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description"},"page_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Context","description":"Developer console page where this dashboard renders"},"panels":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Panels","description":"Ordered list of panel definitions"},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Filters","description":"Dashboard-level filter controls"},"refresh_interval":{"type":"integer","title":"Refresh Interval","description":"Auto-refresh interval in seconds"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the dashboard is active"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Creator identifier"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the dashboard was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the dashboard was last updated"}},"type":"object","required":["id","slug","title","panels","filters","refresh_interval","is_active"],"title":"DashboardDefinitionResponse"}}}} ``` ## The DashboardResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DashboardResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"operators":{"$ref":"#/components/schemas/OperatorStatusCounts"},"active_escalations":{"type":"integer","title":"Active Escalations"},"escalations_today":{"$ref":"#/components/schemas/EscalationDailyStats"},"recent_escalations":{"items":{"$ref":"#/components/schemas/ActiveEscalationItem"},"type":"array","title":"Recent Escalations"}},"type":"object","required":["workspace_id","operators","active_escalations","escalations_today","recent_escalations"],"title":"DashboardResponse"},"OperatorStatusCounts":{"properties":{"total":{"type":"integer","title":"Total"},"online":{"type":"integer","title":"Online"},"busy":{"type":"integer","title":"Busy"},"offline":{"type":"integer","title":"Offline"}},"type":"object","required":["total","online","busy","offline"],"title":"OperatorStatusCounts"},"EscalationDailyStats":{"properties":{"requested":{"type":"integer","title":"Requested","default":0},"connected":{"type":"integer","title":"Connected","default":0},"completed":{"type":"integer","title":"Completed","default":0},"avg_wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Wait Seconds"},"avg_handle_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Handle Time Seconds"}},"type":"object","title":"EscalationDailyStats"},"ActiveEscalationItem":{"properties":{"call_entity_id":{"type":"string","format":"uuid","title":"Call Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id","description":"Escalation event ID"},"status":{"type":"string","maxLength":64,"title":"Status","description":"Current escalation state"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"What triggered the escalation"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source","description":"Source system of the trigger"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept","description":"Clinical concept that triggered escalation"},"operator_type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Operator Type","description":"Required operator specialization"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis","description":"Regulatory reason for escalation"},"immediate":{"type":"boolean","title":"Immediate","description":"Whether the escalation requires immediate attention"},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score","description":"Risk score 0.0 to 1.0"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested At","description":"ISO-8601 timestamp when escalation was requested"},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connected At","description":"ISO-8601 timestamp when operator connected"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds","description":"Seconds the caller waited for an operator"},"operator_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Operator Entity Id","description":"Entity ID of the connected operator"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id","description":"Caller phone number"},"direction":{"anyOf":[{"type":"string","enum":["inbound","outbound","playground","simulated","test"]},{"type":"null"}],"title":"Direction","description":"Call direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Service phone number"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"ISO-8601 timestamp when the call started"}},"type":"object","required":["call_entity_id","status","immediate"],"title":"ActiveEscalationItem","description":"A call with an active escalation, enriched from projected state."}}}} ``` ## The DataCollectionState-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."},"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."},"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."},"TurnPolicy":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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)."},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."}}}} ``` ## The DataCollectionState-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."},"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."},"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."},"TurnPolicy":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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)."},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."}}}} ``` ## The DataQualityMetrics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataQualityMetrics":{"properties":{"pending_reviews":{"type":"integer","title":"Pending Reviews","default":0},"approval_rate_7d":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Approval Rate 7D"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"entities_total":{"type":"integer","title":"Entities Total","default":0},"entities_merged_7d":{"type":"integer","title":"Entities Merged 7D","default":0}},"type":"object","title":"DataQualityMetrics"}}}} ``` ## The DataQualityResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataQualityResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace identifier"},"period_start":{"type":"string","format":"date","title":"Period Start","description":"Start of the reporting period"},"period_end":{"type":"string","format":"date","title":"Period End","description":"End of the reporting period"},"confidence_distribution":{"items":{"$ref":"#/components/schemas/ConfidenceBucket"},"type":"array","title":"Confidence Distribution","description":"Overall confidence distribution across buckets"},"confidence_by_source":{"additionalProperties":{"items":{"$ref":"#/components/schemas/ConfidenceBucket"},"type":"array"},"type":"object","title":"Confidence By Source","description":"Confidence distribution broken down by event source"},"review_pipeline":{"additionalProperties":true,"type":"object","title":"Review Pipeline","description":"Review pipeline throughput statistics"},"timeseries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Timeseries","description":"Daily confidence averages and event counts"},"total_events":{"type":"integer","title":"Total Events","description":"Total number of events in the period"}},"type":"object","required":["workspace_id","period_start","period_end","confidence_distribution","confidence_by_source","review_pipeline","timeseries","total_events"],"title":"DataQualityResponse","description":"Data quality metrics — confidence distribution, review pipeline stats."},"ConfidenceBucket":{"properties":{"confidence_range":{"type":"string","title":"Confidence Range","description":"Confidence level bucket label (e.g. 'raw', 'verified', 'authoritative')"},"count":{"type":"integer","title":"Count","description":"Number of events in this confidence bucket"}},"type":"object","required":["confidence_range","count"],"title":"ConfidenceBucket"}}}} ``` ## The DataQueryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataQueryResponse":{"properties":{"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"},"count":{"type":"integer","title":"Count"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","count","has_more"],"title":"DataQueryResponse"}}}} ``` ## The DataSourceListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataSourceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DataSourceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"DataSourceListResponse"},"DataSourceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"connection_config":{"additionalProperties":true,"type":"object","title":"Connection Config"},"entity_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Entity Types"},"field_mappings":{"additionalProperties":true,"type":"object","title":"Field Mappings"},"sync_strategy":{"type":"string","enum":["manual","scheduled","webhook","continuous"],"title":"Sync Strategy"},"sync_schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Schedule"},"last_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Sync At"},"last_sync_status":{"anyOf":[{"type":"string","enum":["success","error"]},{"type":"null"}],"title":"Last Sync Status"},"last_sync_event_count":{"type":"integer","title":"Last Sync Event Count"},"is_active":{"type":"boolean","title":"Is Active"},"is_stale":{"type":"boolean","title":"Is Stale"},"health_status":{"type":"string","enum":["unknown","healthy","degraded"],"title":"Health Status"},"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","display_name","source_type","connection_config","entity_types","field_mappings","sync_strategy","sync_schedule","last_sync_at","last_sync_status","last_sync_event_count","is_active","is_stale","health_status","created_at","updated_at"],"title":"DataSourceResponse"}}}} ``` ## The DataSourceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataSourceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"connection_config":{"additionalProperties":true,"type":"object","title":"Connection Config"},"entity_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Entity Types"},"field_mappings":{"additionalProperties":true,"type":"object","title":"Field Mappings"},"sync_strategy":{"type":"string","enum":["manual","scheduled","webhook","continuous"],"title":"Sync Strategy"},"sync_schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Schedule"},"last_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Sync At"},"last_sync_status":{"anyOf":[{"type":"string","enum":["success","error"]},{"type":"null"}],"title":"Last Sync Status"},"last_sync_event_count":{"type":"integer","title":"Last Sync Event Count"},"is_active":{"type":"boolean","title":"Is Active"},"is_stale":{"type":"boolean","title":"Is Stale"},"health_status":{"type":"string","enum":["unknown","healthy","degraded"],"title":"Health Status"},"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","display_name","source_type","connection_config","entity_types","field_mappings","sync_strategy","sync_schedule","last_sync_at","last_sync_status","last_sync_event_count","is_active","is_stale","health_status","created_at","updated_at"],"title":"DataSourceResponse"}}}} ``` ## The DataSourceStatusResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataSourceStatusResponse":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"name":{"type":"string","title":"Name"},"is_active":{"type":"boolean","title":"Is Active"},"health_status":{"type":"string","enum":["unknown","healthy","degraded"],"title":"Health Status"},"last_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Sync At"},"last_sync_status":{"anyOf":[{"type":"string","enum":["success","error"]},{"type":"null"}],"title":"Last Sync Status"},"last_sync_event_count":{"type":"integer","title":"Last Sync Event Count"},"event_count":{"type":"integer","title":"Event Count"},"synced_count":{"type":"integer","title":"Synced Count"},"failed_count":{"type":"integer","title":"Failed Count"}},"type":"object","required":["data_source_id","name","is_active","health_status","last_sync_at","last_sync_status","last_sync_event_count","event_count","synced_count","failed_count"],"title":"DataSourceStatusResponse"}}}} ``` ## The DataSourceSyncHistoryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataSourceSyncHistoryResponse":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"name":{"type":"string","title":"Name"},"timeline":{"items":{"$ref":"#/components/schemas/SyncHistoryEntry"},"type":"array","title":"Timeline"},"recent_failures":{"items":{"$ref":"#/components/schemas/SyncFailureEntry"},"type":"array","title":"Recent Failures"}},"type":"object","required":["data_source_id","name","timeline","recent_failures"],"title":"DataSourceSyncHistoryResponse"},"SyncHistoryEntry":{"properties":{"date":{"type":"string","title":"Date"},"event_count":{"type":"integer","title":"Event Count"},"synced_count":{"type":"integer","title":"Synced Count"},"failed_count":{"type":"integer","title":"Failed Count"}},"type":"object","required":["date","event_count","synced_count","failed_count"],"title":"SyncHistoryEntry"},"SyncFailureEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"type":"string","title":"Event Type"},"fhir_resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Type"},"fhir_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Id"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["event_id","event_type","fhir_resource_type","fhir_resource_id","sync_error","created_at"],"title":"SyncFailureEntry"}}}} ``` ## The DataTemplate-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataTemplate-Input":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"fields":{"items":{"$ref":"#/components/schemas/DataTemplateField"},"type":"array","maxItems":50,"minItems":1,"title":"Fields"}},"type":"object","required":["name","fields"],"title":"DataTemplate","description":"Named field template — reusable across multiple outreach rules."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DataTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state (e.g. demographics.date_of_birth)"}},"type":"object","required":["key","label","path"],"title":"DataTemplateField","description":"A field in a data template — maps to entity state path for gap detection."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The DataTemplate-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataTemplate-Output":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"fields":{"items":{"$ref":"#/components/schemas/DataTemplateField"},"type":"array","maxItems":50,"minItems":1,"title":"Fields"}},"type":"object","required":["name","fields"],"title":"DataTemplate","description":"Named field template — reusable across multiple outreach rules."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DataTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state (e.g. demographics.date_of_birth)"}},"type":"object","required":["key","label","path"],"title":"DataTemplateField","description":"A field in a data template — maps to entity state path for gap detection."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The DataTemplateField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DataTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state (e.g. demographics.date_of_birth)"}},"type":"object","required":["key","label","path"],"title":"DataTemplateField","description":"A field in a data template — maps to entity state path for gap detection."},"NameString":{"type":"string","maxLength":256,"minLength":1},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The DatasetRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DatasetRow":{"properties":{"name":{"type":"string","title":"Name","description":"Dataset slug (UI label \"Schema\")."},"schema_version":{"type":"string","title":"Schema Version"},"field_count":{"type":"integer","title":"Field Count"},"file_type":{"type":"string","title":"File Type","description":"Primary/representative file type (the first accepted type)."},"accepted_file_types":{"items":{"type":"string"},"type":"array","title":"Accepted File Types","description":"Document datasets: the full accepted-type set (V265). Empty for snapshot\nor legacy single-type documents (the UI falls back to ``file_type``).","default":[]},"ingestion_mode":{"type":"string","title":"Ingestion Mode","description":"`snapshot` (CSV/Excel → CDC) or `document` (PDF/docx → extraction)."},"limits":{"$ref":"#/components/schemas/Limits"}},"type":"object","required":["name","schema_version","field_count","file_type","ingestion_mode","limits"],"title":"DatasetRow","description":"A registered schema in the Schemas list (intake-ui-mvp-design.md §5.3)."},"Limits":{"properties":{"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","title":"Limits"}}}} ``` ## The DatasetUpdateRunResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DatasetUpdateRunResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"$ref":"#/components/schemas/_DatasetUpdateStatus"},"source_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Source Ids"},"batch_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Batch Ids"},"materialize_run_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Materialize Run Id"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["run_id","dataset","status","source_ids","batch_ids","created_at","updated_at"],"title":"DatasetUpdateRunResponse","description":"Durable status for one dataset update action."},"_DatasetUpdateStatus":{"type":"string","enum":["checking_drive","preparing","publishing","completed","needs_review","failed"]}}}} ``` ## The DecisionFactor object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DecisionFactor":{"properties":{"factor":{"type":"string","maxLength":2000,"minLength":1,"title":"Factor","description":"What specifically drove this decision - exact words heard or tone described"},"source_type":{"type":"string","title":"Source Type","description":"Category of the audio input"}},"type":"object","required":["factor","source_type"],"title":"DecisionFactor","description":"A specific audio input that drove an agent decision."}}}} ``` ## The DecisionState-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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)."}}}} ``` ## The DecisionState-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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)."}}}} ``` ## The DecompositionRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DecompositionRow":{"properties":{"feature_name":{"type":"string","title":"Feature Name"},"beta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Beta"},"delta_x":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta X"},"contribution":{"type":"number","title":"Contribution"},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"},"ci_lo":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ci Lo"},"ci_hi":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ci Hi"}},"type":"object","required":["feature_name","contribution"],"title":"DecompositionRow"}}}} ``` ## The Default object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"}}}} ``` ## The DeliverSurfaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DeliverSurfaceRequest":{"properties":{"channel_address":{"type":"string","maxLength":256,"minLength":1,"title":"Channel Address","description":"Delivery address (phone number, email, etc.)"}},"type":"object","required":["channel_address"],"title":"DeliverSurfaceRequest","description":"Request to mark a surface as delivered."}}}} ``` ## The DeliverSurfaceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DeliverSurfaceResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"type":"string","enum":["delivered","pending_review"],"title":"Status"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"channel_address":{"type":"string","title":"Channel Address"},"message_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message Id"},"from_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Number"},"from_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Address"},"delivery_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivery Provider"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"}},"type":"object","required":["surface_id","status","channel_address"],"title":"DeliverSurfaceResponse"},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The DescriptionString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The DestroySessionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DestroySessionResponse":{"properties":{"status":{"type":"string","const":"destroyed","title":"Status","description":"Session destruction status"}},"type":"object","required":["status"],"title":"DestroySessionResponse"}}}} ``` ## The DocumentProcessingSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DocumentProcessingSpec":{"properties":{"retain_source":{"type":"boolean","title":"Retain Source","default":true},"extraction_mode":{"type":"string","enum":["text_extract","OCR","hybrid"],"title":"Extraction Mode","default":"text_extract"}},"type":"object","title":"DocumentProcessingSpec","description":"Processing config for a document dataset (``ingestion_mode=document``).\n\nDocuments have no schema/primary-key/CDC; this is what the contract carries\ninstead (docs/plans/intake_file_processing_pipeline.md §5.9). Page-split /\noutput-metadata rules are stored in the same jsonb and may be added later\nwithout a migration."}}}} ``` ## The DriveFolderMapping object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DriveFolderMapping":{"properties":{"folder_id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Folder Id"},"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"contains_phi":{"type":"boolean","title":"Contains Phi","default":true}},"type":"object","required":["folder_id","dataset"],"title":"DriveFolderMapping","description":"One Google Drive folder ↔ one intake dataset.\n\n``folder_id`` is the Drive folder id (the identity — never the folder name,\nwhich can be renamed/moved). One folder maps to exactly one dataset."}}}} ``` ## The DropColumnAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DropColumnAction":{"properties":{"op":{"type":"string","const":"drop_column","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropColumnAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The DropColumnDefaultAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DropColumnDefaultAction":{"properties":{"op":{"type":"string","const":"drop_column_default","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropColumnDefaultAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The DropConstraintAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DropConstraintAction":{"properties":{"op":{"type":"string","const":"drop_constraint","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropConstraintAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The DropIndexAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"DropIndexAction":{"properties":{"op":{"type":"string","const":"drop_index","title":"Op"},"index_name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","index_name"],"title":"DropIndexAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The EagerEvalResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EagerEvalResponse":{"properties":{"status":{"type":"string","enum":["evaluated","skipped_over_cap"],"title":"Status"},"eval_count":{"type":"integer","title":"Eval Count"}},"type":"object","required":["status","eval_count"],"title":"EagerEvalResponse"}}}} ``` ## The EffectiveGrant object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EffectiveGrant":{"properties":{"resource_type":{"$ref":"#/components/schemas/_ResourceType"},"resource_key":{"type":"string","title":"Resource Key"},"access":{"$ref":"#/components/schemas/_Access"}},"type":"object","required":["resource_type","resource_key","access"],"title":"EffectiveGrant"},"_ResourceType":{"type":"string","enum":["integration_endpoint","skill","kb_scope"]},"_Access":{"type":"string","enum":["read","write"]}}}} ``` ## The EgressIpsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EgressIpsResponse":{"properties":{"egress_ips":{"items":{"type":"string"},"type":"array","title":"Egress Ips"},"region":{"type":"string","title":"Region"},"note":{"type":"string","title":"Note"}},"type":"object","required":["egress_ips","region","note"],"title":"EgressIpsResponse"}}}} ``` ## The EmotionSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EmotionSummary":{"properties":{"dominant_emotion":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Dominant Emotion","description":"Most frequent emotion (e.g. 'neutral', 'happy', 'angry')"},"average_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Valence","description":"Average emotional valence -1.0 to 1.0"},"average_arousal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Arousal","description":"Average emotional arousal 0.0 to 1.0"},"peak_negative_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Peak Negative Valence","description":"Most negative valence observed"},"barge_in_count":{"type":"integer","title":"Barge In Count","description":"Number of caller interruptions (emotion-tagged)","default":0}},"type":"object","title":"EmotionSummary","description":"Aggregated emotional analysis across the call.\n\nFree-form residual on the raw ``emotion_summary`` JSONB:\n``compound_emotions: list[{name, score}]``. Not exposed via this\ntyped shape — readers wanting it consume the JSONB endpoint."}}}} ``` ## The EmotionalShift object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EmotionalShift":{"properties":{"timestamp_seconds":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Timestamp Seconds","description":"When the shift occurred (seconds from start)"},"from_state":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"From State","description":"Emotional state before the shift"},"to_state":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"To State","description":"Emotional state after the shift"},"trigger":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Trigger","description":"What caused the shift - exact words and tone"},"agent_awareness":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Agent Awareness","description":"Whether the agent noticed and responded to this shift"}},"type":"object","title":"EmotionalShift","description":"A critical emotional state change detected in the caller's voice."}}}} ``` ## The EmotionalSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EmotionalSummary":{"properties":{"dominant_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dominant Emotion"},"average_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Valence"},"average_arousal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Arousal"},"peak_negative_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Peak Negative Valence"},"peak_negative_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Peak Negative Emotion"},"emotional_shifts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Emotional Shifts"},"final_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Trend"},"segment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Segment Count"},"barge_in_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Barge In Count"},"compound_emotions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Compound Emotions"}},"type":"object","title":"EmotionalSummary"}}}} ``` ## The EndpointResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EndpointResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs."},"name":{"type":"string","title":"Name","description":"Slug-like identifier. Unique per integration; immutable post-create."},"description":{"type":"string","title":"Description","description":"LLM-facing description."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method."},"path":{"type":"string","title":"Path","description":"URL path appended to the integration's base_url."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema for the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static request headers."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into every request. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding.","default":"json"},"response_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Template","description":"Jinja template rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Opt-in typed artifact contract for external-user conversation delivery."},"max_response_length":{"type":"integer","title":"Max Response Length","description":"Truncate the final rendered string to this many chars.","default":0},"timeout_seconds":{"type":"number","title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["id","name","description","method","path"],"title":"EndpointResponse","description":"Per-endpoint response (V186 flat shape)."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."}}}} ``` ## The EnrichmentHistoryEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentHistoryEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"value":{"title":"Value"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"confidence":{"type":"number","title":"Confidence"},"source":{"type":"string","title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"type":"string","format":"date-time","title":"Ingested At"},"supersedes":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Supersedes"},"is_current":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Current"}},"type":"object","required":["event_id","value","value_type","confidence","source","ingested_at","is_current"],"title":"EnrichmentHistoryEntry"}}}} ``` ## The EnrichmentHistoryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentHistoryResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"key":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_\\-]*$","title":"Key"},"history":{"items":{"$ref":"#/components/schemas/EnrichmentHistoryEntry"},"type":"array","title":"History"},"dropped_count":{"type":"integer","title":"Dropped Count","default":0}},"type":"object","required":["entity_id","key","history"],"title":"EnrichmentHistoryResponse"},"EnrichmentHistoryEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"value":{"title":"Value"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"confidence":{"type":"number","title":"Confidence"},"source":{"type":"string","title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"type":"string","format":"date-time","title":"Ingested At"},"supersedes":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Supersedes"},"is_current":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Current"}},"type":"object","required":["event_id","value","value_type","confidence","source","ingested_at","is_current"],"title":"EnrichmentHistoryEntry"}}}} ``` ## The EnrichmentKeyCreateBody object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentKeyCreateBody":{"properties":{"entity_type":{"type":"string","maxLength":64,"minLength":1,"title":"Entity Type"},"key":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_\\-]*$","title":"Key"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"allowed_values":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Allowed Values","description":"Required when value_type=enum. Ignored otherwise."},"source_hint":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"min_confidence":{"type":"number","maximum":1,"minimum":0,"title":"Min Confidence","default":0},"is_pii":{"type":"boolean","title":"Is Pii","default":false},"tags":{"items":{"type":"string","const":"memory_extract"},"type":"array","title":"Tags","description":"Routing tags. 'memory_extract' opts this key into memory extraction — the conversation extractor will infer it from transcripts as a workspace-custom memory dimension (person keys with a description only)."}},"type":"object","required":["entity_type","key","value_type"],"title":"EnrichmentKeyCreateBody"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The EnrichmentKeyListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentKeyListResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/EnrichmentKeyResponse"},"type":"array","title":"Keys"}},"type":"object","required":["keys"],"title":"EnrichmentKeyListResponse"},"EnrichmentKeyResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"entity_type":{"type":"string","maxLength":64,"minLength":1,"title":"Entity Type"},"key":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_\\-]*$","title":"Key"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"allowed_values":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Allowed Values"},"source_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Hint"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"min_confidence":{"type":"number","title":"Min Confidence"},"is_pii":{"type":"boolean","title":"Is Pii"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","default":[]},"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","entity_type","key","value_type","min_confidence","is_pii","created_at","updated_at"],"title":"EnrichmentKeyResponse"}}}} ``` ## The EnrichmentKeyPatchBody object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentKeyPatchBody":{"properties":{"allowed_values":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Allowed Values"},"source_hint":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"min_confidence":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Min Confidence"},"is_pii":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Pii"},"tags":{"anyOf":[{"items":{"type":"string","const":"memory_extract"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Replaces the full tags list when set. Pass [] to remove all tags."}},"type":"object","title":"EnrichmentKeyPatchBody"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The EnrichmentKeyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentKeyResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"entity_type":{"type":"string","maxLength":64,"minLength":1,"title":"Entity Type"},"key":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_\\-]*$","title":"Key"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"allowed_values":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Allowed Values"},"source_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Hint"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"min_confidence":{"type":"number","title":"Min Confidence"},"is_pii":{"type":"boolean","title":"Is Pii"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","default":[]},"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","entity_type","key","value_type","min_confidence","is_pii","created_at","updated_at"],"title":"EnrichmentKeyResponse"}}}} ``` ## The EnrichmentListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentListResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"values":{"items":{"$ref":"#/components/schemas/EnrichmentValueResponse"},"type":"array","title":"Values"}},"type":"object","required":["entity_id","values"],"title":"EnrichmentListResponse"},"EnrichmentValueResponse":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_\\-]*$","title":"Key"},"value":{"title":"Value"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"confidence":{"type":"number","title":"Confidence"},"source":{"type":"string","title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"overlay_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Overlay Status"}},"type":"object","required":["key","value","value_type","confidence","source","event_id"],"title":"EnrichmentValueResponse"}}}} ``` ## The EnrichmentValueResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentValueResponse":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z0-9][a-z0-9_\\-]*$","title":"Key"},"value":{"title":"Value"},"value_type":{"type":"string","enum":["string","number","boolean","date","enum","json"],"title":"Value Type"},"confidence":{"type":"number","title":"Confidence"},"source":{"type":"string","title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"overlay_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Overlay Status"}},"type":"object","required":["key","value","value_type","confidence","source","event_id"],"title":"EnrichmentValueResponse"}}}} ``` ## The EnrichmentWriteBody object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EnrichmentWriteBody":{"properties":{"value":{"title":"Value","description":"Scalar or JSON-compatible value to store."},"value_type":{"anyOf":[{"type":"string","enum":["string","number","boolean","date","enum","json"]},{"type":"null"}],"title":"Value Type","description":"Overrides the registry value_type when set. Rarely needed."},"source":{"type":"string","maxLength":64,"minLength":1,"title":"Source","description":"Write source — e.g. manual, forms, auto_enrich.","default":"manual"},"source_system":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Source System","description":"Subsystem / connector identifier."},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence","description":"Write confidence. Must be >= registry min_confidence for the key.","default":1},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At","description":"When the value became true (UTC). Defaults to ingested_at."}},"type":"object","required":["value"],"title":"EnrichmentWriteBody"}}}} ``` ## The EntityEventResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"domain":{"type":"string","title":"Domain"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"event_type":{"type":"string","title":"Event Type"},"event_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Subtype"},"fhir_resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Type"},"fhir_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Id"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","default":"manual"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","default":1},"produced_by_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Produced By Agent"},"display_name":{"anyOf":[{"$ref":"#/components/schemas/EventDisplayNameString"},{"type":"null"}]},"status":{"anyOf":[{"$ref":"#/components/schemas/EventStatusString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/EventDescriptionString"},{"type":"null"}]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/EventOutcomeString"},{"type":"null"}]},"channel":{"anyOf":[{"$ref":"#/components/schemas/EventChannelString"},{"type":"null"}]},"call_sid":{"anyOf":[{"$ref":"#/components/schemas/EventCallSidString"},{"type":"null"}]},"direction":{"anyOf":[{"$ref":"#/components/schemas/EventDirectionString"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"supersedes":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Supersedes"},"is_current":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Current","default":true},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At"},"synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Synced At"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"sync_status":{"anyOf":[{"type":"string","enum":["pending","synced","failed","processing","not_applicable"]},{"type":"null"}],"title":"Sync Status"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event was created"}},"type":"object","required":["id","domain","event_type"],"title":"EntityEventResponse"},"EventDisplayNameString":{"type":"string","maxLength":512},"EventStatusString":{"type":"string","maxLength":128},"EventDescriptionString":{"type":"string","maxLength":4096},"EventOutcomeString":{"type":"string","maxLength":256},"EventChannelString":{"type":"string","maxLength":64},"EventCallSidString":{"type":"string","maxLength":128},"EventDirectionString":{"type":"string","maxLength":64}}}} ``` ## The EntityListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityListResponse":{"properties":{"entities":{"items":{"$ref":"#/components/schemas/EntityResponse"},"type":"array","title":"Entities"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More"},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["entities","total","has_more"],"title":"EntityListResponse"},"EntityResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"entity_type":{"type":"string","title":"Entity Type"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"external_ids":{"additionalProperties":true,"type":"object","title":"External Ids"},"state":{"additionalProperties":true,"type":"object","title":"State","description":"Full JSONB state blob. Prefer typed fields below.","deprecated":true},"has_projection":{"type":"boolean","title":"Has Projection","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name (person, organization)"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Primary phone number (E.164)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Primary email address"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn","description":"Medical record number"},"appointment_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Status","description":"Appointment status (booked, confirmed, cancelled)"},"appointment_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Appointment Start","description":"Appointment start time (UTC)"},"appointment_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Appointment End","description":"Appointment end time (UTC)"},"appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Type","description":"Appointment/visit type"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Organization domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Organization industry"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction","description":"Call direction (inbound, outbound)"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Call duration in seconds"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Entity status"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Primary data source"},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Seen At"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"event_count":{"type":"integer","title":"Event Count","default":0},"confidence":{"type":"number","title":"Confidence","default":1},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated"}},"type":"object","required":["id","workspace_id","entity_type"],"title":"EntityResponse"}}}} ``` ## The EntityRelationshipResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityRelationshipResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_entity_id":{"type":"string","format":"uuid","title":"Source Entity Id"},"source_entity_type":{"type":"string","title":"Source Entity Type"},"target_entity_id":{"type":"string","format":"uuid","title":"Target Entity Id"},"target_entity_type":{"type":"string","title":"Target Entity Type"},"relationship":{"type":"string","title":"Relationship"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"confidence":{"type":"number","title":"Confidence","default":1},"discovered_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discovered By"},"is_current":{"type":"boolean","title":"Is Current","default":true},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the relationship was created"}},"type":"object","required":["id","source_entity_id","source_entity_type","target_entity_id","target_entity_type","relationship"],"title":"EntityRelationshipResponse"}}}} ``` ## The EntityRelationshipsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityRelationshipsResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"relationships":{"items":{"$ref":"#/components/schemas/EntityRelationshipResponse"},"type":"array","title":"Relationships"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["entity_id","relationships","total"],"title":"EntityRelationshipsResponse"},"EntityRelationshipResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source_entity_id":{"type":"string","format":"uuid","title":"Source Entity Id"},"source_entity_type":{"type":"string","title":"Source Entity Type"},"target_entity_id":{"type":"string","format":"uuid","title":"Target Entity Id"},"target_entity_type":{"type":"string","title":"Target Entity Type"},"relationship":{"type":"string","title":"Relationship"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"confidence":{"type":"number","title":"Confidence","default":1},"discovered_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discovered By"},"is_current":{"type":"boolean","title":"Is Current","default":true},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the relationship was created"}},"type":"object","required":["id","source_entity_id","source_entity_type","target_entity_id","target_entity_type","relationship"],"title":"EntityRelationshipResponse"}}}} ``` ## The EntityResolutionMetrics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResolutionMetrics":{"properties":{"total_same_as_edges":{"type":"integer","title":"Total Same As Edges"},"recent_merges_24h":{"type":"integer","title":"Recent Merges 24H"},"loop_status":{"type":"string","title":"Loop Status"},"last_tick_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Tick At"}},"type":"object","required":["total_same_as_edges","recent_merges_24h","loop_status"],"title":"EntityResolutionMetrics"}}}} ``` ## The EntityResolveExternalId object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResolveExternalId":{"properties":{"system":{"$ref":"#/components/schemas/ExternalSystemString","description":"External system label (lowercase, e.g. 'epic')."},"value":{"$ref":"#/components/schemas/ExternalValueString","description":"System-issued identifier."}},"type":"object","required":["system","value"],"title":"EntityResolveExternalId","description":"Reference to an external-system identifier.\n\n``system`` labels which system minted the value (``epic``, ``charm``,\n``charmhealth``, …). Resolution probes the canonical entity map\n(``world.canonical_entity_map_synced``) with the candidate key forms\n``{system}:{ResourceType}:{value}`` (Patient / Practitioner /\nOrganization / Appointment) plus the bare ``value`` — so ``system``\nconstrains the probe keys, and the request's ``entity_type``\nconstrains the map slice. External aliases that were never minted as\ncanonical keys (the legacy ``external_ids`` JSONB junk-drawer\nentries) are no longer resolvable."},"ExternalSystemString":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_\\-]+$"},"ExternalValueString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The EntityResolveMatch object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResolveMatch":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"entity_type":{"type":"string","title":"Entity Type"},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence","description":"Match confidence (0-1)."},"matched_on":{"items":{"type":"string","enum":["entity_id","phone","email","canonical_id","external_id"]},"type":"array","title":"Matched On","description":"Identifier kinds that actually matched this row."},"summary":{"$ref":"#/components/schemas/EntityResolveSummary"}},"type":"object","required":["entity_id","entity_type","confidence","summary"],"title":"EntityResolveMatch","description":"One candidate match with provenance + confidence."},"EntityResolveSummary":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id","description":"Canonical-map value when resolved through the map, else the entity's MRN."},"external_ids":{"additionalProperties":true,"type":"object","title":"External Ids","description":"Always {} — external aliases live in the canonical entity map, not on the serving row."},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"event_count":{"type":"integer","title":"Event Count","default":0},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Always [] — no tags column on the synced serving table."}},"type":"object","title":"EntityResolveSummary","description":"Compact identity card returned for each match.\n\nExcludes full entity state — fetch via\n``GET /v1/{ws}/entities/{entity_id}`` if needed. The fields here are\nthe ones a UI / agent needs to confirm \"yes, that's the right\nperson\" before paying for the full state read.\n\nStage-7 narrowing (resolver serves from ``entities_synced`` +\nthe canonical entity map; fields retained for wire compatibility):\n``external_ids`` is always ``{}`` and ``tags`` is always ``[]`` —\nneither survives on the synced serving table. ``canonical_id`` is\nthe canonical-map value when the row resolved through the map, else\nthe entity's MRN."}}}} ``` ## The EntityResolveRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResolveRequest":{"properties":{"entity_type":{"$ref":"#/components/schemas/EntityTypeString","description":"Required entity type filter (e.g. 'person'). Narrows the scan to the right index."},"phone":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}],"description":"E.164 phone number."},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Primary email (case-insensitive match)."},"canonical_id":{"anyOf":[{"$ref":"#/components/schemas/CanonicalIdLookupString"},{"type":"null"}],"description":"Canonical identifier as carried by the canonical entity map (e.g. 'charm:Patient:42'; a raw MRN resolves only when a producer minted it as the canonical_id)."},"external_id":{"anyOf":[{"$ref":"#/components/schemas/EntityResolveExternalId"},{"type":"null"}],"description":"External-system identifier reference."},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Direct UUID lookup. Useful for confirming an entity exists / re-fetching summary."},"limit":{"type":"integer","maximum":50,"minimum":1,"title":"Limit","description":"Maximum candidates to return.","default":25}},"type":"object","required":["entity_type"],"title":"EntityResolveRequest","description":"Polymorphic identifier query.\n\nProvide ``entity_type`` plus any subset of identifier fields. Each\nidentifier is OR-ed in SQL; matches are ranked by confidence and\nby the number of identifiers that actually matched the row.\nReturns at most ``limit`` candidates (default 25, max 50).\n\nFor latency-sensitive callers (inbound voice, webhook handlers),\npass exactly one identifier — the indexed lookup is sub-10ms.\nMulti-identifier queries are useful for confirming a row matches\non more than one signal (phone + email + MRN)."},"EntityTypeString":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_]+$"},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"CanonicalIdLookupString":{"type":"string","maxLength":256,"minLength":1},"EntityResolveExternalId":{"properties":{"system":{"$ref":"#/components/schemas/ExternalSystemString","description":"External system label (lowercase, e.g. 'epic')."},"value":{"$ref":"#/components/schemas/ExternalValueString","description":"System-issued identifier."}},"type":"object","required":["system","value"],"title":"EntityResolveExternalId","description":"Reference to an external-system identifier.\n\n``system`` labels which system minted the value (``epic``, ``charm``,\n``charmhealth``, …). Resolution probes the canonical entity map\n(``world.canonical_entity_map_synced``) with the candidate key forms\n``{system}:{ResourceType}:{value}`` (Patient / Practitioner /\nOrganization / Appointment) plus the bare ``value`` — so ``system``\nconstrains the probe keys, and the request's ``entity_type``\nconstrains the map slice. External aliases that were never minted as\ncanonical keys (the legacy ``external_ids`` JSONB junk-drawer\nentries) are no longer resolvable."},"ExternalSystemString":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_\\-]+$"},"ExternalValueString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The EntityResolveResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResolveResponse":{"properties":{"matches":{"items":{"$ref":"#/components/schemas/EntityResolveMatch"},"type":"array","title":"Matches"},"total":{"type":"integer","minimum":0,"title":"Total","description":"Number of candidates returned."}},"type":"object","required":["total"],"title":"EntityResolveResponse"},"EntityResolveMatch":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"entity_type":{"type":"string","title":"Entity Type"},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence","description":"Match confidence (0-1)."},"matched_on":{"items":{"type":"string","enum":["entity_id","phone","email","canonical_id","external_id"]},"type":"array","title":"Matched On","description":"Identifier kinds that actually matched this row."},"summary":{"$ref":"#/components/schemas/EntityResolveSummary"}},"type":"object","required":["entity_id","entity_type","confidence","summary"],"title":"EntityResolveMatch","description":"One candidate match with provenance + confidence."},"EntityResolveSummary":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id","description":"Canonical-map value when resolved through the map, else the entity's MRN."},"external_ids":{"additionalProperties":true,"type":"object","title":"External Ids","description":"Always {} — external aliases live in the canonical entity map, not on the serving row."},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"event_count":{"type":"integer","title":"Event Count","default":0},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Always [] — no tags column on the synced serving table."}},"type":"object","title":"EntityResolveSummary","description":"Compact identity card returned for each match.\n\nExcludes full entity state — fetch via\n``GET /v1/{ws}/entities/{entity_id}`` if needed. The fields here are\nthe ones a UI / agent needs to confirm \"yes, that's the right\nperson\" before paying for the full state read.\n\nStage-7 narrowing (resolver serves from ``entities_synced`` +\nthe canonical entity map; fields retained for wire compatibility):\n``external_ids`` is always ``{}`` and ``tags`` is always ``[]`` —\nneither survives on the synced serving table. ``canonical_id`` is\nthe canonical-map value when the row resolved through the map, else\nthe entity's MRN."}}}} ``` ## The EntityResolveSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResolveSummary":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id","description":"Canonical-map value when resolved through the map, else the entity's MRN."},"external_ids":{"additionalProperties":true,"type":"object","title":"External Ids","description":"Always {} — external aliases live in the canonical entity map, not on the serving row."},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"event_count":{"type":"integer","title":"Event Count","default":0},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Always [] — no tags column on the synced serving table."}},"type":"object","title":"EntityResolveSummary","description":"Compact identity card returned for each match.\n\nExcludes full entity state — fetch via\n``GET /v1/{ws}/entities/{entity_id}`` if needed. The fields here are\nthe ones a UI / agent needs to confirm \"yes, that's the right\nperson\" before paying for the full state read.\n\nStage-7 narrowing (resolver serves from ``entities_synced`` +\nthe canonical entity map; fields retained for wire compatibility):\n``external_ids`` is always ``{}`` and ``tags`` is always ``[]`` —\nneither survives on the synced serving table. ``canonical_id`` is\nthe canonical-map value when the row resolved through the map, else\nthe entity's MRN."}}}} ``` ## The EntityResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"entity_type":{"type":"string","title":"Entity Type"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"external_ids":{"additionalProperties":true,"type":"object","title":"External Ids"},"state":{"additionalProperties":true,"type":"object","title":"State","description":"Full JSONB state blob. Prefer typed fields below.","deprecated":true},"has_projection":{"type":"boolean","title":"Has Projection","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name (person, organization)"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Primary phone number (E.164)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Primary email address"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn","description":"Medical record number"},"appointment_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Status","description":"Appointment status (booked, confirmed, cancelled)"},"appointment_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Appointment Start","description":"Appointment start time (UTC)"},"appointment_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Appointment End","description":"Appointment end time (UTC)"},"appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Type","description":"Appointment/visit type"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Organization domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Organization industry"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction","description":"Call direction (inbound, outbound)"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Call duration in seconds"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Entity status"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Primary data source"},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Seen At"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"event_count":{"type":"integer","title":"Event Count","default":0},"confidence":{"type":"number","title":"Confidence","default":1},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated"}},"type":"object","required":["id","workspace_id","entity_type"],"title":"EntityResponse"}}}} ``` ## The EntityStatsSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityStatsSummary":{"properties":{"total_entities":{"type":"integer","title":"Total Entities"},"total_events":{"type":"integer","title":"Total Events"},"sync_pending":{"type":"integer","title":"Sync Pending"},"sync_synced":{"type":"integer","title":"Sync Synced"},"sync_failed":{"type":"integer","title":"Sync Failed"},"by_event_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Event Type"}},"type":"object","required":["total_entities","total_events","sync_pending","sync_synced","sync_failed"],"title":"EntityStatsSummary"}}}} ``` ## The EntityTimelineResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityTimelineResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"events":{"items":{"$ref":"#/components/schemas/EntityEventResponse"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More"},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["entity_id","events","total","has_more"],"title":"EntityTimelineResponse"},"EntityEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"domain":{"type":"string","title":"Domain"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"event_type":{"type":"string","title":"Event Type"},"event_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Subtype"},"fhir_resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Type"},"fhir_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Id"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","default":"manual"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","default":1},"produced_by_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Produced By Agent"},"display_name":{"anyOf":[{"$ref":"#/components/schemas/EventDisplayNameString"},{"type":"null"}]},"status":{"anyOf":[{"$ref":"#/components/schemas/EventStatusString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/EventDescriptionString"},{"type":"null"}]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/EventOutcomeString"},{"type":"null"}]},"channel":{"anyOf":[{"$ref":"#/components/schemas/EventChannelString"},{"type":"null"}]},"call_sid":{"anyOf":[{"$ref":"#/components/schemas/EventCallSidString"},{"type":"null"}]},"direction":{"anyOf":[{"$ref":"#/components/schemas/EventDirectionString"},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"supersedes":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Supersedes"},"is_current":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Current","default":true},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At"},"synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Synced At"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"sync_status":{"anyOf":[{"type":"string","enum":["pending","synced","failed","processing","not_applicable"]},{"type":"null"}],"title":"Sync Status"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event was created"}},"type":"object","required":["id","domain","event_type"],"title":"EntityEventResponse"},"EventDisplayNameString":{"type":"string","maxLength":512},"EventStatusString":{"type":"string","maxLength":128},"EventDescriptionString":{"type":"string","maxLength":4096},"EventOutcomeString":{"type":"string","maxLength":256},"EventChannelString":{"type":"string","maxLength":64},"EventCallSidString":{"type":"string","maxLength":128},"EventDirectionString":{"type":"string","maxLength":64}}}} ``` ## The EntityTypeRegistryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityTypeRegistryResponse":{"properties":{"entity_types":{"items":{"$ref":"#/components/schemas/EntityTypeSummary"},"type":"array","title":"Entity Types"},"total_entities":{"type":"integer","title":"Total Entities"}},"type":"object","required":["entity_types","total_entities"],"title":"EntityTypeRegistryResponse"},"EntityTypeSummary":{"properties":{"entity_type":{"type":"string","title":"Entity Type"},"count":{"type":"integer","title":"Count"},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated"},"has_projection":{"type":"boolean","title":"Has Projection"}},"type":"object","required":["entity_type","count","last_updated","has_projection"],"title":"EntityTypeSummary"}}}} ``` ## The EntityTypeString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityTypeString":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_]+$"}}}} ``` ## The EntityTypeSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EntityTypeSummary":{"properties":{"entity_type":{"type":"string","title":"Entity Type"},"count":{"type":"integer","title":"Count"},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated"},"has_projection":{"type":"boolean","title":"Has Projection"}},"type":"object","required":["entity_type","count","last_updated","has_projection"],"title":"EntityTypeSummary"}}}} ``` ## The EscalationDailyStats object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EscalationDailyStats":{"properties":{"requested":{"type":"integer","title":"Requested","default":0},"connected":{"type":"integer","title":"Connected","default":0},"completed":{"type":"integer","title":"Completed","default":0},"avg_wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Wait Seconds"},"avg_handle_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Handle Time Seconds"}},"type":"object","title":"EscalationDailyStats"}}}} ``` ## The EscalationEventListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EscalationEventListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EscalationEventResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"EscalationEventListResponse"},"EscalationEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"event_type":{"type":"string","title":"Event Type","description":"Event type (e.g. escalation.requested, escalation.connected)"},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Event payload — shape varies by event_type"},"source":{"type":"string","title":"Source","description":"System that emitted the event"},"confidence":{"type":"number","title":"Confidence","description":"Confidence score 0.0 to 1.0"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At","description":"When the event was ingested"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event occurred"}},"type":"object","required":["id","workspace_id","event_type","data","source","confidence"],"title":"EscalationEventResponse"}}}} ``` ## The EscalationEventResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EscalationEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"event_type":{"type":"string","title":"Event Type","description":"Event type (e.g. escalation.requested, escalation.connected)"},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Event payload — shape varies by event_type"},"source":{"type":"string","title":"Source","description":"System that emitted the event"},"confidence":{"type":"number","title":"Confidence","description":"Confidence score 0.0 to 1.0"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At","description":"When the event was ingested"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event occurred"}},"type":"object","required":["id","workspace_id","event_type","data","source","confidence"],"title":"EscalationEventResponse"}}}} ``` ## The EscalationState object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EscalationState":{"properties":{"status":{"type":"string","title":"Status","default":"none"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id"},"requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Requested At"},"connected_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Connected At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Completed At"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger"},"trigger_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Source"},"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity"},"agent_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Confidence"},"operator_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Type"},"regulatory_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regulatory Basis"},"immediate":{"type":"boolean","title":"Immediate","default":false},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"operator_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator Entity Id"},"wait_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wait Seconds"},"handle_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Handle Time Seconds"},"human_segment_turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Human Segment Turn Count"}},"type":"object","title":"EscalationState"}}}} ``` ## The EscalationStatsBucket object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EscalationStatsBucket":{"properties":{"key":{"type":"string","title":"Key"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"EscalationStatsBucket"}}}} ``` ## The EscalationStatsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EscalationStatsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"type":"string","title":"Period"},"group_by":{"type":"string","title":"Group By"},"buckets":{"items":{"$ref":"#/components/schemas/EscalationStatsBucket"},"type":"array","title":"Buckets"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["workspace_id","period","group_by","buckets","total"],"title":"EscalationStatsResponse"},"EscalationStatsBucket":{"properties":{"key":{"type":"string","title":"Key"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"EscalationStatsBucket"}}}} ``` ## The EvalQualityResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EvalQualityResponse":{"properties":{"summary":{"$ref":"#/components/schemas/EvalQualitySummary","description":"Workspace-wide aggregate for the period"},"by_eval_key":{"items":{"$ref":"#/components/schemas/EvalQualitySummary"},"type":"array","maxItems":200,"title":"By Eval Key","description":"Per-eval-key aggregates, most-evaluated first"},"trend":{"items":{"$ref":"#/components/schemas/EvalQualityTrendPoint"},"type":"array","maxItems":2200,"title":"Trend","description":"Time series of eval pass-rate/score per interval bucket"}},"type":"object","required":["summary","by_eval_key","trend"],"title":"EvalQualityResponse","description":"Production-eval quality: overall pass-rate/score, per-eval-key breakdown, and a trend.\n\nThe channel-agnostic quality surface. Returns zeroed shapes (empty ``by_eval_key``\nand ``trend``, null rates) when no verdicts exist for the workspace/window — the\nconsole renders an empty-state rather than erroring, so this ships safely ahead of\nthe eager-eval trigger being enabled in production."},"EvalQualitySummary":{"properties":{"eval_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eval Key","description":"Eval key for a per-key row; null for the overall summary"},"total_evals":{"type":"integer","title":"Total Evals","description":"Total verdicts recorded (any status, incl. errored)"},"judged":{"type":"integer","title":"Judged","description":"Verdicts with a non-null pass/fail outcome (denominator for pass_rate)"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"Fraction of judged verdicts that passed (0.0-1.0)"},"avg_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Score","description":"Mean numeric judge score across scored verdicts"}},"type":"object","required":["total_evals","judged"],"title":"EvalQualitySummary","description":"Aggregate production-eval verdict stats, overall or for one eval_key.\n\nSourced from ``call_eval_results`` (LLM-judge + assertion verdicts), which is\nkeyed by ``conversation_id`` and therefore CHANNEL-AGNOSTIC — voice, text,\nSMS, email all contribute equally, unlike the voice-shaped call-quality score."},"EvalQualityTrendPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date bucket (granularity follows `interval`)"},"total_evals":{"type":"integer","title":"Total Evals","description":"Total verdicts in this bucket"},"judged":{"type":"integer","title":"Judged","description":"Verdicts with a non-null pass/fail outcome in this bucket"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"Fraction of judged verdicts that passed in this bucket"},"avg_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Score","description":"Mean numeric judge score in this bucket"}},"type":"object","required":["date","total_evals","judged"],"title":"EvalQualityTrendPoint","description":"Single date-bucket data point in the eval-quality trend series."}}}} ``` ## The EvalQualitySummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EvalQualitySummary":{"properties":{"eval_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eval Key","description":"Eval key for a per-key row; null for the overall summary"},"total_evals":{"type":"integer","title":"Total Evals","description":"Total verdicts recorded (any status, incl. errored)"},"judged":{"type":"integer","title":"Judged","description":"Verdicts with a non-null pass/fail outcome (denominator for pass_rate)"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"Fraction of judged verdicts that passed (0.0-1.0)"},"avg_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Score","description":"Mean numeric judge score across scored verdicts"}},"type":"object","required":["total_evals","judged"],"title":"EvalQualitySummary","description":"Aggregate production-eval verdict stats, overall or for one eval_key.\n\nSourced from ``call_eval_results`` (LLM-judge + assertion verdicts), which is\nkeyed by ``conversation_id`` and therefore CHANNEL-AGNOSTIC — voice, text,\nSMS, email all contribute equally, unlike the voice-shaped call-quality score."}}}} ``` ## The EvalQualityTrendPoint object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EvalQualityTrendPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date bucket (granularity follows `interval`)"},"total_evals":{"type":"integer","title":"Total Evals","description":"Total verdicts in this bucket"},"judged":{"type":"integer","title":"Judged","description":"Verdicts with a non-null pass/fail outcome in this bucket"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"Fraction of judged verdicts that passed in this bucket"},"avg_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Score","description":"Mean numeric judge score in this bucket"}},"type":"object","required":["date","total_evals","judged"],"title":"EvalQualityTrendPoint","description":"Single date-bucket data point in the eval-quality trend series."}}}} ``` ## The EvaluationResultView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."}}}} ``` ## The EventBreakdownItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventBreakdownItem":{"properties":{"key":{"type":"string","title":"Key","description":"Grouping key (event type or source name)"},"count":{"type":"integer","title":"Count","description":"Number of events for this key"}},"type":"object","required":["key","count"],"title":"EventBreakdownItem","description":"Single row in an event breakdown aggregation."}}}} ``` ## The EventBreakdownResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventBreakdownResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace identifier"},"period_start":{"type":"string","format":"date","title":"Period Start","description":"Start of the reporting period"},"period_end":{"type":"string","format":"date","title":"Period End","description":"End of the reporting period"},"by_type":{"items":{"$ref":"#/components/schemas/EventBreakdownItem"},"type":"array","title":"By Type","description":"Event counts grouped by event type"},"by_source":{"items":{"$ref":"#/components/schemas/EventBreakdownItem"},"type":"array","title":"By Source","description":"Event counts grouped by source"},"total_events":{"type":"integer","title":"Total Events","description":"Total number of events in the period"}},"type":"object","required":["workspace_id","period_start","period_end","by_type","by_source","total_events"],"title":"EventBreakdownResponse"},"EventBreakdownItem":{"properties":{"key":{"type":"string","title":"Key","description":"Grouping key (event type or source name)"},"count":{"type":"integer","title":"Count","description":"Number of events for this key"}},"type":"object","required":["key","count"],"title":"EventBreakdownItem","description":"Single row in an event breakdown aggregation."}}}} ``` ## The EventCallSidString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventCallSidString":{"type":"string","maxLength":128}}}} ``` ## The EventChannelString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventChannelString":{"type":"string","maxLength":64}}}} ``` ## The EventDescriptionString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventDescriptionString":{"type":"string","maxLength":4096}}}} ``` ## The EventDirectionString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventDirectionString":{"type":"string","maxLength":64}}}} ``` ## The EventDisplayNameString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventDisplayNameString":{"type":"string","maxLength":512}}}} ``` ## The EventOutcomeString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventOutcomeString":{"type":"string","maxLength":256}}}} ``` ## The EventStatusString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventStatusString":{"type":"string","maxLength":128}}}} ``` ## The EventTypeRegistryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventTypeRegistryResponse":{"properties":{"event_types":{"items":{"$ref":"#/components/schemas/EventTypeSummary"},"type":"array","title":"Event Types"},"total_events":{"type":"integer","title":"Total Events"}},"type":"object","required":["event_types","total_events"],"title":"EventTypeRegistryResponse"},"EventTypeSummary":{"properties":{"event_type":{"type":"string","title":"Event Type"},"count":{"type":"integer","title":"Count"},"domains":{"items":{"type":"string"},"type":"array","title":"Domains"},"sources":{"items":{"type":"string"},"type":"array","title":"Sources"}},"type":"object","required":["event_type","count","domains","sources"],"title":"EventTypeSummary"}}}} ``` ## The EventTypeSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EventTypeSummary":{"properties":{"event_type":{"type":"string","title":"Event Type"},"count":{"type":"integer","title":"Count"},"domains":{"items":{"type":"string"},"type":"array","title":"Domains"},"sources":{"items":{"type":"string"},"type":"array","title":"Sources"}},"type":"object","required":["event_type","count","domains","sources"],"title":"EventTypeSummary"}}}} ``` ## The ExecutePanelRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExecutePanelRequest":{"properties":{"filter_values":{"additionalProperties":true,"type":"object","title":"Filter Values","description":"Filter values to apply to panel queries"}},"type":"object","title":"ExecutePanelRequest"}}}} ``` ## The ExitCondition object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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"}}}} ``` ## The ExplorationConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"}}}} ``` ## The ExternalAuthClaim object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalAuthClaim":{"properties":{"namespace":{"type":"string","maxLength":64,"pattern":"^[a-z][a-z0-9_.:-]{0,63}$","title":"Namespace"},"key":{"type":"string","maxLength":64,"pattern":"^[a-z][a-z0-9_.:-]{0,63}$","title":"Key"},"value":{"type":"string","maxLength":256,"minLength":1,"title":"Value"}},"additionalProperties":false,"type":"object","required":["namespace","key","value"],"title":"ExternalAuthClaim","description":"One normalized customer assertion: the exact tuple ``(namespace, key, value)``.\n\n``value`` is preserved byte-for-byte (bounded length only) — Amigo does not\nlowercase, alias, or rewrite it. ``namespace`` and ``key`` are bounded canonical\nidentifiers. Arrays, objects, numbers, booleans, and null are rejected for every\nfield (v1 values are non-empty strings)."}}}} ``` ## The ExternalIdentityBindingItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIdentityBindingItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"external_integration_id":{"type":"string","format":"uuid","title":"External Integration Id"},"subject_type":{"type":"string","const":"user","title":"Subject Type"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","deprecated":true},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"status":{"type":"string","enum":["active","revoked"],"title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","external_integration_id","subject_type","entity_id","status","created_at","updated_at"],"title":"ExternalIdentityBindingItem"}}}} ``` ## The ExternalIdentityBindingListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIdentityBindingListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExternalIdentityBindingItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ExternalIdentityBindingListResponse"},"ExternalIdentityBindingItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"external_integration_id":{"type":"string","format":"uuid","title":"External Integration Id"},"subject_type":{"type":"string","const":"user","title":"Subject Type"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","deprecated":true},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"status":{"type":"string","enum":["active","revoked"],"title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","external_integration_id","subject_type","entity_id","status","created_at","updated_at"],"title":"ExternalIdentityBindingItem"}}}} ``` ## The ExternalIdentityBindingUpsertResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIdentityBindingUpsertResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"external_integration_id":{"type":"string","format":"uuid","title":"External Integration Id"},"subject_type":{"type":"string","const":"user","title":"Subject Type"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","deprecated":true},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"status":{"type":"string","enum":["active","revoked"],"title":"Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"upsert_outcome":{"type":"string","enum":["created","materialized","unchanged"],"title":"Upsert Outcome"}},"type":"object","required":["id","external_integration_id","subject_type","entity_id","status","created_at","updated_at","upsert_outcome"],"title":"ExternalIdentityBindingUpsertResponse"}}}} ``` ## The ExternalIntegrationCredentialRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationCredentialRequest":{"properties":{"service_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1,"title":"Service Ids"},"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["service_ids"],"title":"ExternalIntegrationCredentialRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ExternalIntegrationCredentialResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationCredentialResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"integration_id":{"type":"string","format":"uuid","title":"Integration Id"},"client_id":{"type":"string","title":"Client Id"},"service_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Service Ids"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"is_active":{"type":"boolean","title":"Is Active"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"rotated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Rotated At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"}},"type":"object","required":["id","workspace_id","integration_id","client_id","service_ids","is_active"],"title":"ExternalIntegrationCredentialResponse"}}}} ``` ## The ExternalIntegrationCredentialSecretResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationCredentialSecretResponse":{"properties":{"credential":{"$ref":"#/components/schemas/ExternalIntegrationCredentialResponse"},"client_secret":{"type":"string","title":"Client Secret"}},"type":"object","required":["credential","client_secret"],"title":"ExternalIntegrationCredentialSecretResponse"},"ExternalIntegrationCredentialResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"integration_id":{"type":"string","format":"uuid","title":"Integration Id"},"client_id":{"type":"string","title":"Client Id"},"service_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Service Ids"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"is_active":{"type":"boolean","title":"Is Active"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"rotated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Rotated At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"}},"type":"object","required":["id","workspace_id","integration_id","client_id","service_ids","is_active"],"title":"ExternalIntegrationCredentialResponse"}}}} ``` ## The ExternalIntegrationListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExternalIntegrationResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ExternalIntegrationListResponse"},"ExternalIntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Name"},"display_name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"title":"Description"},"is_active":{"type":"boolean","title":"Is Active"},"created_by_entity_id":{"type":"string","format":"uuid","title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Credential Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","display_name","is_active","created_by_entity_id"],"title":"ExternalIntegrationResponse"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ExternalIntegrationRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationRequest":{"properties":{"name":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Name"},"display_name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"title":"Description"}},"type":"object","required":["name","display_name"],"title":"ExternalIntegrationRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ExternalIntegrationResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Name"},"display_name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"title":"Description"},"is_active":{"type":"boolean","title":"Is Active"},"created_by_entity_id":{"type":"string","format":"uuid","title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By Credential Id"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","display_name","is_active","created_by_entity_id"],"title":"ExternalIntegrationResponse"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ExternalIntegrationUpdateRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalIntegrationUpdateRequest":{"properties":{"name":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Name"},"display_name":{"$ref":"#/components/schemas/NameString","title":"Display Name"},"description":{"anyOf":[{"type":"string","maxLength":4096},{"type":"null"}],"title":"Description"}},"type":"object","title":"ExternalIntegrationUpdateRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ExternalRoleAssignmentItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalRoleAssignmentItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source":{"type":"string","title":"Source"},"external_subject_key":{"type":"string","title":"External Subject Key"},"external_subject_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Subject Id"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"roles":{"items":{"type":"string"},"type":"array","title":"Roles"},"roles_verified":{"type":"boolean","title":"Roles Verified"},"status":{"type":"string","enum":["active","suspended","revoked"],"title":"Status"},"provisioned_via":{"type":"string","enum":["roster_sync","jit"],"title":"Provisioned Via"},"last_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Verified At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","source","external_subject_key","entity_id","roles","roles_verified","status","provisioned_via","created_at","updated_at"],"title":"ExternalRoleAssignmentItem"}}}} ``` ## The ExternalRoleItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalRoleItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"external_name":{"type":"string","title":"External Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"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","name","external_name","created_at","updated_at"],"title":"ExternalRoleItem","description":"Wire shape for read + create responses."}}}} ``` ## The ExternalSystemString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalSystemString":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z0-9_\\-]+$"}}}} ``` ## The ExternalValueString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalValueString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ExternalWriteProposal object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalWriteProposal":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"connector_type":{"type":"string","title":"Connector Type"},"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"fhir_resource_type":{"type":"string","title":"Fhir Resource Type"},"fhir_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Id"},"proposed_payload":{"additionalProperties":true,"type":"object","title":"Proposed Payload"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"origin_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Run Id"},"origin_run_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Run Kind"},"origin_event_id":{"type":"string","format":"uuid","title":"Origin Event Id"},"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"status":{"type":"string","enum":["proposed","approved","rejected","pushing","pushed","failed","superseded"],"title":"Status"},"decided_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Decided By"},"decided_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Decided At"},"reject_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reject Reason"},"push_attempt_count":{"type":"integer","title":"Push Attempt Count","default":0},"vendor_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Resource Id"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","connector_type","data_source_id","fhir_resource_type","origin_event_id","status"],"title":"ExternalWriteProposal","description":"A human-review proposal for an external (EHR) write-back — the Review Queue.\n\nStaged by connector-runner when a `review_required` sink would otherwise\nauto-push (world.external_write_proposals); a reviewer approves/rejects, and the\negress drain delivers approved ones. ``proposed_payload`` is the full FHIR write\nbody and MAY contain PHI — this surface is workspace-scoped (FORCE-RLS) and\npermission-gated (ReviewQueue); never log it. ``connector_type``/``fhir_*``/\n``status``/``idempotency_key`` are opaque strings; the ids are uuid."}}}} ``` ## The ExternalWriteProposalListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ExternalWriteProposalListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExternalWriteProposal"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ExternalWriteProposalListResponse"},"ExternalWriteProposal":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"connector_type":{"type":"string","title":"Connector Type"},"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"fhir_resource_type":{"type":"string","title":"Fhir Resource Type"},"fhir_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Id"},"proposed_payload":{"additionalProperties":true,"type":"object","title":"Proposed Payload"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"origin_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Run Id"},"origin_run_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Run Kind"},"origin_event_id":{"type":"string","format":"uuid","title":"Origin Event Id"},"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"status":{"type":"string","enum":["proposed","approved","rejected","pushing","pushed","failed","superseded"],"title":"Status"},"decided_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Decided By"},"decided_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Decided At"},"reject_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reject Reason"},"push_attempt_count":{"type":"integer","title":"Push Attempt Count","default":0},"vendor_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor Resource Id"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","connector_type","data_source_id","fhir_resource_type","origin_event_id","status"],"title":"ExternalWriteProposal","description":"A human-review proposal for an external (EHR) write-back — the Review Queue.\n\nStaged by connector-runner when a `review_required` sink would otherwise\nauto-push (world.external_write_proposals); a reviewer approves/rejects, and the\negress drain delivers approved ones. ``proposed_payload`` is the full FHIR write\nbody and MAY contain PHI — this surface is workspace-scoped (FORCE-RLS) and\npermission-gated (ReviewQueue); never log it. ``connector_type``/``fhir_*``/\n``status``/``idempotency_key`` are opaque strings; the ids are uuid."}}}} ``` ## The FailureClass object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."}}}} ``` ## The FhirAppointmentListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirAppointmentListResponse":{"properties":{"appointments":{"items":{"$ref":"#/components/schemas/FhirAppointmentView"},"type":"array","title":"Appointments"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["appointments","total"],"title":"FhirAppointmentListResponse"},"FhirAppointmentView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End"},"patient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Patient Name"},"practitioner_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Practitioner Name"},"location_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Name"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"cancel_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Reason"},"appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Type"},"duration_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Minutes"},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirAppointmentView"}}}} ``` ## The FhirAppointmentView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirAppointmentView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End"},"patient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Patient Name"},"practitioner_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Practitioner Name"},"location_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Name"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"cancel_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Reason"},"appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Type"},"duration_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Minutes"},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirAppointmentView"}}}} ``` ## The FhirBuildBundleRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirBuildBundleRequest":{"properties":{"users":{"items":{"$ref":"#/components/schemas/FhirPatientUser"},"type":"array","maxItems":1000,"minItems":1,"title":"Users"}},"type":"object","required":["users"],"title":"FhirBuildBundleRequest","description":"Request body for ``POST /fhir/build-bundle``.\n\nBundle building is a pure transformation, so this carries only the user\nrows — provenance/dedup options (``source``, ``dedup``, …) belong to the\ndownstream ``POST /fhir/import`` call, not to bundle construction."},"FhirPatientUser":{"properties":{"external_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"External Id","description":"Stable source-system id (e.g. FAM user UUID). Becomes the Patient MR identifier and, when it satisfies the FHIR id grammar, the resource id. Capped at 64 to match the FHIR Resource.id length."},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Validated email; becomes an email telecom on the Patient."},"name":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Name","description":"Full name; used when first_name/last_name are not supplied."},"first_name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Last Name"}},"type":"object","title":"FhirPatientUser","description":"One caller-friendly user row for ``POST /fhir/build-bundle``.\n\nA flat identity shape (email / name / external id) that the server expands\ninto a FHIR Patient resource, so integrators onboarding users don't have to\nhand-author FHIR. ``external_id`` becomes the Patient MR identifier (and,\nwhen spec-valid, the FHIR resource id) — the anchor a later import uses for\nthe entity's canonical id / source-system binding (e.g. the FAM user UUID).\nSupply either ``name`` (full) or ``first_name`` / ``last_name``."}}}} ``` ## The FhirBundleResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirBundleResponse":{"properties":{"bundle":{"additionalProperties":true,"type":"object","title":"Bundle"},"patient_count":{"type":"integer","title":"Patient Count"}},"type":"object","required":["bundle","patient_count"],"title":"FhirBundleResponse","description":"Response for ``POST /fhir/build-bundle`` — the built FHIR Bundle.\n\n``bundle`` is the exact value ``POST /fhir/import`` expects nested under its\n``bundle`` field; ``patient_count`` echoes how many Patients were built."}}}} ``` ## The FhirImportRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirImportRequest":{"properties":{"bundle":{"additionalProperties":true,"type":"object","title":"Bundle"},"source":{"type":"string","maxLength":128,"title":"Source","default":"fhir_import"},"source_system":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Source System"},"data_source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Source Id"},"dedup":{"type":"boolean","title":"Dedup","description":"When true, identical re-uploads of the same FHIR resource are skipped via content-hash dedup. Set to false to force emission regardless of content changes.","default":true},"unsupported_resource_policy":{"$ref":"#/components/schemas/FhirUnsupportedResourcePolicy","description":"Controls resources whose resourceType is missing or not projected by platform FHIR APIs. 'error' skips the resource and adds a per-resource error; 'skip' skips it without adding an error. Unsupported resources are never emitted as silent raw world events.","default":"error"}},"type":"object","required":["bundle"],"title":"FhirImportRequest"},"FhirUnsupportedResourcePolicy":{"type":"string","enum":["error","skip"]}}}} ``` ## The FhirImportResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirImportResponse":{"properties":{"events_created":{"type":"integer","title":"Events Created"},"events_skipped":{"type":"integer","title":"Events Skipped","default":0},"events_updated":{"type":"integer","title":"Events Updated","default":0},"entities_created":{"type":"integer","title":"Entities Created"},"entities_updated":{"type":"integer","title":"Entities Updated"},"error_count":{"type":"integer","title":"Error Count","default":0},"errors":{"items":{"type":"string"},"type":"array","maxItems":1000,"title":"Errors"},"errors_truncated":{"type":"boolean","title":"Errors Truncated","default":false},"unsupported_resource_count":{"type":"integer","title":"Unsupported Resource Count","default":0},"unsupported_resources":{"items":{"$ref":"#/components/schemas/FhirUnsupportedResourceItem"},"type":"array","maxItems":1000,"title":"Unsupported Resources"},"unsupported_resources_truncated":{"type":"boolean","title":"Unsupported Resources Truncated","default":false},"upsert_semantics":{"type":"string","const":"same_resource_id_upsert","title":"Upsert Semantics","description":"FHIR import uses workspace + resourceType + id as the natural key. Identical re-uploads can be deduped; changed resources supersede prior current events.","default":"same_resource_id_upsert"},"absence_semantics":{"type":"string","const":"absent_resources_persist","title":"Absence Semantics","description":"Resources omitted from a later bundle are not deleted or archived by import.","default":"absent_resources_persist"}},"type":"object","required":["events_created","entities_created","entities_updated"],"title":"FhirImportResponse"},"FhirUnsupportedResourceItem":{"properties":{"resource_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Resource Id"},"location":{"type":"string","maxLength":128,"title":"Location"},"reason":{"type":"string","maxLength":512,"title":"Reason"}},"type":"object","required":["location","reason"],"title":"FhirUnsupportedResourceItem"}}}} ``` ## The FhirLocationListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirLocationListResponse":{"properties":{"locations":{"items":{"$ref":"#/components/schemas/FhirLocationView"},"type":"array","title":"Locations"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["locations","total"],"title":"FhirLocationListResponse"},"FhirLocationView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Address"},"address_line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone"},"facility_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Facility Id"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"hours":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hours"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirLocationView"}}}} ``` ## The FhirLocationView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirLocationView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Address"},"address_line":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone"},"facility_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Facility Id"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"hours":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hours"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirLocationView"}}}} ``` ## The FhirOrganizationListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirOrganizationListResponse":{"properties":{"organizations":{"items":{"$ref":"#/components/schemas/FhirOrganizationView"},"type":"array","title":"Organizations"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["organizations","total"],"title":"FhirOrganizationListResponse"},"FhirOrganizationView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Address"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirOrganizationView"}}}} ``` ## The FhirOrganizationView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirOrganizationView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Address"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirOrganizationView"}}}} ``` ## The FhirPatientListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirPatientListResponse":{"properties":{"patients":{"items":{"$ref":"#/components/schemas/FhirPatientView"},"type":"array","title":"Patients"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["patients","total"],"title":"FhirPatientListResponse"},"FhirPatientView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn"},"address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Address"},"address_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address State"},"address_postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Postal Code"},"address_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address City"},"active_conditions":{"items":{"type":"string"},"type":"array","title":"Active Conditions"},"active_medications":{"items":{"type":"string"},"type":"array","title":"Active Medications"},"allergies":{"items":{"type":"string"},"type":"array","title":"Allergies"},"insurance":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Insurance"},"primary_payer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Payer Name"},"practice_payer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Practice Payer Id"},"member_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Id"},"policyholder_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policyholder Name"},"policyholder_relationship":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policyholder Relationship"},"policyholder_dob":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policyholder Dob"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"confidence":{"type":"number","title":"Confidence","default":1},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["entity_id"],"title":"FhirPatientView"}}}} ``` ## The FhirPatientUser object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirPatientUser":{"properties":{"external_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"External Id","description":"Stable source-system id (e.g. FAM user UUID). Becomes the Patient MR identifier and, when it satisfies the FHIR id grammar, the resource id. Capped at 64 to match the FHIR Resource.id length."},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email","description":"Validated email; becomes an email telecom on the Patient."},"name":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Name","description":"Full name; used when first_name/last_name are not supplied."},"first_name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Last Name"}},"type":"object","title":"FhirPatientUser","description":"One caller-friendly user row for ``POST /fhir/build-bundle``.\n\nA flat identity shape (email / name / external id) that the server expands\ninto a FHIR Patient resource, so integrators onboarding users don't have to\nhand-author FHIR. ``external_id`` becomes the Patient MR identifier (and,\nwhen spec-valid, the FHIR resource id) — the anchor a later import uses for\nthe entity's canonical id / source-system binding (e.g. the FAM user UUID).\nSupply either ``name`` (full) or ``first_name`` / ``last_name``."}}}} ``` ## The FhirPatientView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirPatientView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn"},"address":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Address"},"address_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address State"},"address_postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Postal Code"},"address_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address City"},"active_conditions":{"items":{"type":"string"},"type":"array","title":"Active Conditions"},"active_medications":{"items":{"type":"string"},"type":"array","title":"Active Medications"},"allergies":{"items":{"type":"string"},"type":"array","title":"Allergies"},"insurance":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Insurance"},"primary_payer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Payer Name"},"practice_payer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Practice Payer Id"},"member_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Id"},"policyholder_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policyholder Name"},"policyholder_relationship":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policyholder Relationship"},"policyholder_dob":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policyholder Dob"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"confidence":{"type":"number","title":"Confidence","default":1},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["entity_id"],"title":"FhirPatientView"}}}} ``` ## The FhirPractitionerListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirPractitionerListResponse":{"properties":{"practitioners":{"items":{"$ref":"#/components/schemas/FhirPractitionerView"},"type":"array","title":"Practitioners"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["practitioners","total"],"title":"FhirPractitionerListResponse"},"FhirPractitionerView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"member_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Id"},"scheduling_eligible":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Scheduling Eligible"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirPractitionerView"}}}} ``` ## The FhirPractitionerView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirPractitionerView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"npi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Npi"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"member_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Id"},"scheduling_eligible":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Scheduling Eligible"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirPractitionerView"}}}} ``` ## The FhirResourceHistoryEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirResourceHistoryEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"type":"string","title":"Event Type"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"data_source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Source Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"is_current":{"type":"boolean","title":"Is Current"},"effective_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"fields_affected":{"items":{"type":"string"},"type":"array","title":"Fields Affected"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["event_id","event_type","is_current"],"title":"FhirResourceHistoryEntry"}}}} ``` ## The FhirResourceHistoryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirResourceHistoryResponse":{"properties":{"resource_type":{"type":"string","title":"Resource Type"},"resource_id":{"type":"string","title":"Resource Id"},"entries":{"items":{"$ref":"#/components/schemas/FhirResourceHistoryEntry"},"type":"array","title":"Entries"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["resource_type","resource_id","entries","total"],"title":"FhirResourceHistoryResponse"},"FhirResourceHistoryEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"type":"string","title":"Event Type"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"data_source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Source Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"is_current":{"type":"boolean","title":"Is Current"},"effective_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"fields_affected":{"items":{"type":"string"},"type":"array","title":"Fields Affected"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["event_id","event_type","is_current"],"title":"FhirResourceHistoryEntry"}}}} ``` ## The FhirResourceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirResourceResponse":{"properties":{"resource_type":{"type":"string","title":"Resource Type"},"resource_id":{"type":"string","title":"Resource Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"type":"object","required":["resource_type","resource_id","data"],"title":"FhirResourceResponse"}}}} ``` ## The FhirSearchResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirSearchResponse":{"properties":{"resource_type":{"type":"string","title":"Resource Type"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"entries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Entries"},"next_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Url"}},"type":"object","required":["resource_type","total","entries"],"title":"FhirSearchResponse"}}}} ``` ## The FhirSlotListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirSlotListResponse":{"properties":{"slots":{"items":{"$ref":"#/components/schemas/FhirSlotView"},"type":"array","title":"Slots"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["slots","total"],"title":"FhirSlotListResponse"},"FhirSlotView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End"},"schedule_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Ref"},"provider_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Name"},"provider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Id"},"facility_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Facility Id"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"visit_type_ids":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visit Type Ids"},"visit_type_names":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visit Type Names"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirSlotView"}}}} ``` ## The FhirSlotView object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirSlotView":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End"},"schedule_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Ref"},"provider_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Name"},"provider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Id"},"facility_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Facility Id"},"specialty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specialty"},"visit_type_ids":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visit Type Ids"},"visit_type_names":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visit Type Names"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"FhirSlotView"}}}} ``` ## The FhirStatusResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirStatusResponse":{"properties":{"configured":{"type":"boolean","title":"Configured"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"event_count":{"type":"integer","title":"Event Count"},"entity_count":{"type":"integer","title":"Entity Count"},"entity_type_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Entity Type Counts"},"resource_type_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Resource Type Counts"},"last_poll_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Poll At"},"last_change_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Change At"},"sync_healthy":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sync Healthy"}},"type":"object","required":["configured","event_count","entity_count"],"title":"FhirStatusResponse"}}}} ``` ## The FhirUnsupportedResourceItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirUnsupportedResourceItem":{"properties":{"resource_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Resource Id"},"location":{"type":"string","maxLength":128,"title":"Location"},"reason":{"type":"string","maxLength":512,"title":"Reason"}},"type":"object","required":["location","reason"],"title":"FhirUnsupportedResourceItem"}}}} ``` ## The FhirUnsupportedResourcePolicy object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirUnsupportedResourcePolicy":{"type":"string","enum":["error","skip"]}}}} ``` ## The FhirWriteRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FhirWriteRequest":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"data_source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Source Id"}},"type":"object","required":["data"],"title":"FhirWriteRequest"}}}} ``` ## The FieldSaveRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FieldSaveRequest":{"properties":{"value":{"title":"Value","description":"The field value to save"}},"type":"object","required":["value"],"title":"FieldSaveRequest"}}}} ``` ## The FieldType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The FileEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FileEntry":{"properties":{"file_id":{"type":"string","format":"uuid","title":"File Id"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"},"version":{"type":"integer","title":"Version"},"source_path":{"type":"string","title":"Source Path"},"file_type":{"type":"string","title":"File Type"},"content_type":{"type":"string","title":"Content Type"},"sha256":{"type":"string","title":"Sha256"},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At"},"contract_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contract Id"},"contract_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract Version"},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"}},"type":"object","required":["file_id","version","source_path","file_type","content_type","sha256","size_bytes","ingested_at"],"title":"FileEntry"}}}} ``` ## The FireTriggerRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FireTriggerRequest":{"properties":{"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input","description":"Optional overrides merged into the trigger's input_template at fire time."}},"type":"object","title":"FireTriggerRequest"}}}} ``` ## The FleetStatusResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FleetStatusResponse":{"properties":{"fleet":{"type":"string","title":"Fleet"},"namespace":{"type":"string","title":"Namespace"},"ready":{"type":"integer","title":"Ready"},"allocated":{"type":"integer","title":"Allocated"},"total":{"type":"integer","title":"Total"},"max_replicas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Replicas"},"headroom":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Headroom"},"by_state":{"additionalProperties":{"type":"integer"},"type":"object","title":"By State"}},"type":"object","required":["fleet","namespace","ready","allocated","total","max_replicas","headroom","by_state"],"title":"FleetStatusResponse","description":"Live Agones fleet capacity (workspace-global).\n\n``headroom`` = remaining isolated-unit slots (``max_replicas - allocated``);\n``max_replicas``/``headroom`` are null when the ceiling isn't configured upstream.\nThe counts span the whole fleet (one fleet serves every workspace) — this is NOT\nper-workspace. ``fleet``/``namespace`` echo which fleet was read."}}}} ``` ## The ForecastDrawPoint object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForecastDrawPoint":{"properties":{"draw_id":{"type":"integer","title":"Draw Id"},"t":{"type":"number","title":"T"},"value":{"type":"number","title":"Value"}},"type":"object","required":["draw_id","t","value"],"title":"ForecastDrawPoint"}}}} ``` ## The ForecastDrawsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForecastDrawsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/ForecastDrawPoint"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"ForecastDrawsResponse"},"ForecastDrawPoint":{"properties":{"draw_id":{"type":"integer","title":"Draw Id"},"t":{"type":"number","title":"T"},"value":{"type":"number","title":"Value"}},"type":"object","required":["draw_id","t","value"],"title":"ForecastDrawPoint"}}}} ``` ## The ForecastFanPointRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForecastFanPointRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"run_id":{"type":"string","title":"Run Id"},"scenario":{"type":"string","enum":["baseline","with_policy","observational"],"title":"Scenario"},"t":{"type":"number","title":"T"},"lower_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lower 95"},"upper_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Upper 95"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"observed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Observed"},"ym":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ym"},"is_historical":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Historical"}},"type":"object","required":["workspace_id","run_id","scenario","t"],"title":"ForecastFanPointRow"}}}} ``` ## The ForecastFanResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForecastFanResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/ForecastFanPointRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"ForecastFanResponse"},"ForecastFanPointRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"run_id":{"type":"string","title":"Run Id"},"scenario":{"type":"string","enum":["baseline","with_policy","observational"],"title":"Scenario"},"t":{"type":"number","title":"T"},"lower_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lower 95"},"upper_95":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Upper 95"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"observed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Observed"},"ym":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ym"},"is_historical":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Historical"}},"type":"object","required":["workspace_id","run_id","scenario","t"],"title":"ForecastFanPointRow"}}}} ``` ## The ForkAlternative object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForkAlternative":{"properties":{"caller_text":{"type":"string","maxLength":2000,"title":"Caller Text"},"emotion":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Valence"}},"type":"object","required":["caller_text"],"title":"ForkAlternative"}}}} ``` ## The ForkRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForkRequest":{"properties":{"alternatives":{"items":{"$ref":"#/components/schemas/ForkAlternative"},"type":"array","maxItems":20,"minItems":1,"title":"Alternatives"}},"type":"object","required":["alternatives"],"title":"ForkRequest"},"ForkAlternative":{"properties":{"caller_text":{"type":"string","maxLength":2000,"title":"Caller Text"},"emotion":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Valence"}},"type":"object","required":["caller_text"],"title":"ForkAlternative"}}}} ``` ## The FormTemplate-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FormTemplate-Input":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"category":{"type":"string","enum":["intake","update","consent","screening","survey","custom"],"title":"Category","default":"custom"},"patient_type":{"type":"string","enum":["new","returning","any"],"title":"Patient Type","default":"any"},"fields":{"items":{"$ref":"#/components/schemas/FormTemplateField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"sections":{"items":{"$ref":"#/components/schemas/FormTemplateSection"},"type":"array","maxItems":20,"minItems":1,"title":"Sections"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"active":{"type":"boolean","title":"Active","default":true},"version":{"type":"integer","minimum":1,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"FormTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"},"prefill_path":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Prefill Path","description":"Dot-notation path into entity state for prefill (e.g. demographics.date_of_birth)"},"layout_group":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Layout Group","description":"Row grouping hint — fields with same layout_group render side-by-side"}},"type":"object","required":["key","label"],"title":"FormTemplateField","description":"Extended field with prefill_path mapping to entity state.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"FormTemplateSection":{"properties":{"id":{"type":"string","maxLength":64,"minLength":1,"title":"Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["id","title","field_keys"],"title":"FormTemplateSection","description":"A section in a form template (maps to one wizard step)."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The FormTemplate-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FormTemplate-Output":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"category":{"type":"string","enum":["intake","update","consent","screening","survey","custom"],"title":"Category","default":"custom"},"patient_type":{"type":"string","enum":["new","returning","any"],"title":"Patient Type","default":"any"},"fields":{"items":{"$ref":"#/components/schemas/FormTemplateField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"sections":{"items":{"$ref":"#/components/schemas/FormTemplateSection"},"type":"array","maxItems":20,"minItems":1,"title":"Sections"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"active":{"type":"boolean","title":"Active","default":true},"version":{"type":"integer","minimum":1,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"FormTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"},"prefill_path":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Prefill Path","description":"Dot-notation path into entity state for prefill (e.g. demographics.date_of_birth)"},"layout_group":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Layout Group","description":"Row grouping hint — fields with same layout_group render side-by-side"}},"type":"object","required":["key","label"],"title":"FormTemplateField","description":"Extended field with prefill_path mapping to entity state.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"FormTemplateSection":{"properties":{"id":{"type":"string","maxLength":64,"minLength":1,"title":"Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["id","title","field_keys"],"title":"FormTemplateSection","description":"A section in a form template (maps to one wizard step)."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The FormTemplateField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FormTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"},"prefill_path":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Prefill Path","description":"Dot-notation path into entity state for prefill (e.g. demographics.date_of_birth)"},"layout_group":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Layout Group","description":"Row grouping hint — fields with same layout_group render side-by-side"}},"type":"object","required":["key","label"],"title":"FormTemplateField","description":"Extended field with prefill_path mapping to entity state.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"NameString":{"type":"string","maxLength":256,"minLength":1},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The FormTemplateListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FormTemplateListResponse":{"properties":{"templates":{"items":{"$ref":"#/components/schemas/FormTemplate-Output"},"type":"array","title":"Templates"}},"type":"object","required":["templates"],"title":"FormTemplateListResponse","description":"List of form templates for a workspace."},"FormTemplate-Output":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"category":{"type":"string","enum":["intake","update","consent","screening","survey","custom"],"title":"Category","default":"custom"},"patient_type":{"type":"string","enum":["new","returning","any"],"title":"Patient Type","default":"any"},"fields":{"items":{"$ref":"#/components/schemas/FormTemplateField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"sections":{"items":{"$ref":"#/components/schemas/FormTemplateSection"},"type":"array","maxItems":20,"minItems":1,"title":"Sections"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"active":{"type":"boolean","title":"Active","default":true},"version":{"type":"integer","minimum":1,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"FormTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"},"prefill_path":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Prefill Path","description":"Dot-notation path into entity state for prefill (e.g. demographics.date_of_birth)"},"layout_group":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Layout Group","description":"Row grouping hint — fields with same layout_group render side-by-side"}},"type":"object","required":["key","label"],"title":"FormTemplateField","description":"Extended field with prefill_path mapping to entity state.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"FormTemplateSection":{"properties":{"id":{"type":"string","maxLength":64,"minLength":1,"title":"Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["id","title","field_keys"],"title":"FormTemplateSection","description":"A section in a form template (maps to one wizard step)."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The FormTemplateSection object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FormTemplateSection":{"properties":{"id":{"type":"string","maxLength":64,"minLength":1,"title":"Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["id","title","field_keys"],"title":"FormTemplateSection","description":"A section in a form template (maps to one wizard step)."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The FormTemplateUpdateRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FormTemplateUpdateRequest":{"properties":{"templates":{"items":{"$ref":"#/components/schemas/FormTemplate-Input"},"type":"array","maxItems":50,"title":"Templates"}},"type":"object","required":["templates"],"title":"FormTemplateUpdateRequest","description":"Replace all form templates."},"FormTemplate-Input":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"category":{"type":"string","enum":["intake","update","consent","screening","survey","custom"],"title":"Category","default":"custom"},"patient_type":{"type":"string","enum":["new","returning","any"],"title":"Patient Type","default":"any"},"fields":{"items":{"$ref":"#/components/schemas/FormTemplateField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"sections":{"items":{"$ref":"#/components/schemas/FormTemplateSection"},"type":"array","maxItems":20,"minItems":1,"title":"Sections"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"active":{"type":"boolean","title":"Active","default":true},"version":{"type":"integer","minimum":1,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"FormTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"},"prefill_path":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Prefill Path","description":"Dot-notation path into entity state for prefill (e.g. demographics.date_of_birth)"},"layout_group":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Layout Group","description":"Row grouping hint — fields with same layout_group render side-by-side"}},"type":"object","required":["key","label"],"title":"FormTemplateField","description":"Extended field with prefill_path mapping to entity state.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"FormTemplateSection":{"properties":{"id":{"type":"string","maxLength":64,"minLength":1,"title":"Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["id","title","field_keys"],"title":"FormTemplateSection","description":"A section in a form template (maps to one wizard step)."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."}}}} ``` ## The ForwardingDetails object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForwardingDetails":{"properties":{"forward_to":{"type":"string","title":"Forward To"},"warm_transfer":{"type":"boolean","title":"Warm Transfer"},"forwarded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Forwarded At"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ForwardingDetails"}}}} ``` ## The FunctionExample object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"FunctionExample":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input"},"output":{"title":"Output"},"description":{"type":"string","title":"Description","default":""}},"additionalProperties":false,"type":"object","required":["input","output"],"title":"FunctionExample","description":"One example call, surfaced to the LLM and the DC test panel.\n\nExamples are first-class metadata, not buried in a UC ``COMMENT``\nclause the way Databricks' native authoring requires. The DC\ntool-picker shows them; the LLM tool spec includes them inline."}}}} ``` ## The GapRequiredField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GapRequiredField":{"properties":{"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"min_items":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"title":"Min Items","description":"For list fields, minimum items required"}},"type":"object","required":["path","label"],"title":"GapRequiredField","description":"A field that must be present in entity state."},"NameString":{"type":"string","maxLength":256,"minLength":1},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The GapRequirement-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GapRequirement-Input":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"entity_type":{"type":"string","const":"person","title":"Entity Type","default":"person"},"trigger":{"type":"string","enum":["upcoming_appointment","recent_interaction"],"title":"Trigger","default":"upcoming_appointment"},"required_fields":{"items":{"$ref":"#/components/schemas/GapRequiredField"},"type":"array","maxItems":50,"minItems":1,"title":"Required Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"priority":{"type":"string","enum":["low","normal","high"],"title":"Priority","default":"normal"},"surface_title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Title for generated surfaces. Defaults to requirement name."},"surface_description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","required":["name","required_fields"],"title":"GapRequirement","description":"A named gap detection rule."},"NameString":{"type":"string","maxLength":256,"minLength":1},"GapRequiredField":{"properties":{"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"min_items":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"title":"Min Items","description":"For list fields, minimum items required"}},"type":"object","required":["path","label"],"title":"GapRequiredField","description":"A field that must be present in entity state."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The GapRequirement-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GapRequirement-Output":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"entity_type":{"type":"string","const":"person","title":"Entity Type","default":"person"},"trigger":{"type":"string","enum":["upcoming_appointment","recent_interaction"],"title":"Trigger","default":"upcoming_appointment"},"required_fields":{"items":{"$ref":"#/components/schemas/GapRequiredField"},"type":"array","maxItems":50,"minItems":1,"title":"Required Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"priority":{"type":"string","enum":["low","normal","high"],"title":"Priority","default":"normal"},"surface_title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Title for generated surfaces. Defaults to requirement name."},"surface_description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","required":["name","required_fields"],"title":"GapRequirement","description":"A named gap detection rule."},"NameString":{"type":"string","maxLength":256,"minLength":1},"GapRequiredField":{"properties":{"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"min_items":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"title":"Min Items","description":"For list fields, minimum items required"}},"type":"object","required":["path","label"],"title":"GapRequiredField","description":"A field that must be present in entity state."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The GapScannerPreviewRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GapScannerPreviewRequest":{"properties":{"limit":{"type":"integer","maximum":200,"minimum":1,"title":"Limit","default":50}},"type":"object","title":"GapScannerPreviewRequest"}}}} ``` ## The GapScannerSettingsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GapScannerSettingsRequest":{"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"scan_interval_seconds":{"anyOf":[{"type":"integer","maximum":86400,"minimum":60},{"type":"null"}],"title":"Scan Interval Seconds"},"appointment_lookahead_hours":{"anyOf":[{"type":"integer","maximum":720,"minimum":1},{"type":"null"}],"title":"Appointment Lookahead Hours"},"cooldown_hours":{"anyOf":[{"type":"integer","maximum":8760,"minimum":1},{"type":"null"}],"title":"Cooldown Hours"},"max_surfaces_per_tick":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"title":"Max Surfaces Per Tick"},"max_pending_surfaces":{"anyOf":[{"type":"integer","maximum":50,"minimum":0},{"type":"null"}],"title":"Max Pending Surfaces","description":"Max non-terminal surfaces per entity (0 = disabled)"},"min_completion_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Min Completion Rate","description":"Min historical completion rate to create new surfaces (0.0 = disabled)"},"channel_optimization":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Channel Optimization","description":"Use entity preferred channel over static requirement channel"},"requirements":{"anyOf":[{"items":{"$ref":"#/components/schemas/GapRequirement-Input"},"type":"array","maxItems":100},{"type":"null"}],"title":"Requirements"}},"type":"object","title":"GapScannerSettingsRequest"},"GapRequirement-Input":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"entity_type":{"type":"string","const":"person","title":"Entity Type","default":"person"},"trigger":{"type":"string","enum":["upcoming_appointment","recent_interaction"],"title":"Trigger","default":"upcoming_appointment"},"required_fields":{"items":{"$ref":"#/components/schemas/GapRequiredField"},"type":"array","maxItems":50,"minItems":1,"title":"Required Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"priority":{"type":"string","enum":["low","normal","high"],"title":"Priority","default":"normal"},"surface_title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Title for generated surfaces. Defaults to requirement name."},"surface_description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","required":["name","required_fields"],"title":"GapRequirement","description":"A named gap detection rule."},"NameString":{"type":"string","maxLength":256,"minLength":1},"GapRequiredField":{"properties":{"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"min_items":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"title":"Min Items","description":"For list fields, minimum items required"}},"type":"object","required":["path","label"],"title":"GapRequiredField","description":"A field that must be present in entity state."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The GapScannerSettingsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GapScannerSettingsResponse":{"properties":{"enabled":{"type":"boolean","title":"Enabled"},"scan_interval_seconds":{"type":"integer","title":"Scan Interval Seconds"},"appointment_lookahead_hours":{"type":"integer","title":"Appointment Lookahead Hours"},"cooldown_hours":{"type":"integer","title":"Cooldown Hours"},"max_surfaces_per_tick":{"type":"integer","title":"Max Surfaces Per Tick"},"max_pending_surfaces":{"type":"integer","title":"Max Pending Surfaces"},"min_completion_rate":{"type":"number","title":"Min Completion Rate"},"channel_optimization":{"type":"boolean","title":"Channel Optimization"},"requirements":{"items":{"$ref":"#/components/schemas/GapRequirement-Output"},"type":"array","title":"Requirements"}},"type":"object","required":["enabled","scan_interval_seconds","appointment_lookahead_hours","cooldown_hours","max_surfaces_per_tick","max_pending_surfaces","min_completion_rate","channel_optimization","requirements"],"title":"GapScannerSettingsResponse"},"GapRequirement-Output":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"entity_type":{"type":"string","const":"person","title":"Entity Type","default":"person"},"trigger":{"type":"string","enum":["upcoming_appointment","recent_interaction"],"title":"Trigger","default":"upcoming_appointment"},"required_fields":{"items":{"$ref":"#/components/schemas/GapRequiredField"},"type":"array","maxItems":50,"minItems":1,"title":"Required Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"priority":{"type":"string","enum":["low","normal","high"],"title":"Priority","default":"normal"},"surface_title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Title for generated surfaces. Defaults to requirement name."},"surface_description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","required":["name","required_fields"],"title":"GapRequirement","description":"A named gap detection rule."},"NameString":{"type":"string","maxLength":256,"minLength":1},"GapRequiredField":{"properties":{"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"min_items":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"title":"Min Items","description":"For list fields, minimum items required"}},"type":"object","required":["path","label"],"title":"GapRequiredField","description":"A field that must be present in entity state."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The GetSimulationBenchmarkResultsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"GetSimulationBenchmarkResultsRequest":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1,"title":"Run Ids"}},"type":"object","required":["run_ids"],"title":"GetSimulationBenchmarkResultsRequest"}}}} ``` ## The Guardrail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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)."}}}} ``` ## The Guardrails object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Guardrails":{"properties":{"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints","default":[]},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines","default":[]}},"type":"object","title":"Guardrails"}}}} ``` ## The HTTPValidationError object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"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"}}}} ``` ## The HarnessContext object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"HarnessContext":{"properties":{"context_version":{"type":"integer","title":"Context Version","default":1},"config_fingerprint":{"type":"string","title":"Config Fingerprint","default":""},"source":{"type":"string","title":"Source","default":""},"identity":{"anyOf":[{"$ref":"#/components/schemas/AgentIdentity"},{"type":"null"}]},"world_scope":{"$ref":"#/components/schemas/WorldScope"},"tools":{"$ref":"#/components/schemas/Tools"},"guardrails":{"$ref":"#/components/schemas/Guardrails"},"write_floor":{"$ref":"#/components/schemas/WriteFloor"},"runtime":{"$ref":"#/components/schemas/Runtime"}},"type":"object","required":["world_scope","tools","guardrails","write_floor","runtime"],"title":"HarnessContext","description":"A framework-neutral, retrievable service bootstrap projection."},"AgentIdentity":{"properties":{"entry_actor_name":{"type":"string","title":"Entry Actor Name","default":""},"name":{"type":"string","title":"Name","default":""},"role":{"type":"string","title":"Role","default":""},"developed_by":{"type":"string","title":"Developed By","default":""},"instructions":{"type":"string","title":"Instructions","default":""},"initial_state":{"type":"string","title":"Initial State","default":""}},"type":"object","title":"AgentIdentity","description":"Who the agent IS — platform-authored only; ``None`` for native runs\n(a customer's own definition carries its own identity). Named\n``AgentIdentity`` (not ``Identity``) to avoid colliding with the existing\n``config.models.Identity`` OpenAPI schema (a same-name collision would\nforce-rename that shipped schema — a breaking spec change)."},"WorldScope":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"scoped_entity_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Scoped Entity Ids","default":[]},"allow_create":{"type":"boolean","title":"Allow Create","default":false}},"type":"object","required":["workspace_id"],"title":"WorldScope","description":"The world slice — ids only (the leaf stays I/O-free). This is the\nread/subject scope, NOT the write bound (see ``write_floor``).\n``allow_create`` records context intent and is not an authorization grant."},"Tools":{"properties":{"descriptors":{"items":{"$ref":"#/components/schemas/ToolDescriptor"},"type":"array","title":"Descriptors","default":[]},"read_tool_names":{"items":{"type":"string"},"type":"array","title":"Read Tool Names","default":[]},"write_tool_names":{"items":{"type":"string"},"type":"array","title":"Write Tool Names","default":[]}},"type":"object","title":"Tools","description":"Discovery hint — the neutral descriptors. NOT the enforcement (the MCP\nedge is; a remote agent discovers live schemas from the server too)."},"ToolDescriptor":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}}},"type":"object","required":["name"],"title":"ToolDescriptor"},"Guardrails":{"properties":{"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints","default":[]},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines","default":[]}},"type":"object","title":"Guardrails"},"WriteFloor":{"properties":{"enforced_at":{"type":"string","title":"Enforced At","default":"mcp-world-tools-edge"},"requires_entity_anchor":{"type":"boolean","title":"Requires Entity Anchor","default":true},"clinical_write_principal":{"type":"string","title":"Clinical Write Principal","default":"provider-only"},"clinical_write_scope":{"type":"string","title":"Clinical Write Scope","default":"any-entity-in-workspace"},"enrichment_write_scope":{"type":"string","title":"Enrichment Write Scope","default":"caller-anchor-only"},"unanchored_or_api_key_writes":{"type":"string","title":"Unanchored Or Api Key Writes","default":"none"},"allow_create":{"type":"boolean","title":"Allow Create","default":false}},"type":"object","title":"WriteFloor","description":"A static summary of MCP write policy, advisory to the renderer.\n\nThe MCP edge resolves the caller's actual principal and enforces the\nresult. These fields do not grant write access; hosted runner credentials\nare currently unanchored and cannot perform provider-only clinical writes."},"Runtime":{"properties":{"engage_model":{"type":"string","title":"Engage Model","default":""},"channel_kind":{"type":"string","title":"Channel Kind","default":""},"language":{"type":"string","title":"Language","default":""},"caller_context":{"type":"string","title":"Caller Context","default":""}},"type":"object","title":"Runtime"}}}} ``` ## The HealFieldRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"HealFieldRequest":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"value":{"type":"string","maxLength":2000,"minLength":1,"title":"Value"},"field_type":{"type":"string","maxLength":32,"title":"Field Type"},"label":{"type":"string","maxLength":256,"title":"Label"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"context":{"additionalProperties":true,"type":"object","title":"Context"}},"type":"object","required":["key","value","field_type","label"],"title":"HealFieldRequest"}}}} ``` ## The HealFieldResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"HealFieldResponse":{"properties":{"corrected_value":{"type":"string","maxLength":4000,"title":"Corrected Value"},"explanation":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Explanation"},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence"}},"type":"object","required":["corrected_value","confidence"],"title":"HealFieldResponse"}}}} ``` ## The HealthSyncResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"HealthSyncResponse":{"properties":{"connector_heartbeats":{"items":{"$ref":"#/components/schemas/ConnectorHeartbeat"},"type":"array","title":"Connector Heartbeats"}},"type":"object","title":"HealthSyncResponse"},"ConnectorHeartbeat":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"name":{"type":"string","title":"Name"},"alive":{"type":"boolean","title":"Alive"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen"}},"type":"object","required":["data_source_id","name","alive"],"title":"ConnectorHeartbeat"}}}} ``` ## The HipaaReportResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"HipaaReportResponse":{"properties":{"generated_at":{"type":"string","title":"Generated At"},"report_period_days":{"type":"integer","title":"Report Period Days"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"audit_summary":{"additionalProperties":true,"type":"object","title":"Audit Summary"},"retention_policy":{"additionalProperties":true,"type":"object","title":"Retention Policy"},"encryption":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Encryption"},"access_controls":{"additionalProperties":true,"type":"object","title":"Access Controls"},"api_key_summary":{"additionalProperties":{"type":"integer"},"type":"object","title":"Api Key Summary"},"compliance_status":{"type":"string","title":"Compliance Status"}},"type":"object","required":["generated_at","report_period_days","workspace_id","audit_summary","retention_policy","encryption","access_controls","api_key_summary","compliance_status"],"title":"HipaaReportResponse"}}}} ``` ## The HumanSegment object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"HumanSegment":{"properties":{"speaker_role":{"type":"string","title":"Speaker Role"},"transcript":{"type":"string","title":"Transcript"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp"}},"type":"object","required":["speaker_role","transcript"],"title":"HumanSegment"}}}} ``` ## The IdentifierString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The Identity object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Identity":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"default_spoken_language":{"type":"string","title":"Default Spoken Language"},"relationship_to_developer":{"$ref":"#/components/schemas/RelationshipToDeveloper"}},"type":"object","required":["name","role","developed_by","default_spoken_language"],"title":"Identity"},"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"}}}} ``` ## The IdentityMetrics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IdentityMetrics":{"properties":{"active_api_keys":{"type":"integer","title":"Active Api Keys","default":0},"active_sessions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Sessions"},"failed_auths_1h":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Failed Auths 1H"},"locked_accounts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Locked Accounts"},"mfa_coverage_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mfa Coverage Pct"}},"type":"object","title":"IdentityMetrics"}}}} ``` ## The Index-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Index-Input":{"properties":{"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"}},"type":"object","required":["columns"],"title":"Index"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The Index-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Index-Output":{"properties":{"name":{"type":"string","title":"Name"},"definition":{"type":"string","title":"Definition","description":"``pg_indexes.indexdef`` — the full CREATE INDEX statement."}},"type":"object","required":["name","definition"],"title":"Index"}}}} ``` ## The InjectRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InjectRequest":{"properties":{"message":{"type":"string","maxLength":5000,"minLength":1,"title":"Message"},"sender":{"type":"string","maxLength":200,"title":"Sender","default":"System"},"event_type":{"type":"string","enum":["external_event","guidance"],"title":"Event Type","description":"external_event (factual info) or guidance (instructional)","default":"external_event"}},"type":"object","required":["message"],"title":"InjectRequest"}}}} ``` ## The InjectResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InjectResponse":{"properties":{"status":{"type":"string","enum":["delivered","queued_no_subscriber"],"title":"Status"},"call_sid":{"type":"string","title":"Call Sid"}},"type":"object","required":["status","call_sid"],"title":"InjectResponse"}}}} ``` ## The InstrumentationScope object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InstrumentationScope":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"}},"type":"object","required":["name","version"],"title":"InstrumentationScope"}}}} ``` ## The IntakeFieldType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntakeFieldType":{"type":"string","enum":["str","int","float","bool","date","datetime"],"title":"IntakeFieldType","description":"Allowed ``schema[].type`` values for a registered contract.\n\nConfirmed set (intake-ui-mvp design contract point #1): scalars plus\nISO date/datetime. Coercion semantics live in :func:`_coerces`."}}}} ``` ## The IntakeFileRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]}}}} ``` ## The IntakeSourceRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntakeSourceRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"source_id."},"source_type":{"type":"string","title":"Source Type"},"display_name":{"type":"string","title":"Display Name"},"drive_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Id"},"folders":{"items":{"$ref":"#/components/schemas/DriveFolderMapping"},"type":"array","title":"Folders"},"impersonate_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impersonate Subject","description":"DWD impersonation subject, if this source authenticates via domain-wide delegation."},"status":{"type":"string","title":"Status"},"created_ts":{"type":"string","title":"Created Ts","description":"ISO-8601 timestamp."}},"type":"object","required":["id","source_type","display_name","folders","status","created_ts"],"title":"IntakeSourceRow","description":"A registered intake source (Sources list)."},"DriveFolderMapping":{"properties":{"folder_id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Folder Id"},"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"contains_phi":{"type":"boolean","title":"Contains Phi","default":true}},"type":"object","required":["folder_id","dataset"],"title":"DriveFolderMapping","description":"One Google Drive folder ↔ one intake dataset.\n\n``folder_id`` is the Drive folder id (the identity — never the folder name,\nwhich can be renamed/moved). One folder maps to exactly one dataset."}}}} ``` ## The IntegrationApprovalResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntegrationApprovalResponse":{"properties":{"status":{"type":"string","enum":["granted","rejected"],"title":"Status"},"conversation_id":{"type":"string","maxLength":256,"minLength":1,"title":"Conversation Id"}},"type":"object","required":["status","conversation_id"],"title":"IntegrationApprovalResponse","description":"Resolution outcome for a pending integration-write approval."}}}} ``` ## The IntegrationRejectRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntegrationRejectRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason"}},"type":"object","title":"IntegrationRejectRequest","description":"Reject body — optional free-text reason surfaced to the agent."}}}} ``` ## The IntegrationToolRef-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntegrationToolRef-Input":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."}}}} ``` ## The InteractionDynamics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InteractionDynamics":{"properties":{"turn_taking_quality":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Turn Taking Quality","description":"How well speakers managed turn-taking - interruptions, overlaps, pacing"},"information_density":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Information Density","description":"Whether the agent gave too much or too little information per turn"},"repair_effectiveness":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Repair Effectiveness","description":"How misunderstandings were detected and resolved"},"rapport_trajectory":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Rapport Trajectory","description":"How the interpersonal dynamic evolved across the call"}},"type":"object","title":"InteractionDynamics","description":"System-level analysis of the conversation as a whole."}}}} ``` ## The InternalServiceConfigResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InternalServiceConfigResponse":{"properties":{"service":{"$ref":"#/components/schemas/Service"},"agent_version":{"$ref":"#/components/schemas/AgentVersion"},"context_graph_version":{"$ref":"#/components/schemas/ContextGraphVersion"}},"type":"object","required":["service","agent_version","context_graph_version"],"title":"InternalServiceConfigResponse","description":"Composite response matching ServiceConfig shape for voice-agent consumption."},"Service":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet-Output"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity","default":3},"channel_type":{"type":"string","enum":["voice","text"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig-Output"},{"type":"null"}]},"accepted_context":{"items":{"$ref":"#/components/schemas/ContextKeySpec"},"type":"array","maxItems":100,"title":"Accepted Context"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","name","description","agent_id","context_graph_id","keyterms","is_active","version_sets","tags"],"title":"Service","description":"A service links an agent + context graph + version sets."},"VersionSet-Output":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig-Output":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"DescriptionString":{"type":"string","maxLength":2000},"AgentVersion":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"version":{"type":"integer","title":"Version"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"initials":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initials"},"identity":{"$ref":"#/components/schemas/Identity"},"background":{"type":"string","title":"Background"},"behaviors":{"items":{"type":"string"},"type":"array","title":"Behaviors"},"communication_patterns":{"items":{"type":"string"},"type":"array","title":"Communication Patterns"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/VoiceConfig"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","agent_id","version","identity","background","behaviors","communication_patterns"],"title":"AgentVersion","description":"A version of an Agent document."},"Identity":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role"},"developed_by":{"type":"string","title":"Developed By"},"default_spoken_language":{"type":"string","title":"Default Spoken Language"},"relationship_to_developer":{"$ref":"#/components/schemas/RelationshipToDeveloper"}},"type":"object","required":["name","role","developed_by","default_spoken_language"],"title":"Identity"},"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"},"VoiceConfig":{"properties":{"voice_id":{"type":"string","title":"Voice Id"},"stability":{"type":"number","title":"Stability","default":0},"similarity_boost":{"type":"number","title":"Similarity Boost","default":0},"style":{"type":"number","title":"Style","default":0},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"}},"type":"object","required":["voice_id"],"title":"VoiceConfig"},"ContextGraphVersion":{"properties":{"id":{"type":"string","format":"uuid","title":"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","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"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","context_graph_id","version","description","states","new_user_initial_state","returning_user_initial_state","terminal_state"],"title":"ContextGraphVersion","description":"A version of a hierarchical state machine (context graph)."},"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The InternalSkillResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InternalSkillResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model","default":"claude-sonnet-5"},"max_tokens":{"type":"integer","title":"Max Tokens","default":4096},"max_result_chars":{"type":"integer","title":"Max Result Chars","default":2000},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S","default":60},"thinking_effort":{"anyOf":[{"$ref":"#/components/schemas/ThinkingEffort"},{"type":"null"}]},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P"},"enable_caching":{"type":"boolean","title":"Enable Caching","default":true},"enable_citations":{"type":"boolean","title":"Enable Citations","default":false},"use_structured_output":{"type":"boolean","title":"Use Structured Output","default":false},"integration_tools":{"items":{"$ref":"#/components/schemas/src__routes__internal_skills__IntegrationToolRef"},"type":"array","title":"Integration Tools","default":[]},"static_tools":{"items":{"$ref":"#/components/schemas/src__routes__internal_skills__StaticToolDef"},"type":"array","title":"Static Tools","default":[]},"enabled":{"type":"boolean","title":"Enabled","default":true},"max_agent_turns":{"type":"integer","title":"Max Agent Turns","default":20},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled","default":true},"approval_required":{"type":"boolean","title":"Approval Required","default":false}},"type":"object","required":["id","workspace_id","slug","name","description"],"title":"InternalSkillResponse"},"ThinkingEffort":{"type":"string","enum":["low","medium","high"]},"src__routes__internal_skills__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef"},"src__routes__internal_skills__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef"}}}} ``` ## The InternalSkillsListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InternalSkillsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/InternalSkillResponse"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"InternalSkillsListResponse"},"InternalSkillResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model","default":"claude-sonnet-5"},"max_tokens":{"type":"integer","title":"Max Tokens","default":4096},"max_result_chars":{"type":"integer","title":"Max Result Chars","default":2000},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S","default":60},"thinking_effort":{"anyOf":[{"$ref":"#/components/schemas/ThinkingEffort"},{"type":"null"}]},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P"},"enable_caching":{"type":"boolean","title":"Enable Caching","default":true},"enable_citations":{"type":"boolean","title":"Enable Citations","default":false},"use_structured_output":{"type":"boolean","title":"Use Structured Output","default":false},"integration_tools":{"items":{"$ref":"#/components/schemas/src__routes__internal_skills__IntegrationToolRef"},"type":"array","title":"Integration Tools","default":[]},"static_tools":{"items":{"$ref":"#/components/schemas/src__routes__internal_skills__StaticToolDef"},"type":"array","title":"Static Tools","default":[]},"enabled":{"type":"boolean","title":"Enabled","default":true},"max_agent_turns":{"type":"integer","title":"Max Agent Turns","default":20},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled","default":true},"approval_required":{"type":"boolean","title":"Approval Required","default":false}},"type":"object","required":["id","workspace_id","slug","name","description"],"title":"InternalSkillResponse"},"ThinkingEffort":{"type":"string","enum":["low","medium","high"]},"src__routes__internal_skills__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef"},"src__routes__internal_skills__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef"}}}} ``` ## The InvokeRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InvokeRequest":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Caller arguments matching input_schema."}},"type":"object","title":"InvokeRequest","description":"Invoke a registered function with caller-supplied args."}}}} ``` ## The InvokeResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"InvokeResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"row_count":{"type":"integer","title":"Row Count","default":0}},"type":"object","title":"InvokeResponse"}}}} ``` ## The JoinCallRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"JoinCallRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","default":"takeover"}},"type":"object","required":["call_sid"],"title":"JoinCallRequest","description":"Request to join an active call as operator."}}}} ``` ## The JoinCallResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"JoinCallResponse":{"properties":{"participant_call_sid":{"type":"string","title":"Participant Call Sid","description":"Twilio participant call SID"},"conference_sid":{"type":"string","title":"Conference Sid","description":"Twilio conference SID"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","description":"Operator mode: listen or takeover"},"operator_entity_id":{"type":"string","format":"uuid","title":"Operator Entity Id","description":"World entity ID of the operator"}},"type":"object","required":["participant_call_sid","conference_sid","mode","operator_entity_id"],"title":"JoinCallResponse","description":"Confirmation of operator joining a call's conference."}}}} ``` ## The JsonValue object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]}}}} ``` ## The KetamineBlockOverlapParams object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"KetamineBlockOverlapParams":{"properties":{"rule_kind":{"type":"string","const":"ketamine_block_overlap","title":"Rule Kind","default":"ketamine_block_overlap"},"window_days":{"type":"integer","maximum":365,"minimum":1,"title":"Window Days"}},"type":"object","required":["window_days"],"title":"KetamineBlockOverlapParams","description":"How many days after a ketamine session to block follow-up\nappointments (clinical safety window)."}}}} ``` ## The KeyMoment object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"KeyMoment":{"properties":{"turn":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn","description":"Turn index where the moment occurred"},"type":{"type":"string","enum":["latency_spike","silence","barge_in","loop","tool_failure","escalation","safety_flag","high_risk","elevated_risk"],"title":"Type","description":"Category of the moment"},"severity":{"type":"string","enum":["info","warning","error"],"title":"Severity","description":"Severity level","default":"warning"},"description":{"type":"string","title":"Description","description":"Human-readable description"}},"type":"object","required":["type","description"],"title":"KeyMoment","description":"Notable event during the call worth highlighting."}}}} ``` ## The KeyValue object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"$ref":"#/components/schemas/AnyValue"}},"type":"object","required":["key","value"],"title":"KeyValue","description":"OTLP ``KeyValue`` attribute pair."},"AnyValue":{"additionalProperties":true,"type":"object"}}}} ``` ## The LLMConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."}}}} ``` ## The LLMExperienceControls object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."}}}} ``` ## The LanguageProviderEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The LastPollInfo object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LastPollInfo":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"duration_ms":{"type":"integer","title":"Duration Ms","default":0},"event_count":{"type":"integer","title":"Event Count","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"LastPollInfo"}}}} ``` ## The LatencySummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LatencySummary":{"properties":{"avg_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Engine Ms","description":"Average reasoning-engine latency (ms)"},"p50_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Engine Ms","description":"Median engine latency (ms)"},"p95_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Engine Ms","description":"95th percentile engine latency (ms)"},"avg_audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Audio Ttfb Ms","description":"Average audio time-to-first-byte (ms)"},"p50_audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Audio Ttfb Ms","description":"Median audio TTFB (ms)"},"p95_audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Audio Ttfb Ms","description":"95th percentile audio TTFB (ms)"},"avg_nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Nav Ms","description":"Average navigation latency (ms)"},"avg_render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Render Ms","description":"Average render latency (ms)"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Count","description":"Number of turns the latency averages were computed over"},"silence_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Silence Ratio","description":"Fraction of call spent in silence"}},"type":"object","title":"LatencySummary","description":"Audio + engine latency metrics (one entry per turn averaged)."}}}} ``` ## The LeaveCallRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LeaveCallRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"}},"type":"object","required":["call_sid"],"title":"LeaveCallRequest","description":"Request to remove operator from an active call."}}}} ``` ## The LeaveCallResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LeaveCallResponse":{"properties":{"success":{"type":"boolean","title":"Success"}},"type":"object","required":["success"],"title":"LeaveCallResponse"}}}} ``` ## The Limits object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Limits":{"properties":{"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","title":"Limits"}}}} ``` ## The ListSimulationSuiteRunsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ListSimulationSuiteRunsResponse":{"properties":{"suite_id":{"type":"string","format":"uuid","title":"Suite Id"},"runs":{"items":{"$ref":"#/components/schemas/SimulationSuiteRunSummary"},"type":"array","title":"Runs"}},"type":"object","required":["suite_id","runs"],"title":"ListSimulationSuiteRunsResponse"},"SimulationSuiteRunSummary":{"properties":{"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"expected_case_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Expected Case Count"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"}},"type":"object","required":["suite_run_id","run_ids","total_runs","status"],"title":"SimulationSuiteRunSummary"}}}} ``` ## The ListSimulationSuitesResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ListSimulationSuitesResponse":{"properties":{"suites":{"items":{"$ref":"#/components/schemas/SimulationSuiteResponse"},"type":"array","title":"Suites"}},"type":"object","required":["suites"],"title":"ListSimulationSuitesResponse"},"SimulationSuiteResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","case_count"],"title":"SimulationSuiteResponse","description":"HTTP response shape for first-class simulation suites."}}}} ``` ## The LookupResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LookupResponse":{"properties":{"results":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":200,"title":"Results"}},"type":"object","title":"LookupResponse","description":"Autocompletion results for a surface lookup field."}}}} ``` ## The LoopLatencyPointItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LoopLatencyPointItem":{"properties":{"hour":{"type":"string","format":"date-time","title":"Hour","description":"UTC hour bucket (truncated to the hour)."},"count":{"type":"integer","title":"Count","description":"Sensing→action pairs whose sensing event lands in this hour."},"p50_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Seconds","description":"Median latency for this hour; null if no pairs."}},"type":"object","required":["hour","count"],"title":"LoopLatencyPointItem"}}}} ``` ## The LoopLatencyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LoopLatencyResponse":{"properties":{"as_of":{"type":"string","format":"date-time","title":"As Of","description":"Server clock at query time (UTC)."},"window_hours":{"type":"integer","title":"Window Hours"},"overall_count":{"type":"integer","title":"Overall Count","description":"Total pairs across the window."},"overall_p50_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall P50 Seconds","description":"Median latency across the whole window; null if no pairs."},"sparkline":{"items":{"$ref":"#/components/schemas/LoopLatencyPointItem"},"type":"array","maxItems":168,"title":"Sparkline"},"truncated":{"type":"boolean","title":"Truncated","description":"True when the underlying query hit the row cap; p50 is computed over the truncated sample.","default":false}},"type":"object","required":["as_of","window_hours","overall_count"],"title":"LoopLatencyResponse"},"LoopLatencyPointItem":{"properties":{"hour":{"type":"string","format":"date-time","title":"Hour","description":"UTC hour bucket (truncated to the hour)."},"count":{"type":"integer","title":"Count","description":"Sensing→action pairs whose sensing event lands in this hour."},"p50_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Seconds","description":"Median latency for this hour; null if no pairs."}},"type":"object","required":["hour","count"],"title":"LoopLatencyPointItem"}}}} ``` ## The M42CatalogResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"M42CatalogResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/CatalogEntry"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"M42CatalogResponse"},"CatalogEntry":{"properties":{"name":{"type":"string","title":"Name"},"layer":{"type":"string","title":"Layer"},"description":{"type":"string","title":"Description"},"row_count":{"type":"integer","title":"Row Count"},"exists":{"type":"boolean","title":"Exists"}},"type":"object","required":["name","layer","description","row_count","exists"],"title":"CatalogEntry"}}}} ``` ## The MappedRole object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MappedRole":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","name"],"title":"MappedRole"}}}} ``` ## The MaterializationRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MaterializationRow":{"properties":{"dataset":{"type":"string","title":"Dataset"},"ingestion_mode":{"type":"string","title":"Ingestion Mode"},"status":{"type":"string","enum":["materialized","not_materialized"],"title":"Status"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count"},"last_materialized_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Materialized At"}},"type":"object","required":["dataset","ingestion_mode","status"],"title":"MaterializationRow","description":"Per-dataset status of the customer-data destination table\n(``customer_data_..``)."}}}} ``` ## The MaterializeRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MaterializeRequest":{"properties":{"dataset":{"anyOf":[{"$ref":"#/components/schemas/_DatasetSlug"},{"type":"null"}]}},"type":"object","title":"MaterializeRequest"},"_DatasetSlug":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$"}}}} ``` ## The MaterializeResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MaterializeResponse":{"properties":{"run_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Id"}},"type":"object","title":"MaterializeResponse"}}}} ``` ## The MergedEntitiesResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MergedEntitiesResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"linked_entities":{"items":{"$ref":"#/components/schemas/EntityResponse"},"type":"array","title":"Linked Entities"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["entity_id","linked_entities","total"],"title":"MergedEntitiesResponse"},"EntityResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"entity_type":{"type":"string","title":"Entity Type"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Id"},"external_ids":{"additionalProperties":true,"type":"object","title":"External Ids"},"state":{"additionalProperties":true,"type":"object","title":"State","description":"Full JSONB state blob. Prefer typed fields below.","deprecated":true},"has_projection":{"type":"boolean","title":"Has Projection","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name (person, organization)"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Primary phone number (E.164)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Primary email address"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn","description":"Medical record number"},"appointment_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Status","description":"Appointment status (booked, confirmed, cancelled)"},"appointment_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Appointment Start","description":"Appointment start time (UTC)"},"appointment_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Appointment End","description":"Appointment end time (UTC)"},"appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment Type","description":"Appointment/visit type"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Organization domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Organization industry"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid","description":"Twilio call SID"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction","description":"Call direction (inbound, outbound)"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Call duration in seconds"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Entity status"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Primary data source"},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Seen At"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"event_count":{"type":"integer","title":"Event Count","default":0},"confidence":{"type":"number","title":"Confidence","default":1},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the entity was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the entity was last updated"}},"type":"object","required":["id","workspace_id","entity_type"],"title":"EntityResponse"}}}} ``` ## The MeteringEmitRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MeteringEmitRequest":{"properties":{"event_type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._]*$","title":"Event Type"},"metering_quantity":{"type":"number","minimum":0,"title":"Metering Quantity"},"metering_source":{"type":"string","enum":["production","simulation"],"title":"Metering Source","description":"Traffic class — 'production' or 'simulation'."},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At","description":"When the event happened. Defaults to ingest time."},"metering_unit":{"anyOf":[{"type":"string","maxLength":32,"minLength":1},{"type":"null"}],"title":"Metering Unit"},"metering_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metering Metadata"},"event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Event Id","description":"Optional deterministic row id (typically uuid5(NAMESPACE, '')). Re-emitting with the same value lands on the same world_events row instead of double-billing. Use for backfills and retries. Default: server generates a random uuid4."}},"type":"object","required":["event_type","metering_quantity","metering_source"],"title":"MeteringEmitRequest"}}}} ``` ## The MeteringEmitResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MeteringEmitResponse":{"properties":{"status":{"type":"string","const":"accepted","title":"Status","description":"Emission outcome. Always 'accepted' on 202."},"event_type":{"type":"string","maxLength":64,"minLength":1,"title":"Event Type","description":"Echo of the emitted event_type."}},"type":"object","required":["status","event_type"],"title":"MeteringEmitResponse"}}}} ``` ## The MetricCatalogEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricCatalogEntry":{"properties":{"key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Key","description":"Metric key (lowercase alphanumeric + underscores)"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"metric_type":{"type":"string","enum":["numerical","categorical","boolean"],"title":"Metric Type"},"source":{"type":"string","enum":["call_intelligence","world_events","surface_events","emotion_events","connector_events","zerobus_events","voice_judge_results","custom"],"title":"Source"},"custom_source_key":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Custom Source Key"},"extraction_mode":{"type":"string","enum":["static","ai_classify","ai_extract","ai_query","sql_expr"],"title":"Extraction Mode","default":"static"},"granularity":{"type":"string","enum":["aggregate","per_entity"],"title":"Granularity","default":"aggregate"},"period_granularity":{"type":"string","enum":["hourly","daily"],"title":"Period Granularity","default":"daily"},"latency_tier":{"type":"string","enum":["streaming","near_realtime","batch"],"title":"Latency Tier","default":"batch"},"model_tier":{"type":"string","enum":["free","fast","balanced","max","custom"],"title":"Model Tier","default":"free"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"has_prompt":{"type":"boolean","title":"Has Prompt","default":false},"builtin":{"type":"boolean","title":"Builtin"}},"type":"object","required":["key","name","metric_type","source","builtin"],"title":"MetricCatalogEntry"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The MetricCatalogResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricCatalogResponse":{"properties":{"metrics":{"items":{"$ref":"#/components/schemas/MetricCatalogEntry"},"type":"array","title":"Metrics"}},"type":"object","required":["metrics"],"title":"MetricCatalogResponse"},"MetricCatalogEntry":{"properties":{"key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Key","description":"Metric key (lowercase alphanumeric + underscores)"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"metric_type":{"type":"string","enum":["numerical","categorical","boolean"],"title":"Metric Type"},"source":{"type":"string","enum":["call_intelligence","world_events","surface_events","emotion_events","connector_events","zerobus_events","voice_judge_results","custom"],"title":"Source"},"custom_source_key":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Custom Source Key"},"extraction_mode":{"type":"string","enum":["static","ai_classify","ai_extract","ai_query","sql_expr"],"title":"Extraction Mode","default":"static"},"granularity":{"type":"string","enum":["aggregate","per_entity"],"title":"Granularity","default":"aggregate"},"period_granularity":{"type":"string","enum":["hourly","daily"],"title":"Period Granularity","default":"daily"},"latency_tier":{"type":"string","enum":["streaming","near_realtime","batch"],"title":"Latency Tier","default":"batch"},"model_tier":{"type":"string","enum":["free","fast","balanced","max","custom"],"title":"Model Tier","default":"free"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"has_prompt":{"type":"boolean","title":"Has Prompt","default":false},"builtin":{"type":"boolean","title":"Builtin"}},"type":"object","required":["key","name","metric_type","source","builtin"],"title":"MetricCatalogEntry"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The MetricDefinition object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricDefinition":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Key","description":"Lowercase slug used as metric key (e.g. 'voice_quality_score')"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"metric_type":{"type":"string","enum":["numerical","categorical","boolean"],"title":"Metric Type"},"latency_tier":{"type":"string","enum":["streaming","near_realtime","batch"],"title":"Latency Tier","description":"'streaming' — seconds-latency via ZeroBus streaming ingestion (continuous pipeline). 'near_realtime' — minutes-latency via triggered pipeline refresh. 'batch' — hourly/daily scheduled refresh (default, cheapest).","default":"batch"},"period_granularity":{"type":"string","enum":["hourly","daily"],"title":"Period Granularity","description":"'hourly' — one row per workspace per hour. Use for near_realtime metrics where shift-level visibility matters (voice quality, latency). 'daily' — one row per workspace per day (default, cheapest).","default":"daily"},"source":{"type":"string","enum":["call_intelligence","world_events","surface_events","emotion_events","connector_events","zerobus_events","voice_judge_results","custom"],"title":"Source","description":"Source key for the producer that supplies this metric. Built-ins include 'call_intelligence', 'world_events', and 'surface_events'. Use 'custom' with custom_source_key for extension producers."},"custom_source_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Custom Source Key","description":"Extension source key used only when source='custom'."},"event_types":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Event Types","description":"Event types to scan (e.g. 'call.outcome', 'surface.submitted'). For call_intelligence source, use pseudo-types: 'call_intelligence.row'."},"source_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Filter","description":"Optional SQL WHERE fragment for additional filtering (e.g. \"source = 'voice_agent'\"). Applied after event_type filter."},"extraction_mode":{"type":"string","enum":["static","ai_classify","ai_extract","ai_query","sql_expr"],"title":"Extraction Mode","description":"'static' — JSONB path extraction (fast, free). 'ai_classify' — AI classification into user-defined labels (free). 'ai_extract' — AI field extraction from text (free). 'ai_query' — LLM-powered extraction with custom prompt (uses model_tier). 'sql_expr' — Raw SQL expression for computed metrics.","default":"static"},"extract_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extract Path","description":"JSON path for static extraction (e.g. `$.quality_score`, `$.risk_level`). For `call_intelligence` and `world_events`, single-segment paths resolve to typed columns when available and fall back to JSONB extraction otherwise. Used when `extraction_mode='static'`."},"ai_labels":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Ai Labels","description":"Labels for ai_classify (categories) or ai_extract (field names). Required when extraction_mode='ai_classify' or 'ai_extract'. Examples: ['positive', 'negative', 'neutral'] or ['diagnosis', 'medication']."},"ai_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ai Schema","description":"Extraction schema for ai_extract. Required when extraction_mode='ai_extract'."},"ai_query_endpoint":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Ai Query Endpoint","description":"Model serving endpoint for ai_query. Optional — if omitted, platform resolves from model_tier automatically. Override for custom endpoints."},"ai_query_prompt":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Ai Query Prompt","description":"Prompt template for ai_query. Use {data} placeholder for event data. Example: 'Classify this call transcript into one of: {labels}. Transcript: {data}'. Budgeted at 8KB to hold the full rubric + output spec for standard quality judges (longest authored rubric — conversational_naturalness — is ~5KB)."},"sql_expression":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Sql Expression","description":"Raw SQL expression evaluated in pipeline context. Has access to all columns in the source table. Example: 'CASE WHEN duration_seconds > 120 THEN 1.0 ELSE 0.0 END'. Required when extraction_mode='sql_expr'."},"aggregation":{"type":"string","enum":["count","sum","avg","min","max","count_distinct","ratio","rate"],"title":"Aggregation","description":"How to aggregate extracted values per workspace per period. 'ratio' requires ratio_numerator_event and ratio_denominator_event. 'rate' computes count(true) / count(all) for boolean metrics.","default":"count"},"ratio_numerator_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ratio Numerator Event","description":"Event type for numerator when aggregation='ratio'."},"ratio_denominator_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ratio Denominator Event","description":"Event type for denominator when aggregation='ratio'."},"valid_range_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valid Range Min","description":"Minimum valid value for numerical metrics. Pipeline drops values outside range."},"valid_range_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valid Range Max","description":"Maximum valid value for numerical metrics."},"freshness_sla_minutes":{"type":"integer","maximum":1440,"minimum":5,"title":"Freshness Sla Minutes","description":"Max acceptable staleness in minutes before alerting. Default: 60 (1 hour).","default":60},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit","description":"Display unit (e.g. 'score', 'minutes', '%', 'count')."},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Categories","description":"Allowed values for categorical metrics. Pipeline drops values not in this list when set."},"model_tier":{"type":"string","enum":["free","fast","balanced","max","custom"],"title":"Model Tier","description":"AI model tier for extraction quality/cost tradeoff. 'free' — platform managed models (ai_classify, ai_extract). 'fast' — optimized for simple classification, low latency. 'balanced' — quality scoring, moderate reasoning. 'max' — complex analysis, multi-step reasoning. 'custom' — use ai_query_endpoint directly. When extraction_mode='ai_query' and ai_query_endpoint is not set, platform resolves model_tier to the optimal model automatically.","default":"free"},"channel_scope":{"type":"string","enum":["all","voice","text","surface","inbound","outbound"],"title":"Channel Scope","description":"Business-logic channel filter. 'voice' — voice calls only. 'text' — SMS/text sessions. 'surface' — form submissions. 'inbound'/'outbound' — by direction. 'all' — no channel filter (default). Pipeline translates to appropriate source + event_type filters.","default":"all"},"applies_to_product_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Applies To Product Types","description":"Product types this metric applies to (matches service tags, e.g. 'scheduling', 'outbound', 'coaching', 'intake', 'triage', 'support'). When set, the metric only computes for calls belonging to services whose config.tags include one of these keys. When None (default), the metric applies to every service regardless of product type."},"prompt":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Prompt","description":"Rubric prompt for LLM judge evaluation with {$.path} context variables. Each {$.path} reference is extracted from the entity's projected state and substituted before sending to ai_query. The prompt is both the evaluation criteria and the context specification."},"granularity":{"type":"string","enum":["aggregate","per_entity"],"title":"Granularity","description":"'aggregate' groups by (workspace, period) — one value per time bucket. 'per_entity' keeps entity_id — one value per entity (call, encounter). Judge metrics are typically per_entity. Computed metrics are typically aggregate.","default":"aggregate"},"active":{"type":"boolean","title":"Active","default":true},"builtin":{"type":"boolean","title":"Builtin","description":"True for platform-provided metrics (read-only key).","default":false}},"type":"object","required":["key","name","metric_type","source","event_types"],"title":"MetricDefinition","description":"A single metric definition — what to extract and how.\n\nTwo broad modes:\n- Built-in metrics: extraction is handled by hardcoded pipeline logic\n (extract_path + aggregation). Shipped with every workspace.\n- Custom metrics: extraction uses AI functions or static JSONB paths.\n Defined per-workspace via settings API.\n\nFrozen: builtins are process-wide singletons exposed via the\n``BUILTIN_METRICS`` list. A mutable list field (e.g.\n``applies_to_product_types``) could otherwise be mutated by one caller\nand leak into every subsequent call in the same process."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The MetricListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricListResponse":{"properties":{"metrics":{"items":{"oneOf":[{"$ref":"#/components/schemas/NumericalMetricValueResponse"},{"$ref":"#/components/schemas/CategoricalMetricValueResponse"},{"$ref":"#/components/schemas/BooleanMetricValueResponse"}],"discriminator":{"propertyName":"metric_type","mapping":{"boolean":"#/components/schemas/BooleanMetricValueResponse","categorical":"#/components/schemas/CategoricalMetricValueResponse","numerical":"#/components/schemas/NumericalMetricValueResponse"}}},"type":"array","title":"Metrics"}},"type":"object","required":["metrics"],"title":"MetricListResponse"},"NumericalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"numerical","title":"Metric Type"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"NumericalMetricValueResponse"},"CategoricalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"categorical","title":"Metric Type"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"CategoricalMetricValueResponse"},"BooleanMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"boolean","title":"Metric Type"},"value":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"BooleanMetricValueResponse"}}}} ``` ## The MetricProjectionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricProjectionResponse":{"properties":{"status":{"type":"string","const":"projected","title":"Status"},"accepted":{"type":"integer","title":"Accepted"},"skipped_duplicates":{"type":"integer","title":"Skipped Duplicates"},"queued_jobs":{"type":"integer","title":"Queued Jobs","default":0,"deprecated":true}},"type":"object","required":["status","accepted","skipped_duplicates"],"title":"MetricProjectionResponse"}}}} ``` ## The MetricSettingsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricSettingsRequest":{"properties":{"definitions":{"anyOf":[{"items":{"$ref":"#/components/schemas/MetricDefinition"},"type":"array"},{"type":"null"}],"title":"Definitions"}},"type":"object","title":"MetricSettingsRequest","description":"Partial update — only provided fields are changed.\n\nThe definitions list is replaced entirely when provided.\nBuilt-in metrics can be deactivated (active=false) or have their\nfreshness_sla_minutes changed, but their key cannot be reused\nfor custom metrics."},"MetricDefinition":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Key","description":"Lowercase slug used as metric key (e.g. 'voice_quality_score')"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"metric_type":{"type":"string","enum":["numerical","categorical","boolean"],"title":"Metric Type"},"latency_tier":{"type":"string","enum":["streaming","near_realtime","batch"],"title":"Latency Tier","description":"'streaming' — seconds-latency via ZeroBus streaming ingestion (continuous pipeline). 'near_realtime' — minutes-latency via triggered pipeline refresh. 'batch' — hourly/daily scheduled refresh (default, cheapest).","default":"batch"},"period_granularity":{"type":"string","enum":["hourly","daily"],"title":"Period Granularity","description":"'hourly' — one row per workspace per hour. Use for near_realtime metrics where shift-level visibility matters (voice quality, latency). 'daily' — one row per workspace per day (default, cheapest).","default":"daily"},"source":{"type":"string","enum":["call_intelligence","world_events","surface_events","emotion_events","connector_events","zerobus_events","voice_judge_results","custom"],"title":"Source","description":"Source key for the producer that supplies this metric. Built-ins include 'call_intelligence', 'world_events', and 'surface_events'. Use 'custom' with custom_source_key for extension producers."},"custom_source_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Custom Source Key","description":"Extension source key used only when source='custom'."},"event_types":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Event Types","description":"Event types to scan (e.g. 'call.outcome', 'surface.submitted'). For call_intelligence source, use pseudo-types: 'call_intelligence.row'."},"source_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Filter","description":"Optional SQL WHERE fragment for additional filtering (e.g. \"source = 'voice_agent'\"). Applied after event_type filter."},"extraction_mode":{"type":"string","enum":["static","ai_classify","ai_extract","ai_query","sql_expr"],"title":"Extraction Mode","description":"'static' — JSONB path extraction (fast, free). 'ai_classify' — AI classification into user-defined labels (free). 'ai_extract' — AI field extraction from text (free). 'ai_query' — LLM-powered extraction with custom prompt (uses model_tier). 'sql_expr' — Raw SQL expression for computed metrics.","default":"static"},"extract_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extract Path","description":"JSON path for static extraction (e.g. `$.quality_score`, `$.risk_level`). For `call_intelligence` and `world_events`, single-segment paths resolve to typed columns when available and fall back to JSONB extraction otherwise. Used when `extraction_mode='static'`."},"ai_labels":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Ai Labels","description":"Labels for ai_classify (categories) or ai_extract (field names). Required when extraction_mode='ai_classify' or 'ai_extract'. Examples: ['positive', 'negative', 'neutral'] or ['diagnosis', 'medication']."},"ai_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ai Schema","description":"Extraction schema for ai_extract. Required when extraction_mode='ai_extract'."},"ai_query_endpoint":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Ai Query Endpoint","description":"Model serving endpoint for ai_query. Optional — if omitted, platform resolves from model_tier automatically. Override for custom endpoints."},"ai_query_prompt":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Ai Query Prompt","description":"Prompt template for ai_query. Use {data} placeholder for event data. Example: 'Classify this call transcript into one of: {labels}. Transcript: {data}'. Budgeted at 8KB to hold the full rubric + output spec for standard quality judges (longest authored rubric — conversational_naturalness — is ~5KB)."},"sql_expression":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Sql Expression","description":"Raw SQL expression evaluated in pipeline context. Has access to all columns in the source table. Example: 'CASE WHEN duration_seconds > 120 THEN 1.0 ELSE 0.0 END'. Required when extraction_mode='sql_expr'."},"aggregation":{"type":"string","enum":["count","sum","avg","min","max","count_distinct","ratio","rate"],"title":"Aggregation","description":"How to aggregate extracted values per workspace per period. 'ratio' requires ratio_numerator_event and ratio_denominator_event. 'rate' computes count(true) / count(all) for boolean metrics.","default":"count"},"ratio_numerator_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ratio Numerator Event","description":"Event type for numerator when aggregation='ratio'."},"ratio_denominator_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ratio Denominator Event","description":"Event type for denominator when aggregation='ratio'."},"valid_range_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valid Range Min","description":"Minimum valid value for numerical metrics. Pipeline drops values outside range."},"valid_range_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valid Range Max","description":"Maximum valid value for numerical metrics."},"freshness_sla_minutes":{"type":"integer","maximum":1440,"minimum":5,"title":"Freshness Sla Minutes","description":"Max acceptable staleness in minutes before alerting. Default: 60 (1 hour).","default":60},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit","description":"Display unit (e.g. 'score', 'minutes', '%', 'count')."},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Categories","description":"Allowed values for categorical metrics. Pipeline drops values not in this list when set."},"model_tier":{"type":"string","enum":["free","fast","balanced","max","custom"],"title":"Model Tier","description":"AI model tier for extraction quality/cost tradeoff. 'free' — platform managed models (ai_classify, ai_extract). 'fast' — optimized for simple classification, low latency. 'balanced' — quality scoring, moderate reasoning. 'max' — complex analysis, multi-step reasoning. 'custom' — use ai_query_endpoint directly. When extraction_mode='ai_query' and ai_query_endpoint is not set, platform resolves model_tier to the optimal model automatically.","default":"free"},"channel_scope":{"type":"string","enum":["all","voice","text","surface","inbound","outbound"],"title":"Channel Scope","description":"Business-logic channel filter. 'voice' — voice calls only. 'text' — SMS/text sessions. 'surface' — form submissions. 'inbound'/'outbound' — by direction. 'all' — no channel filter (default). Pipeline translates to appropriate source + event_type filters.","default":"all"},"applies_to_product_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Applies To Product Types","description":"Product types this metric applies to (matches service tags, e.g. 'scheduling', 'outbound', 'coaching', 'intake', 'triage', 'support'). When set, the metric only computes for calls belonging to services whose config.tags include one of these keys. When None (default), the metric applies to every service regardless of product type."},"prompt":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Prompt","description":"Rubric prompt for LLM judge evaluation with {$.path} context variables. Each {$.path} reference is extracted from the entity's projected state and substituted before sending to ai_query. The prompt is both the evaluation criteria and the context specification."},"granularity":{"type":"string","enum":["aggregate","per_entity"],"title":"Granularity","description":"'aggregate' groups by (workspace, period) — one value per time bucket. 'per_entity' keeps entity_id — one value per entity (call, encounter). Judge metrics are typically per_entity. Computed metrics are typically aggregate.","default":"aggregate"},"active":{"type":"boolean","title":"Active","default":true},"builtin":{"type":"boolean","title":"Builtin","description":"True for platform-provided metrics (read-only key).","default":false}},"type":"object","required":["key","name","metric_type","source","event_types"],"title":"MetricDefinition","description":"A single metric definition — what to extract and how.\n\nTwo broad modes:\n- Built-in metrics: extraction is handled by hardcoded pipeline logic\n (extract_path + aggregation). Shipped with every workspace.\n- Custom metrics: extraction uses AI functions or static JSONB paths.\n Defined per-workspace via settings API.\n\nFrozen: builtins are process-wide singletons exposed via the\n``BUILTIN_METRICS`` list. A mutable list field (e.g.\n``applies_to_product_types``) could otherwise be mutated by one caller\nand leak into every subsequent call in the same process."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The MetricSettingsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricSettingsResponse":{"properties":{"definitions":{"items":{"$ref":"#/components/schemas/MetricDefinition"},"type":"array","title":"Definitions"}},"type":"object","required":["definitions"],"title":"MetricSettingsResponse"},"MetricDefinition":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Key","description":"Lowercase slug used as metric key (e.g. 'voice_quality_score')"},"name":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"metric_type":{"type":"string","enum":["numerical","categorical","boolean"],"title":"Metric Type"},"latency_tier":{"type":"string","enum":["streaming","near_realtime","batch"],"title":"Latency Tier","description":"'streaming' — seconds-latency via ZeroBus streaming ingestion (continuous pipeline). 'near_realtime' — minutes-latency via triggered pipeline refresh. 'batch' — hourly/daily scheduled refresh (default, cheapest).","default":"batch"},"period_granularity":{"type":"string","enum":["hourly","daily"],"title":"Period Granularity","description":"'hourly' — one row per workspace per hour. Use for near_realtime metrics where shift-level visibility matters (voice quality, latency). 'daily' — one row per workspace per day (default, cheapest).","default":"daily"},"source":{"type":"string","enum":["call_intelligence","world_events","surface_events","emotion_events","connector_events","zerobus_events","voice_judge_results","custom"],"title":"Source","description":"Source key for the producer that supplies this metric. Built-ins include 'call_intelligence', 'world_events', and 'surface_events'. Use 'custom' with custom_source_key for extension producers."},"custom_source_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Custom Source Key","description":"Extension source key used only when source='custom'."},"event_types":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Event Types","description":"Event types to scan (e.g. 'call.outcome', 'surface.submitted'). For call_intelligence source, use pseudo-types: 'call_intelligence.row'."},"source_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Filter","description":"Optional SQL WHERE fragment for additional filtering (e.g. \"source = 'voice_agent'\"). Applied after event_type filter."},"extraction_mode":{"type":"string","enum":["static","ai_classify","ai_extract","ai_query","sql_expr"],"title":"Extraction Mode","description":"'static' — JSONB path extraction (fast, free). 'ai_classify' — AI classification into user-defined labels (free). 'ai_extract' — AI field extraction from text (free). 'ai_query' — LLM-powered extraction with custom prompt (uses model_tier). 'sql_expr' — Raw SQL expression for computed metrics.","default":"static"},"extract_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extract Path","description":"JSON path for static extraction (e.g. `$.quality_score`, `$.risk_level`). For `call_intelligence` and `world_events`, single-segment paths resolve to typed columns when available and fall back to JSONB extraction otherwise. Used when `extraction_mode='static'`."},"ai_labels":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Ai Labels","description":"Labels for ai_classify (categories) or ai_extract (field names). Required when extraction_mode='ai_classify' or 'ai_extract'. Examples: ['positive', 'negative', 'neutral'] or ['diagnosis', 'medication']."},"ai_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ai Schema","description":"Extraction schema for ai_extract. Required when extraction_mode='ai_extract'."},"ai_query_endpoint":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Ai Query Endpoint","description":"Model serving endpoint for ai_query. Optional — if omitted, platform resolves from model_tier automatically. Override for custom endpoints."},"ai_query_prompt":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Ai Query Prompt","description":"Prompt template for ai_query. Use {data} placeholder for event data. Example: 'Classify this call transcript into one of: {labels}. Transcript: {data}'. Budgeted at 8KB to hold the full rubric + output spec for standard quality judges (longest authored rubric — conversational_naturalness — is ~5KB)."},"sql_expression":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Sql Expression","description":"Raw SQL expression evaluated in pipeline context. Has access to all columns in the source table. Example: 'CASE WHEN duration_seconds > 120 THEN 1.0 ELSE 0.0 END'. Required when extraction_mode='sql_expr'."},"aggregation":{"type":"string","enum":["count","sum","avg","min","max","count_distinct","ratio","rate"],"title":"Aggregation","description":"How to aggregate extracted values per workspace per period. 'ratio' requires ratio_numerator_event and ratio_denominator_event. 'rate' computes count(true) / count(all) for boolean metrics.","default":"count"},"ratio_numerator_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ratio Numerator Event","description":"Event type for numerator when aggregation='ratio'."},"ratio_denominator_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ratio Denominator Event","description":"Event type for denominator when aggregation='ratio'."},"valid_range_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valid Range Min","description":"Minimum valid value for numerical metrics. Pipeline drops values outside range."},"valid_range_max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valid Range Max","description":"Maximum valid value for numerical metrics."},"freshness_sla_minutes":{"type":"integer","maximum":1440,"minimum":5,"title":"Freshness Sla Minutes","description":"Max acceptable staleness in minutes before alerting. Default: 60 (1 hour).","default":60},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit","description":"Display unit (e.g. 'score', 'minutes', '%', 'count')."},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Categories","description":"Allowed values for categorical metrics. Pipeline drops values not in this list when set."},"model_tier":{"type":"string","enum":["free","fast","balanced","max","custom"],"title":"Model Tier","description":"AI model tier for extraction quality/cost tradeoff. 'free' — platform managed models (ai_classify, ai_extract). 'fast' — optimized for simple classification, low latency. 'balanced' — quality scoring, moderate reasoning. 'max' — complex analysis, multi-step reasoning. 'custom' — use ai_query_endpoint directly. When extraction_mode='ai_query' and ai_query_endpoint is not set, platform resolves model_tier to the optimal model automatically.","default":"free"},"channel_scope":{"type":"string","enum":["all","voice","text","surface","inbound","outbound"],"title":"Channel Scope","description":"Business-logic channel filter. 'voice' — voice calls only. 'text' — SMS/text sessions. 'surface' — form submissions. 'inbound'/'outbound' — by direction. 'all' — no channel filter (default). Pipeline translates to appropriate source + event_type filters.","default":"all"},"applies_to_product_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Applies To Product Types","description":"Product types this metric applies to (matches service tags, e.g. 'scheduling', 'outbound', 'coaching', 'intake', 'triage', 'support'). When set, the metric only computes for calls belonging to services whose config.tags include one of these keys. When None (default), the metric applies to every service regardless of product type."},"prompt":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Prompt","description":"Rubric prompt for LLM judge evaluation with {$.path} context variables. Each {$.path} reference is extracted from the entity's projected state and substituted before sending to ai_query. The prompt is both the evaluation criteria and the context specification."},"granularity":{"type":"string","enum":["aggregate","per_entity"],"title":"Granularity","description":"'aggregate' groups by (workspace, period) — one value per time bucket. 'per_entity' keeps entity_id — one value per entity (call, encounter). Judge metrics are typically per_entity. Computed metrics are typically aggregate.","default":"aggregate"},"active":{"type":"boolean","title":"Active","default":true},"builtin":{"type":"boolean","title":"Builtin","description":"True for platform-provided metrics (read-only key).","default":false}},"type":"object","required":["key","name","metric_type","source","event_types"],"title":"MetricDefinition","description":"A single metric definition — what to extract and how.\n\nTwo broad modes:\n- Built-in metrics: extraction is handled by hardcoded pipeline logic\n (extract_path + aggregation). Shipped with every workspace.\n- Custom metrics: extraction uses AI functions or static JSONB paths.\n Defined per-workspace via settings API.\n\nFrozen: builtins are process-wide singletons exposed via the\n``BUILTIN_METRICS`` list. A mutable list field (e.g.\n``applies_to_product_types``) could otherwise be mutated by one caller\nand leak into every subsequent call in the same process."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The MetricStoreRunResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricStoreRunResponse":{"properties":{"run_id":{"type":"integer","title":"Run Id"}},"type":"object","required":["run_id"],"title":"MetricStoreRunResponse"}}}} ``` ## The MetricStoreRunStatusResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MetricStoreRunStatusResponse":{"properties":{"run_id":{"type":"integer","title":"Run Id"},"life_cycle_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Life Cycle State"},"result_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result State"},"state_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Message"}},"type":"object","required":["run_id"],"title":"MetricStoreRunStatusResponse"}}}} ``` ## The MigrationConversationItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MigrationConversationItem":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"source_conversation_id":{"type":"string","maxLength":128,"minLength":1,"title":"Source Conversation Id"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"type":"string","format":"date-time","title":"Ended At"},"channel_kind":{"$ref":"#/components/schemas/ChannelKind","default":"web"},"turn_count":{"type":"integer","minimum":0,"title":"Turn Count","default":0}},"type":"object","required":["entity_id","source_conversation_id","started_at","ended_at"],"title":"MigrationConversationItem"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."}}}} ``` ## The MigrationConversationsBody object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MigrationConversationsBody":{"properties":{"conversations":{"items":{"$ref":"#/components/schemas/MigrationConversationItem"},"type":"array","maxItems":500,"minItems":1,"title":"Conversations"}},"type":"object","required":["conversations"],"title":"MigrationConversationsBody"},"MigrationConversationItem":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"source_conversation_id":{"type":"string","maxLength":128,"minLength":1,"title":"Source Conversation Id"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"type":"string","format":"date-time","title":"Ended At"},"channel_kind":{"$ref":"#/components/schemas/ChannelKind","default":"web"},"turn_count":{"type":"integer","minimum":0,"title":"Turn Count","default":0}},"type":"object","required":["entity_id","source_conversation_id","started_at","ended_at"],"title":"MigrationConversationItem"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."}}}} ``` ## The MigrationConversationsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MigrationConversationsResponse":{"properties":{"imported":{"type":"integer","title":"Imported"},"created":{"type":"integer","title":"Created"},"updated":{"type":"integer","title":"Updated"}},"type":"object","required":["imported","created","updated"],"title":"MigrationConversationsResponse"}}}} ``` ## The ModelCost object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ModelCost":{"properties":{"model_id":{"type":"string","title":"Model Id"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model priced subtotal rounded to cents; can be partial when is_priced is false. Null if none is priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Model priced subtotal / all model priced subtotals in the selected scope, after any service filter.\nIncludes partial subtotals; null when this model has no priced cost or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced; false can coexist with a priced subtotal."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."},"applied_rates":{"items":{"$ref":"#/components/schemas/AppliedRate"},"type":"array","title":"Applied Rates","description":"Effective-date and context-band rates used for this model."}},"type":"object","required":["model_id","calculated_cost_usd","cost_share","is_priced","unpriced_reason","applied_rates"],"title":"ModelCost","description":"Cost and pricing status for one model."},"AppliedRate":{"properties":{"input_rate_effective_from":{"type":"string","format":"date","title":"Input Rate Effective From","description":"Inclusive first usage date for the input rate."},"input_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Input Rate Effective To","description":"Exclusive end usage date for the input rate; null means no end date."},"output_rate_effective_from":{"type":"string","format":"date","title":"Output Rate Effective From","description":"Inclusive first usage date for the output rate."},"output_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Output Rate Effective To","description":"Exclusive end usage date for the output rate; null means no end date."},"cached_rate_effective_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective From","description":"Inclusive first usage date for the cached-input rate; null if no cached rate applied."},"cached_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective To","description":"Exclusive end usage date for the cached-input rate; null if unbounded or no cached rate applied."},"min_input_tokens":{"type":"integer","title":"Min Input Tokens","description":"Inclusive lower bound on per-request context input tokens for the input-rate band."},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens","description":"Inclusive upper bound on per-request context input tokens; null means unbounded."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["input_rate_effective_from","input_rate_effective_to","output_rate_effective_from","output_rate_effective_to","cached_rate_effective_from","cached_rate_effective_to","min_input_tokens","max_input_tokens","input_per_million","cached_input_per_million","output_per_million"],"title":"AppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The ModelRegistryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ModelRegistryResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/ModelRegistryRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"ModelRegistryResponse"},"ModelRegistryRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"model_id":{"type":"string","title":"Model Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"focus_area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Focus Area"},"algorithm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Algorithm"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version"},"trained_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Trained At"},"training_set_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Training Set Size"},"coefficients_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coefficients Json"},"metrics_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metrics Json"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","required":["workspace_id","model_id"],"title":"ModelRegistryRow"}}}} ``` ## The ModelRegistryRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ModelRegistryRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"model_id":{"type":"string","title":"Model Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"focus_area":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Focus Area"},"algorithm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Algorithm"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version"},"trained_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Trained At"},"training_set_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Training Set Size"},"coefficients_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coefficients Json"},"metrics_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metrics Json"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","required":["workspace_id","model_id"],"title":"ModelRegistryRow"}}}} ``` ## The ModelUsage object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ModelUsage":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked requests / its distinct linked conversations in the selected scope; null if none."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ModelUsage","description":"Usage attributed to one model and provider."}}}} ``` ## The NameString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The NinetyDayRollingParams object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NinetyDayRollingParams":{"properties":{"rule_kind":{"type":"string","const":"ninety_day_rolling","title":"Rule Kind","default":"ninety_day_rolling"},"days":{"type":"integer","maximum":365,"minimum":1,"title":"Days"}},"type":"object","required":["days"],"title":"NinetyDayRollingParams","description":"Rolling-window cap on appointments per patient (e.g. 90 days\nbetween TMS sessions)."}}}} ``` ## The NonDesiredState object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"}}}} ``` ## The NoteRollupCategoryEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NoteRollupCategoryEntry":{"properties":{"value":{"type":"string","title":"Value"},"n":{"type":"integer","title":"N"},"pct":{"type":"number","title":"Pct"},"mean_risk":{"type":"number","title":"Mean Risk"},"risk_lift":{"type":"number","title":"Risk Lift"}},"type":"object","required":["value","n","pct","mean_risk","risk_lift"],"title":"NoteRollupCategoryEntry"}}}} ``` ## The NoteRollupResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NoteRollupResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"total_notes":{"type":"integer","title":"Total Notes"},"cohort_mean_risk":{"type":"number","title":"Cohort Mean Risk"},"sentiment_distribution":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Sentiment Distribution"},"top_symptoms":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Top Symptoms"},"top_concerns":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Top Concerns"},"top_medications":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Top Medications"},"sdoh":{"$ref":"#/components/schemas/NoteRollupSdoh"}},"type":"object","required":["workspace_id","total_notes","cohort_mean_risk","sentiment_distribution","top_symptoms","top_concerns","top_medications","sdoh"],"title":"NoteRollupResponse"},"NoteRollupCategoryEntry":{"properties":{"value":{"type":"string","title":"Value"},"n":{"type":"integer","title":"N"},"pct":{"type":"number","title":"Pct"},"mean_risk":{"type":"number","title":"Mean Risk"},"risk_lift":{"type":"number","title":"Risk Lift"}},"type":"object","required":["value","n","pct","mean_risk","risk_lift"],"title":"NoteRollupCategoryEntry"},"NoteRollupSdoh":{"properties":{"activity":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Activity"},"smoking":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Smoking"},"diet":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Diet"}},"type":"object","required":["activity","smoking","diet"],"title":"NoteRollupSdoh"}}}} ``` ## The NoteRollupSdoh object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NoteRollupSdoh":{"properties":{"activity":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Activity"},"smoking":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Smoking"},"diet":{"items":{"$ref":"#/components/schemas/NoteRollupCategoryEntry"},"type":"array","title":"Diet"}},"type":"object","required":["activity","smoking","diet"],"title":"NoteRollupSdoh"},"NoteRollupCategoryEntry":{"properties":{"value":{"type":"string","title":"Value"},"n":{"type":"integer","title":"N"},"pct":{"type":"number","title":"Pct"},"mean_risk":{"type":"number","title":"Mean Risk"},"risk_lift":{"type":"number","title":"Risk Lift"}},"type":"object","required":["value","n","pct","mean_risk","risk_lift"],"title":"NoteRollupCategoryEntry"}}}} ``` ## The NumericalMetricValueResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NumericalMetricValueResponse":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"source":{"type":"string","title":"Source","default":"production"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"period_start":{"type":"string","format":"date-time","title":"Period Start"},"period_end":{"type":"string","format":"date-time","title":"Period End"},"event_count":{"type":"integer","title":"Event Count"},"avg_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Confidence"},"unit":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Unit"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"},"metric_type":{"type":"string","const":"numerical","title":"Metric Type"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["metric_key","period_start","period_end","event_count","metric_type","value"],"title":"NumericalMetricValueResponse"}}}} ``` ## The OAuth2ClientCredentialsAuthDict object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."}}}} ``` ## The OAuth2ClientCredentialsAuthRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OAuth2ClientCredentialsAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type","default":"oauth2_client_credentials"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method","description":"RFC 6749 § 2.3.1: ``basic`` sends client_id+secret as HTTP Basic auth; ``body`` sends them in the form body.","default":"basic"}},"type":"object","required":["token_url","client_id"],"title":"OAuth2ClientCredentialsAuthRequest","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4.\n\nStrict RFC 6749 § 4.4.2 access token request: ``grant_type`` + optional\n``scope``. Client authentication (RFC 6749 § 2.3.1) is orthogonal —\n``client_auth_method`` picks between HTTP Basic auth and form-body\ncredentials. RFC 8707 ``resource`` and non-standard ``audience`` extensions\nare NOT supported here — add them back when a vendor needs one."}}}} ``` ## The OAuth2JwtBearerAuthDict object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."}}}} ``` ## The OAuth2JwtBearerAuthRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OAuth2JwtBearerAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type","default":"oauth2_jwt_bearer"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer","description":"RFC 7523 ``iss`` claim — typically the service-account email or client_id."},"assertion_audience":{"type":"string","title":"Assertion Audience","description":"RFC 7523 ``aud`` claim — typically the token_url."},"assertion_subject":{"type":"string","title":"Assertion Subject","description":"RFC 7523 § 3 ``sub`` claim — MUST be present. For service-account flows\nwhere the client is its own subject, set to the same value as ``assertion_issuer``.\nUse a different value only for delegation / impersonation grants."},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds","default":3600},"include_iat":{"type":"boolean","title":"Include Iat","description":"RFC 7523 § 3 item 6 — ``iat`` claim set to mint time. Most IdPs (Google, Azure)\nrequire it for anti-replay; leave True unless a specific vendor rejects it.","default":true},"include_jti":{"type":"boolean","title":"Include Jti","description":"When True, generate a fresh ``jti`` (anti-replay) on every mint.","default":true},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm","default":"RS256"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage","description":"RFC 7523 flow selector — required; the caller must pick a flow.\n``authorization_grant`` (§ 2.1) sends the JWT as ``assertion`` under\n``grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer``.\n``client_authentication`` (§ 2.2, the ``private_key_jwt`` method) sends it as\n``client_assertion`` + ``client_assertion_type`` under ``grant_type=client_credentials``\n— required by Epic / SMART Backend Services."},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes","description":"RFC 7523 § 2.1 ``scope`` form-body parameter. Vendors that put scopes inside\nthe JWT instead (Google service accounts) use ``extra_claims = {\"scope\": \"...\"}``\nand leave this empty."},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims","description":"RFC 7523 § 3 item 8 — arbitrary additional JWT claims (e.g. Google's\n``scope`` claim, Azure's tenant claim). Merged BEFORE the required claims so\nIdP-specific extensions can't override ``iss`` / ``sub`` / ``aud`` / ``exp`` /\n``iat`` / ``nbf`` / ``jti``.","default":{}}},"type":"object","required":["token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_usage"],"title":"OAuth2JwtBearerAuthRequest","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` (required) selects the flow: § 2.1 (JWT as authorization\ngrant) or § 2.2 (JWT as client authentication / private_key_jwt)."}}}} ``` ## The OcrRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OcrRequest":{"properties":{"image":{"type":"string","maxLength":10000000,"minLength":1,"title":"Image","description":"Base64-encoded image data"},"target_fields":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Target Fields","description":"Optional list of field keys to extract"}},"type":"object","required":["image"],"title":"OcrRequest"}}}} ``` ## The OcrResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OcrResponse":{"properties":{"extracted_fields":{"additionalProperties":true,"type":"object","title":"Extracted Fields"},"confidence":{"type":"number","maximum":1,"minimum":0,"title":"Confidence"}},"type":"object","required":["confidence"],"title":"OcrResponse","description":"Structured field extraction result for an uploaded image."}}}} ``` ## The OperatorIntelligenceSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorIntelligenceSummary":{"properties":{"escalated":{"type":"boolean","title":"Escalated","description":"Whether the call was escalated to a human operator","default":false},"operator_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Operator Active","description":"Whether an operator was active during escalation. True = active; False = escalation occurred but no operator picked up; None = no escalation occurred (do NOT coerce to False)."}},"type":"object","title":"OperatorIntelligenceSummary","description":"Operator intervention summary.\n\nThree-valued semantics on ``operator_active``:\n- ``True`` — escalation occurred and an operator was active.\n- ``False`` — escalation occurred but no operator picked up.\n- ``None`` — no escalation occurred (producer omits the key).\n Readers must distinguish; do not coerce ``None`` → ``False``."}}}} ``` ## The OperatorListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/OperatorResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"OperatorListResponse"},"OperatorResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Contact email"},"type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Type","description":"Operator specialization"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills","description":"Skill tags for routing"},"connection_method":{"type":"string","enum":["browser","phone"],"title":"Connection Method","description":"How the operator connects to calls"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"E.164 phone number for phone-based operators"},"role":{"type":"string","enum":["operator","supervisor","admin"],"title":"Role","description":"Permission role"},"status":{"type":"string","enum":["online","busy","offline"],"title":"Status","description":"Current availability"},"last_status_change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status Change","description":"ISO-8601 timestamp of last status transition"},"active_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Call Sid","description":"Call SID if currently on a call"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled","description":"Lifetime escalation count"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds","description":"Average escalation handle time in seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At","description":"ISO-8601 timestamp of last call"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the operator was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the operator was last updated"}},"type":"object","required":["id","workspace_id","skills","connection_method","role","status","total_escalations_handled","avg_handle_time_seconds"],"title":"OperatorResponse"}}}} ``` ## The OperatorPerformanceItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorPerformanceItem":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name"},"status":{"type":"string","enum":["online","busy","offline"],"title":"Status","description":"Current availability"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled","description":"Lifetime escalation count"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds","description":"Average handle time in seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At","description":"ISO-8601 timestamp of last call"}},"type":"object","required":["operator_id","status","total_escalations_handled","avg_handle_time_seconds"],"title":"OperatorPerformanceItem"}}}} ``` ## The OperatorPerformanceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorPerformanceResponse":{"properties":{"summary":{"$ref":"#/components/schemas/OperatorPerformanceSummary","description":"Aggregate operator performance metrics"},"trend":{"items":{"$ref":"#/components/schemas/OperatorPerformanceTrendPoint"},"type":"array","maxItems":2200,"title":"Trend","description":"Time series of escalation counts per interval bucket"}},"type":"object","required":["summary","trend"],"title":"OperatorPerformanceResponse","description":"Operator escalation performance and quality comparison over time."},"OperatorPerformanceSummary":{"properties":{"total_calls":{"type":"integer","title":"Total Calls","description":"Total number of calls in the period"},"escalated_count":{"type":"integer","title":"Escalated Count","description":"Number of calls escalated to an operator"},"escalation_rate":{"type":"number","title":"Escalation Rate","description":"Fraction of calls that were escalated (0.0-1.0)"},"operator_handled_count":{"type":"integer","title":"Operator Handled Count","description":"Number of calls where an operator was active"},"avg_escalated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Escalated Duration Seconds","description":"Average duration in seconds of escalated calls"},"avg_escalated_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Escalated Quality Score","description":"Average quality score of escalated calls"},"avg_non_escalated_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Non Escalated Quality Score","description":"Average quality score of non-escalated calls"}},"type":"object","required":["total_calls","escalated_count","escalation_rate","operator_handled_count"],"title":"OperatorPerformanceSummary","description":"Aggregate operator escalation stats for the period."},"OperatorPerformanceTrendPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date for the time bucket"},"total_calls":{"type":"integer","title":"Total Calls","description":"Total calls in this time bucket"},"escalated_count":{"type":"integer","title":"Escalated Count","description":"Escalated calls in this time bucket"}},"type":"object","required":["date","total_calls","escalated_count"],"title":"OperatorPerformanceTrendPoint","description":"Single time-bucket data point in the operator performance trend series."}}}} ``` ## The OperatorPerformanceSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorPerformanceSummary":{"properties":{"total_calls":{"type":"integer","title":"Total Calls","description":"Total number of calls in the period"},"escalated_count":{"type":"integer","title":"Escalated Count","description":"Number of calls escalated to an operator"},"escalation_rate":{"type":"number","title":"Escalation Rate","description":"Fraction of calls that were escalated (0.0-1.0)"},"operator_handled_count":{"type":"integer","title":"Operator Handled Count","description":"Number of calls where an operator was active"},"avg_escalated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Escalated Duration Seconds","description":"Average duration in seconds of escalated calls"},"avg_escalated_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Escalated Quality Score","description":"Average quality score of escalated calls"},"avg_non_escalated_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Non Escalated Quality Score","description":"Average quality score of non-escalated calls"}},"type":"object","required":["total_calls","escalated_count","escalation_rate","operator_handled_count"],"title":"OperatorPerformanceSummary","description":"Aggregate operator escalation stats for the period."}}}} ``` ## The OperatorPerformanceTrendPoint object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorPerformanceTrendPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date for the time bucket"},"total_calls":{"type":"integer","title":"Total Calls","description":"Total calls in this time bucket"},"escalated_count":{"type":"integer","title":"Escalated Count","description":"Escalated calls in this time bucket"}},"type":"object","required":["date","total_calls","escalated_count"],"title":"OperatorPerformanceTrendPoint","description":"Single time-bucket data point in the operator performance trend series."}}}} ``` ## The OperatorResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Contact email"},"type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Type","description":"Operator specialization"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills","description":"Skill tags for routing"},"connection_method":{"type":"string","enum":["browser","phone"],"title":"Connection Method","description":"How the operator connects to calls"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"E.164 phone number for phone-based operators"},"role":{"type":"string","enum":["operator","supervisor","admin"],"title":"Role","description":"Permission role"},"status":{"type":"string","enum":["online","busy","offline"],"title":"Status","description":"Current availability"},"last_status_change":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status Change","description":"ISO-8601 timestamp of last status transition"},"active_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Active Call Sid","description":"Call SID if currently on a call"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled","description":"Lifetime escalation count"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds","description":"Average escalation handle time in seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At","description":"ISO-8601 timestamp of last call"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the operator was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the operator was last updated"}},"type":"object","required":["id","workspace_id","skills","connection_method","role","status","total_escalations_handled","avg_handle_time_seconds"],"title":"OperatorResponse"}}}} ``` ## The OperatorStatusCounts object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorStatusCounts":{"properties":{"total":{"type":"integer","title":"Total"},"online":{"type":"integer","title":"Online"},"busy":{"type":"integer","title":"Busy"},"offline":{"type":"integer","title":"Offline"}},"type":"object","required":["total","online","busy","offline"],"title":"OperatorStatusCounts"}}}} ``` ## The OrderedPathway object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"}}}} ``` ## The OutboundLogItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutboundLogItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Synced At"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"attempt_count":{"type":"integer","title":"Attempt Count"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","event_id","attempt_count","created_at"],"title":"OutboundLogItem"}}}} ``` ## The OutboundLogListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutboundLogListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/OutboundLogItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"OutboundLogListResponse"},"OutboundLogItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Synced At"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"attempt_count":{"type":"integer","title":"Attempt Count"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","event_id","attempt_count","created_at"],"title":"OutboundLogItem"}}}} ``` ## The OutboundSinkSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutboundSinkSummary":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"data_source_name":{"type":"string","title":"Data Source Name"},"total":{"type":"integer","title":"Total"},"synced":{"type":"integer","title":"Synced"},"failed":{"type":"integer","title":"Failed"},"pending":{"type":"integer","title":"Pending"},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Synced At"}},"type":"object","required":["data_source_id","data_source_name","total","synced","failed","pending"],"title":"OutboundSinkSummary"}}}} ``` ## The OutboundSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutboundSummary":{"properties":{"total":{"type":"integer","title":"Total","default":0},"synced":{"type":"integer","title":"Synced","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Synced At"}},"type":"object","title":"OutboundSummary"}}}} ``` ## The OutreachRule object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutreachRule":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"trigger":{"type":"string","enum":["appointment_window","post_visit","gap_detected","form_intake","manual"],"title":"Trigger","default":"appointment_window"},"trigger_config":{"additionalProperties":true,"type":"object","title":"Trigger Config","description":"Trigger-specific config (hours_before, hours_after, etc.)"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"consent_required":{"type":"boolean","title":"Consent Required","default":true},"quiet_hours":{"$ref":"#/components/schemas/QuietHours"},"review_required":{"type":"boolean","title":"Review Required","default":false},"message_template":{"type":"string","maxLength":1600,"title":"Message Template","default":"Hi {first_name}, please complete your form: {surface_url}"},"data_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Template Id"},"form_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Form Template Id"},"active":{"type":"boolean","title":"Active","default":true}},"type":"object","required":["name"],"title":"OutreachRule","description":"A single outreach rule — defines WHEN, WHAT, and HOW to reach a patient."},"NameString":{"type":"string","maxLength":256,"minLength":1},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"QuietHours":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":false},"start_hour":{"type":"integer","maximum":23,"minimum":0,"title":"Start Hour","default":21},"end_hour":{"type":"integer","maximum":23,"minimum":0,"title":"End Hour","default":8},"timezone":{"type":"string","maxLength":64,"title":"Timezone","default":"America/New_York"}},"type":"object","title":"QuietHours","description":"Quiet hours — no outbound outreach during this window."}}}} ``` ## The OutreachSettingsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutreachSettingsRequest":{"properties":{"rules":{"anyOf":[{"items":{"$ref":"#/components/schemas/OutreachRule"},"type":"array"},{"type":"null"}],"title":"Rules"},"data_templates":{"anyOf":[{"items":{"$ref":"#/components/schemas/DataTemplate-Input"},"type":"array"},{"type":"null"}],"title":"Data Templates"}},"type":"object","title":"OutreachSettingsRequest","description":"Partial update — only provided fields are changed.\n\nRules and data_templates lists are replaced entirely when provided."},"OutreachRule":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"trigger":{"type":"string","enum":["appointment_window","post_visit","gap_detected","form_intake","manual"],"title":"Trigger","default":"appointment_window"},"trigger_config":{"additionalProperties":true,"type":"object","title":"Trigger Config","description":"Trigger-specific config (hours_before, hours_after, etc.)"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"consent_required":{"type":"boolean","title":"Consent Required","default":true},"quiet_hours":{"$ref":"#/components/schemas/QuietHours"},"review_required":{"type":"boolean","title":"Review Required","default":false},"message_template":{"type":"string","maxLength":1600,"title":"Message Template","default":"Hi {first_name}, please complete your form: {surface_url}"},"data_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Template Id"},"form_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Form Template Id"},"active":{"type":"boolean","title":"Active","default":true}},"type":"object","required":["name"],"title":"OutreachRule","description":"A single outreach rule — defines WHEN, WHAT, and HOW to reach a patient."},"NameString":{"type":"string","maxLength":256,"minLength":1},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"QuietHours":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":false},"start_hour":{"type":"integer","maximum":23,"minimum":0,"title":"Start Hour","default":21},"end_hour":{"type":"integer","maximum":23,"minimum":0,"title":"End Hour","default":8},"timezone":{"type":"string","maxLength":64,"title":"Timezone","default":"America/New_York"}},"type":"object","title":"QuietHours","description":"Quiet hours — no outbound outreach during this window."},"DataTemplate-Input":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"fields":{"items":{"$ref":"#/components/schemas/DataTemplateField"},"type":"array","maxItems":50,"minItems":1,"title":"Fields"}},"type":"object","required":["name","fields"],"title":"DataTemplate","description":"Named field template — reusable across multiple outreach rules."},"DataTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state (e.g. demographics.date_of_birth)"}},"type":"object","required":["key","label","path"],"title":"DataTemplateField","description":"A field in a data template — maps to entity state path for gap detection."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The OutreachSettingsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OutreachSettingsResponse":{"properties":{"rules":{"items":{"$ref":"#/components/schemas/OutreachRule"},"type":"array","title":"Rules"},"data_templates":{"items":{"$ref":"#/components/schemas/DataTemplate-Output"},"type":"array","title":"Data Templates"}},"type":"object","required":["rules","data_templates"],"title":"OutreachSettingsResponse"},"OutreachRule":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"trigger":{"type":"string","enum":["appointment_window","post_visit","gap_detected","form_intake","manual"],"title":"Trigger","default":"appointment_window"},"trigger_config":{"additionalProperties":true,"type":"object","title":"Trigger Config","description":"Trigger-specific config (hours_before, hours_after, etc.)"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"email"},"consent_required":{"type":"boolean","title":"Consent Required","default":true},"quiet_hours":{"$ref":"#/components/schemas/QuietHours"},"review_required":{"type":"boolean","title":"Review Required","default":false},"message_template":{"type":"string","maxLength":1600,"title":"Message Template","default":"Hi {first_name}, please complete your form: {surface_url}"},"data_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Template Id"},"form_template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Form Template Id"},"active":{"type":"boolean","title":"Active","default":true}},"type":"object","required":["name"],"title":"OutreachRule","description":"A single outreach rule — defines WHEN, WHAT, and HOW to reach a patient."},"NameString":{"type":"string","maxLength":256,"minLength":1},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"QuietHours":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":false},"start_hour":{"type":"integer","maximum":23,"minimum":0,"title":"Start Hour","default":21},"end_hour":{"type":"integer","maximum":23,"minimum":0,"title":"End Hour","default":8},"timezone":{"type":"string","maxLength":64,"title":"Timezone","default":"America/New_York"}},"type":"object","title":"QuietHours","description":"Quiet hours — no outbound outreach during this window."},"DataTemplate-Output":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"$ref":"#/components/schemas/NameString"},"fields":{"items":{"$ref":"#/components/schemas/DataTemplateField"},"type":"array","maxItems":50,"minItems":1,"title":"Fields"}},"type":"object","required":["name","fields"],"title":"DataTemplate","description":"Named field template — reusable across multiple outreach rules."},"DataTemplateField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType","default":"text"},"required":{"type":"boolean","title":"Required","default":true},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"path":{"type":"string","maxLength":256,"minLength":1,"title":"Path","description":"Dot-notation path into entity state (e.g. demographics.date_of_birth)"}},"type":"object","required":["key","label","path"],"title":"DataTemplateField","description":"A field in a data template — maps to entity state path for gap detection."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."}}}} ``` ## The PaginatedResponse\_BatchRow\_ object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PaginatedResponse_BatchRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BatchRow"},"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[BatchRow]"},"BatchRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"batch_id."},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"type":"string","title":"Status","description":"discovered | ready | processing | completed | failed."},"files_found":{"type":"integer","title":"Files Found"},"created_ts":{"type":"string","title":"Created Ts"}},"type":"object","required":["id","dataset","status","files_found","created_ts"],"title":"BatchRow","description":"A source-sync batch (Batches list / detail)."}}}} ``` ## The PaginatedResponse\_DatasetRow\_ object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PaginatedResponse_DatasetRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DatasetRow"},"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[DatasetRow]"},"DatasetRow":{"properties":{"name":{"type":"string","title":"Name","description":"Dataset slug (UI label \"Schema\")."},"schema_version":{"type":"string","title":"Schema Version"},"field_count":{"type":"integer","title":"Field Count"},"file_type":{"type":"string","title":"File Type","description":"Primary/representative file type (the first accepted type)."},"accepted_file_types":{"items":{"type":"string"},"type":"array","title":"Accepted File Types","description":"Document datasets: the full accepted-type set (V265). Empty for snapshot\nor legacy single-type documents (the UI falls back to ``file_type``).","default":[]},"ingestion_mode":{"type":"string","title":"Ingestion Mode","description":"`snapshot` (CSV/Excel → CDC) or `document` (PDF/docx → extraction)."},"limits":{"$ref":"#/components/schemas/Limits"}},"type":"object","required":["name","schema_version","field_count","file_type","ingestion_mode","limits"],"title":"DatasetRow","description":"A registered schema in the Schemas list (intake-ui-mvp-design.md §5.3)."},"Limits":{"properties":{"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","title":"Limits"}}}} ``` ## The PaginatedResponse\_IntakeFileRow\_ object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PaginatedResponse_IntakeFileRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IntakeFileRow"},"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[IntakeFileRow]"},"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]}}}} ``` ## The PaginatedResponse\_IntakeSourceRow\_ object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PaginatedResponse_IntakeSourceRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IntakeSourceRow"},"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[IntakeSourceRow]"},"IntakeSourceRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"source_id."},"source_type":{"type":"string","title":"Source Type"},"display_name":{"type":"string","title":"Display Name"},"drive_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Id"},"folders":{"items":{"$ref":"#/components/schemas/DriveFolderMapping"},"type":"array","title":"Folders"},"impersonate_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impersonate Subject","description":"DWD impersonation subject, if this source authenticates via domain-wide delegation."},"status":{"type":"string","title":"Status"},"created_ts":{"type":"string","title":"Created Ts","description":"ISO-8601 timestamp."}},"type":"object","required":["id","source_type","display_name","folders","status","created_ts"],"title":"IntakeSourceRow","description":"A registered intake source (Sources list)."},"DriveFolderMapping":{"properties":{"folder_id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Folder Id"},"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"contains_phi":{"type":"boolean","title":"Contains Phi","default":true}},"type":"object","required":["folder_id","dataset"],"title":"DriveFolderMapping","description":"One Google Drive folder ↔ one intake dataset.\n\n``folder_id`` is the Drive folder id (the identity — never the folder name,\nwhich can be renamed/moved). One folder maps to exactly one dataset."}}}} ``` ## The PaginatedResponse\_MaterializationRow\_ object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PaginatedResponse_MaterializationRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/MaterializationRow"},"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[MaterializationRow]"},"MaterializationRow":{"properties":{"dataset":{"type":"string","title":"Dataset"},"ingestion_mode":{"type":"string","title":"Ingestion Mode"},"status":{"type":"string","enum":["materialized","not_materialized"],"title":"Status"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count"},"last_materialized_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Materialized At"}},"type":"object","required":["dataset","ingestion_mode","status"],"title":"MaterializationRow","description":"Per-dataset status of the customer-data destination table\n(``customer_data_..``)."}}}} ``` ## The PanelResultResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PanelResultResponse":{"properties":{"panel_id":{"type":"string","title":"Panel Id","description":"Panel identifier from the definition"},"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names"},"rows":{"items":{"items":{},"type":"array"},"type":"array","title":"Rows","description":"Result rows"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if query failed"}},"type":"object","required":["panel_id","columns","rows"],"title":"PanelResultResponse"}}}} ``` ## The ParamValueDict object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}}} ``` ## The ParamValueRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ParamValueRequest":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueRequest","description":"Routing target for a single per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthRequest.param_headers`` / ``param_body_fields``."}}}} ``` ## The Participant object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Participant":{"properties":{"participant_id":{"type":"string","title":"Participant Id"},"role":{"type":"string","enum":["caller","agent","operator"],"title":"Role"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"joined_at":{"type":"string","format":"date-time","title":"Joined At"},"left_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Left At"}},"type":"object","required":["participant_id","role","joined_at"],"title":"Participant"}}}} ``` ## The PatientLabRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientLabRow":{"properties":{"patient_id":{"type":"string","title":"Patient Id"},"observation_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observation Date"},"test_name":{"type":"string","title":"Test Name"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"units":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Units"},"loinc_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Loinc Code"}},"type":"object","required":["patient_id","test_name"],"title":"PatientLabRow"}}}} ``` ## The PatientLabsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientLabsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/PatientLabRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"PatientLabsResponse"},"PatientLabRow":{"properties":{"patient_id":{"type":"string","title":"Patient Id"},"observation_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observation Date"},"test_name":{"type":"string","title":"Test Name"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"units":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Units"},"loinc_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Loinc Code"}},"type":"object","required":["patient_id","test_name"],"title":"PatientLabRow"}}}} ``` ## The PatientListItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientListItem":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Patient name"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Primary phone number"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Primary email address"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn","description":"Medical record number"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"PatientListItem","description":"Typed patient list item — replaces untyped dict."}}}} ``` ## The PatientNoteExtractions object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientNoteExtractions":{"properties":{"symptoms":{"items":{"type":"string"},"type":"array","title":"Symptoms"},"concerns":{"items":{"type":"string"},"type":"array","title":"Concerns"},"medications_planned":{"items":{"type":"string"},"type":"array","title":"Medications Planned"},"hba1c_sentiment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hba1C Sentiment"},"activity_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Activity Level"},"smoking_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Smoking Status"},"food_pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Food Pattern"},"n_symptoms":{"type":"integer","title":"N Symptoms","default":0},"n_concerns":{"type":"integer","title":"N Concerns","default":0}},"type":"object","required":["symptoms","concerns","medications_planned"],"title":"PatientNoteExtractions"}}}} ``` ## The PatientNoteResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientNoteResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"patient_id":{"type":"string","title":"Patient Id"},"authored_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Authored At"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"note_text":{"type":"string","title":"Note Text"},"extractions":{"$ref":"#/components/schemas/PatientNoteExtractions"}},"type":"object","required":["workspace_id","patient_id","note_text","extractions"],"title":"PatientNoteResponse"},"PatientNoteExtractions":{"properties":{"symptoms":{"items":{"type":"string"},"type":"array","title":"Symptoms"},"concerns":{"items":{"type":"string"},"type":"array","title":"Concerns"},"medications_planned":{"items":{"type":"string"},"type":"array","title":"Medications Planned"},"hba1c_sentiment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hba1C Sentiment"},"activity_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Activity Level"},"smoking_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Smoking Status"},"food_pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Food Pattern"},"n_symptoms":{"type":"integer","title":"N Symptoms","default":0},"n_concerns":{"type":"integer","title":"N Concerns","default":0}},"type":"object","required":["symptoms","concerns","medications_planned"],"title":"PatientNoteExtractions"}}}} ``` ## The PatientSearchResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientSearchResponse":{"properties":{"patients":{"items":{"$ref":"#/components/schemas/PatientListItem"},"type":"array","title":"Patients"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset"}},"type":"object","required":["patients","total"],"title":"PatientSearchResponse"},"PatientListItem":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Patient name"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Primary phone number"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Primary email address"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn","description":"Medical record number"},"event_count":{"type":"integer","title":"Event Count","default":0},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event At"}},"type":"object","required":["entity_id"],"title":"PatientListItem","description":"Typed patient list item — replaces untyped dict."}}}} ``` ## The PatientSummaryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientSummaryResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"entity_type":{"type":"string","title":"Entity Type"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"state":{"additionalProperties":true,"type":"object","title":"State","description":"Full JSONB state blob. Prefer typed fields below.","deprecated":true},"event_count":{"type":"integer","title":"Event Count"},"last_event_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Event At"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Patient name"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Primary phone number (E.164)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Primary email address"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date","description":"Date of birth (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Gender"},"mrn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrn","description":"Medical record number"}},"type":"object","required":["entity_id","entity_type","display_name","event_count","last_event_at"],"title":"PatientSummaryResponse"}}}} ``` ## The PatientSurfaceSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientSurfaceSpec":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Description"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields"},"sections":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Sections"},"branding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Branding"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"completion_title":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Context"}},"type":"object","title":"PatientSurfaceSpec","description":"Patient-facing surface spec — what forms-app renders.\n\nFree-form by design: ``fields``/``sections``/``branding`` are forwarded\nfrom the upstream surface document as raw dicts. Renamed from\n``SurfaceSpec`` to avoid an OpenAPI schema-name collision with\n``platform_lib.surfaces.models.SurfaceSpec`` (which would otherwise\nforce FastAPI to namespace both classes and rename the existing\n``SurfaceSpec`` schema in the committed openapi.json)."}}}} ``` ## The PatientTimelineResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientTimelineResponse":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["entity_id","events","total"],"title":"PatientTimelineResponse"}}}} ``` ## The PatientTopologyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientTopologyResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/PatientTopologyRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"PatientTopologyResponse"},"PatientTopologyRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"patient_id":{"type":"string","title":"Patient Id"},"umap_x":{"type":"number","title":"Umap X"},"umap_y":{"type":"number","title":"Umap Y"},"pca_x":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pca X"},"pca_y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pca Y"},"pca_z":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pca Z"},"cluster_name":{"type":"string","title":"Cluster Name"},"age_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age Bucket"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nationality"},"district":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"District"},"charlson_cci":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Charlson Cci"},"bmi_latest":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bmi Latest"},"hba1c_latest":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Hba1C Latest"},"risk_tier":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Risk Tier"},"y_hat_t2d_1yr":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat T2D 1Yr"},"y_hat_htn_1yr":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Htn 1Yr"},"y_hat_chf_90d":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Chf 90D"},"y_hat_asthma_12mo":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Asthma 12Mo"},"y_hat_ckd_1yr":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Ckd 1Yr"},"y_hat_copd_12mo":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Copd 12Mo"},"y_hat_composite":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Composite"},"emergence_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Emergence Month"}},"type":"object","required":["workspace_id","patient_id","umap_x","umap_y","cluster_name"],"title":"PatientTopologyRow"}}}} ``` ## The PatientTopologyRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PatientTopologyRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"patient_id":{"type":"string","title":"Patient Id"},"umap_x":{"type":"number","title":"Umap X"},"umap_y":{"type":"number","title":"Umap Y"},"pca_x":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pca X"},"pca_y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pca Y"},"pca_z":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pca Z"},"cluster_name":{"type":"string","title":"Cluster Name"},"age_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Age Bucket"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nationality"},"district":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"District"},"charlson_cci":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Charlson Cci"},"bmi_latest":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Bmi Latest"},"hba1c_latest":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Hba1C Latest"},"risk_tier":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Risk Tier"},"y_hat_t2d_1yr":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat T2D 1Yr"},"y_hat_htn_1yr":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Htn 1Yr"},"y_hat_chf_90d":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Chf 90D"},"y_hat_asthma_12mo":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Asthma 12Mo"},"y_hat_ckd_1yr":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Ckd 1Yr"},"y_hat_copd_12mo":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Copd 12Mo"},"y_hat_composite":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Y Hat Composite"},"emergence_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Emergence Month"}},"type":"object","required":["workspace_id","patient_id","umap_x","umap_y","cluster_name"],"title":"PatientTopologyRow"}}}} ``` ## The PerformanceSummaryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PerformanceSummaryResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"total_operators":{"type":"integer","title":"Total Operators"},"online":{"type":"integer","title":"Online"},"busy":{"type":"integer","title":"Busy"},"offline":{"type":"integer","title":"Offline"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds"},"operators":{"items":{"$ref":"#/components/schemas/OperatorPerformanceItem"},"type":"array","title":"Operators"}},"type":"object","required":["workspace_id","total_operators","online","busy","offline","total_escalations_handled","avg_handle_time_seconds","operators"],"title":"PerformanceSummaryResponse"},"OperatorPerformanceItem":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name"},"status":{"type":"string","enum":["online","busy","offline"],"title":"Status","description":"Current availability"},"total_escalations_handled":{"type":"integer","title":"Total Escalations Handled","description":"Lifetime escalation count"},"avg_handle_time_seconds":{"type":"number","title":"Avg Handle Time Seconds","description":"Average handle time in seconds"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At","description":"ISO-8601 timestamp of last call"}},"type":"object","required":["operator_id","status","total_escalations_handled","avg_handle_time_seconds"],"title":"OperatorPerformanceItem"}}}} ``` ## The Period object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."}}}} ``` ## The PermissionCatalogResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PermissionCatalogResponse":{"properties":{"roles":{"items":{"$ref":"#/components/schemas/RoleEntry"},"type":"array","title":"Roles"},"permissions":{"items":{"$ref":"#/components/schemas/PermissionEntry"},"type":"array","title":"Permissions"}},"type":"object","required":["roles","permissions"],"title":"PermissionCatalogResponse","description":"The authoritative role→permission model for API-key creation.\n\nServes the server-side source of truth (``DEFAULT_ROLE_DEFINITIONS``) so\nclients (console, SDK) stop hand-copying the matrix and drifting out of\nsync — a drift previously shipped `Data:Query` as a viewer default and\nmade the default create flow 422. Human-facing labels/descriptions for\nindividual permissions stay client-side (pure presentation); this payload\nis authorization truth only."},"RoleEntry":{"properties":{"name":{"type":"string","title":"Name"},"priority":{"type":"integer","title":"Priority"},"description":{"type":"string","title":"Description"},"permission_names":{"items":{"type":"string"},"type":"array","title":"Permission Names"}},"type":"object","required":["name","priority","description","permission_names"],"title":"RoleEntry"},"PermissionEntry":{"properties":{"name":{"type":"string","title":"Name"},"namespace":{"type":"string","title":"Namespace"},"action":{"type":"string","title":"Action"}},"type":"object","required":["name","namespace","action"],"title":"PermissionEntry"}}}} ``` ## The PermissionEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PermissionEntry":{"properties":{"name":{"type":"string","title":"Name"},"namespace":{"type":"string","title":"Namespace"},"action":{"type":"string","title":"Action"}},"type":"object","required":["name","namespace","action"],"title":"PermissionEntry"}}}} ``` ## The PhoneE164 object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PhoneE164":{"type":"string","maxLength":16,"minLength":2}}}} ``` ## The PhoneNumberCallVolume object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PhoneNumberCallVolume":{"properties":{"phone_number":{"type":"string","title":"Phone Number","description":"E.164 phone number"},"total_calls":{"type":"integer","title":"Total Calls","description":"Total calls across the period"},"inbound":{"type":"integer","title":"Inbound","description":"Inbound call count"},"outbound":{"type":"integer","title":"Outbound","description":"Outbound call count"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average call duration"},"by_date":{"items":{"$ref":"#/components/schemas/DailyCallVolume"},"type":"array","title":"By Date","description":"Daily volume breakdown"}},"type":"object","required":["phone_number","total_calls","inbound","outbound"],"title":"PhoneNumberCallVolume"},"DailyCallVolume":{"properties":{"date":{"type":"string","title":"Date","description":"ISO-8601 date (YYYY-MM-DD)"},"count":{"type":"integer","title":"Count","description":"Number of calls on this date"}},"type":"object","required":["date","count"],"title":"DailyCallVolume","description":"Call volume for a single date."}}}} ``` ## The PipelineMetrics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PipelineMetrics":{"properties":{"sources_total":{"type":"integer","title":"Sources Total","default":0},"sources_healthy":{"type":"integer","title":"Sources Healthy","default":0},"sources_degraded":{"type":"integer","title":"Sources Degraded","default":0},"sources_failing":{"type":"integer","title":"Sources Failing","default":0},"events_last_hour":{"type":"integer","title":"Events Last Hour","default":0},"outbound_pending":{"type":"integer","title":"Outbound Pending","default":0},"outbound_failed":{"type":"integer","title":"Outbound Failed","default":0},"connector_status":{"type":"string","enum":["healthy","degraded","unavailable"],"title":"Connector Status","default":"unavailable"}},"type":"object","title":"PipelineMetrics"}}}} ``` ## The PipelineStatusResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PipelineStatusResponse":{"properties":{"status":{"type":"string","title":"Status"},"connector_runner_status":{"type":"string","title":"Connector Runner Status"},"uptime_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Uptime Seconds"},"active_polls":{"type":"integer","title":"Active Polls","default":0},"total_events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Events","description":"Read-model event count for the last 7 days. Null means the read model is empty or unavailable; zero means the read model is ready and has no events."},"event_read_model_status":{"type":"string","enum":["ready","empty","unavailable"],"title":"Event Read Model Status","default":"empty"},"event_read_model_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Event Read Model Synced At"},"total_entities":{"type":"integer","title":"Total Entities","default":0},"sources":{"items":{"$ref":"#/components/schemas/SourceStatus"},"type":"array","title":"Sources","default":[]},"entity_resolution":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Entity Resolution"},"review_loop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Review Loop"},"outbound_dispatch":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Outbound Dispatch"},"outbound_subscriber":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Outbound Subscriber"},"reconciliation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reconciliation"},"gap_scanner":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Gap Scanner"}},"type":"object","required":["status","connector_runner_status"],"title":"PipelineStatusResponse"},"SourceStatus":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"status":{"type":"string","title":"Status"},"last_poll_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Poll At"},"last_poll_duration_ms":{"type":"integer","title":"Last Poll Duration Ms","default":0},"last_poll_event_count":{"type":"integer","title":"Last Poll Event Count","default":0},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"consecutive_errors":{"type":"integer","title":"Consecutive Errors","default":0},"connection_healthy":{"type":"boolean","title":"Connection Healthy","default":true}},"type":"object","required":["data_source_id","workspace_id","source_type","status"],"title":"SourceStatus"}}}} ``` ## The PlaybackTimeline object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PlaybackTimeline":{"properties":{"turns":{"items":{"$ref":"#/components/schemas/TurnTimeline"},"type":"array","title":"Turns"},"segments":{"items":{"$ref":"#/components/schemas/TimelineSegment"},"type":"array","title":"Segments"},"duration_seconds":{"type":"number","title":"Duration Seconds"},"timebase":{"anyOf":[{"$ref":"#/components/schemas/TimelineTimebase"},{"type":"null"}],"description":"Canonical timebase shared by waveform, overlays, seek state, zoom, and scroll transforms."},"lanes":{"items":{"$ref":"#/components/schemas/TimelineLaneDefinition"},"type":"array","title":"Lanes","description":"Canonical actor/system lane model. Every segment lane_id resolves against this collection.","default":[]},"total_user_speech_seconds":{"type":"number","title":"Total User Speech Seconds","default":0},"total_agent_speech_seconds":{"type":"number","title":"Total Agent Speech Seconds","default":0},"total_silence_seconds":{"type":"number","title":"Total Silence Seconds","default":0},"avg_processing_gap_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Processing Gap Ms"},"max_processing_gap_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Processing Gap Ms"},"avg_perceived_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Perceived Latency Ms"}},"type":"object","required":["turns","segments","duration_seconds"],"title":"PlaybackTimeline"},"TurnTimeline":{"properties":{"turn_index":{"type":"integer","title":"Turn Index"},"seek_to":{"type":"number","title":"Seek To"},"active_start":{"type":"number","title":"Active Start"},"active_end":{"type":"number","title":"Active End"}},"type":"object","required":["turn_index","seek_to","active_start","active_end"],"title":"TurnTimeline"},"TimelineSegment":{"properties":{"type":{"type":"string","enum":["agent_speech","barge_in","caller_speech","filler_hesitation","filler_nav","greeting","interrupted_speech","processing_gap","silence","silence_check","state_transition","tool_call"],"title":"Type"},"lane":{"type":"string","enum":["agent","caller","events","operator","system","tool"],"title":"Lane"},"track":{"anyOf":[{"type":"string","enum":["agent","caller","operator","system","tool"]},{"type":"null"}],"title":"Track","description":"Actor-semantic display track for the segment. Inferred for legacy producers."},"lane_id":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Lane Id","description":"Canonical lane id. Must match PlaybackTimeline.lanes[].id after platform normalization."},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order","description":"Canonical event order after platform time/lane normalization."},"actor":{"anyOf":[{"$ref":"#/components/schemas/TimelineActor"},{"type":"null"}],"description":"Actor responsible for the segment. Inferred for legacy producers."},"start":{"type":"number","title":"Start"},"end":{"type":"number","title":"End"},"label":{"type":"string","title":"Label"},"turn_index":{"type":"integer","title":"Turn Index"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eot Confidence"},"audio_window_start":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window Start"},"audio_window_end":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window End"},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Render Ms"},"audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Ttfb Ms"},"e2e_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"E2E Ttfb Ms"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"parent_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Call Id"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name"},"endpoint_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Name"},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"},"succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Succeeded"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"from_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From State"},"to_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To State"},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valence"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"type":"object","required":["type","lane","start","end","label","turn_index"],"title":"TimelineSegment"},"TimelineActor":{"properties":{"kind":{"type":"string","enum":["agent","human","operator","system","tool"],"title":"Kind"},"role":{"type":"string","enum":["agent","caller","operator","runtime","state","tool"],"title":"Role"},"label":{"type":"string","title":"Label"},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Id"}},"type":"object","required":["kind","role","label"],"title":"TimelineActor"},"TimelineTimebase":{"properties":{"unit":{"type":"string","const":"seconds","title":"Unit","description":"Timeline offsets are always seconds.","default":"seconds"},"origin":{"type":"string","enum":["media_start","call_start","synthetic"],"title":"Origin","description":"Zero point used for segment start/end offsets.","default":"media_start"},"start":{"type":"number","title":"Start","description":"Visible/canonical timeline range start in seconds.","default":0},"end":{"type":"number","title":"End","description":"Visible/canonical timeline range end in seconds.","default":0}},"type":"object","title":"TimelineTimebase"},"TimelineLaneDefinition":{"properties":{"id":{"type":"string","maxLength":160,"minLength":1,"title":"Id","description":"Stable canonical lane id used by timeline visualizations. Segments attach via TimelineSegment.lane_id; consumers should not re-infer lanes from CSS or pixel positions."},"track":{"type":"string","enum":["agent","caller","operator","system","tool"],"title":"Track","description":"High-level actor-semantic track for styling and grouping."},"label":{"type":"string","title":"Label","description":"Display label for the lane."},"order":{"type":"integer","title":"Order","description":"Stable vertical order within the timeline lane model."},"actor":{"anyOf":[{"$ref":"#/components/schemas/TimelineActor"},{"type":"null"}],"description":"Actor represented by this lane when applicable."}},"type":"object","required":["id","track","label","order"],"title":"TimelineLaneDefinition"}}}} ``` ## The PreloadSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."}}}} ``` ## The PriorityQueueItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PriorityQueueItem":{"properties":{"call_sid":{"type":"string","title":"Call Sid","description":"Twilio call SID"},"caller_id":{"type":"string","title":"Caller Id","description":"Caller phone number","default":""},"caller_phone":{"anyOf":[{"type":"string","maxLength":16,"pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"title":"Caller Phone","description":"Caller E.164 phone number for console clients"},"service_id":{"type":"string","title":"Service Id","description":"Service ID handling the call","default":""},"service_name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Human-readable service name when available"},"direction":{"type":"string","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","description":"Call direction","default":"inbound"},"data_quality_flags":{"items":{"type":"string","const":"invalid_direction"},"type":"array","title":"Data Quality Flags","default":[]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the active call started"},"priority_score":{"type":"number","maximum":1,"minimum":0,"title":"Priority Score","description":"Priority score normalized to 0.0-1.0"},"priority_reasons":{"items":{"type":"string","enum":["high_risk","long_wait","negative_emotion","safety_concern","looping"]},"type":"array","title":"Priority Reasons","default":[]},"wait_seconds":{"type":"number","title":"Wait Seconds","default":0},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"risk_level":{"anyOf":[{"type":"string","enum":["low","medium","high","critical"]},{"type":"null"}],"title":"Risk Level"},"current_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Emotion"},"current_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Valence"},"current_state":{"type":"string","title":"Current State","default":""},"turn_count":{"type":"integer","title":"Turn Count","default":0},"escalation_active":{"type":"boolean","title":"Escalation Active","default":false},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"brief_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Context"}},"type":"object","required":["call_sid","priority_score"],"title":"PriorityQueueItem","description":"An active call ranked by operator priority."},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The PriorityQueueResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PriorityQueueResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"queue":{"items":{"$ref":"#/components/schemas/PriorityQueueItem"},"type":"array","title":"Queue"},"total_active":{"type":"integer","title":"Total Active"}},"type":"object","required":["workspace_id","queue","total_active"],"title":"PriorityQueueResponse"},"PriorityQueueItem":{"properties":{"call_sid":{"type":"string","title":"Call Sid","description":"Twilio call SID"},"caller_id":{"type":"string","title":"Caller Id","description":"Caller phone number","default":""},"caller_phone":{"anyOf":[{"type":"string","maxLength":16,"pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"title":"Caller Phone","description":"Caller E.164 phone number for console clients"},"service_id":{"type":"string","title":"Service Id","description":"Service ID handling the call","default":""},"service_name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}],"description":"Human-readable service name when available"},"direction":{"type":"string","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","description":"Call direction","default":"inbound"},"data_quality_flags":{"items":{"type":"string","const":"invalid_direction"},"type":"array","title":"Data Quality Flags","default":[]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the active call started"},"priority_score":{"type":"number","maximum":1,"minimum":0,"title":"Priority Score","description":"Priority score normalized to 0.0-1.0"},"priority_reasons":{"items":{"type":"string","enum":["high_risk","long_wait","negative_emotion","safety_concern","looping"]},"type":"array","title":"Priority Reasons","default":[]},"wait_seconds":{"type":"number","title":"Wait Seconds","default":0},"risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Risk Score"},"risk_level":{"anyOf":[{"type":"string","enum":["low","medium","high","critical"]},{"type":"null"}],"title":"Risk Level"},"current_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Emotion"},"current_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Valence"},"current_state":{"type":"string","title":"Current State","default":""},"turn_count":{"type":"integer","title":"Turn Count","default":0},"escalation_active":{"type":"boolean","title":"Escalation Active","default":false},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"brief_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Context"}},"type":"object","required":["call_sid","priority_score"],"title":"PriorityQueueItem","description":"An active call ranked by operator priority."},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ProductionEvalDefinition object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ProductionEvalDefinition":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"expected":{"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"active":{"type":"boolean","title":"Active","default":true},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["workspace_id","eval_key","eval_type"],"title":"ProductionEvalDefinition","description":"An eval (assertion or metric-eval) that runs against a workspace's live\ncalls — the production analogue of a sim case's ``evals``. ``service_id``\nNone applies to every service in the workspace. ``expected`` is JSON: a\nphrase string for assertions, or a ``{gte|lte|equals|...}`` threshold for\nmetric-evals."}}}} ``` ## The ProductionEvalDefinitionListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ProductionEvalDefinitionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ProductionEvalDefinition"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ProductionEvalDefinitionListResponse"},"ProductionEvalDefinition":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"expected":{"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"active":{"type":"boolean","title":"Active","default":true},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["workspace_id","eval_key","eval_type"],"title":"ProductionEvalDefinition","description":"An eval (assertion or metric-eval) that runs against a workspace's live\ncalls — the production analogue of a sim case's ``evals``. ``service_id``\nNone applies to every service in the workspace. ``expected`` is JSON: a\nphrase string for assertions, or a ``{gte|lte|equals|...}`` threshold for\nmetric-evals."}}}} ``` ## The ProductionEvalType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ProductionEvalType":{"type":"string","enum":["metric"],"title":"ProductionEvalType"}}}} ``` ## The ProgressHint object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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."}}}} ``` ## The PromoteSessionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PromoteSessionResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"The coverage run the session is now bound to"},"session_id":{"type":"string","title":"Session Id","description":"The promoted session id (unchanged)"},"already_bound":{"type":"boolean","title":"Already Bound","description":"True when the session was already run-scoped; the existing run is returned unchanged"}},"type":"object","required":["run_id","session_id","already_bound"],"title":"PromoteSessionResponse","description":"Result of binding a run-less session to a (newly created) coverage run."}}}} ``` ## The PromptLogEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PromptLogEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"prompt_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Type"},"turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Index"},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt"},"history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"History"},"full_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Prompt"},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model"},"llm_response":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Response"},"state_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Name"},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action"},"tool_names":{"items":{"type":"string"},"type":"array","title":"Tool Names"},"has_tools":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Tools"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"data_parse_error":{"type":"boolean","title":"Data Parse Error","default":false}},"type":"object","required":["event_id","workspace_id"],"title":"PromptLogEntry","description":"One ``prompt_log`` event projection — full LLM input + output for a turn.\n\nUnbounded string fields (``system_prompt``, ``full_prompt``,\n``llm_response``) reflect the producer's payload as-is — typically\n1-50 KB each, occasionally larger for long histories. SDK consumers\nshould not assume a max length."}}}} ``` ## The PromptLogListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PromptLogListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/PromptLogEntry"},"type":"array","title":"Items"},"count":{"type":"integer","minimum":0,"title":"Count"},"has_more":{"type":"boolean","title":"Has More"},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Offset","description":"Pass back as offset to fetch the next page; null when has_more is false"},"applied_time_window_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Applied Time Window Days","description":"Auto-applied time bound (in days) when no call_sid/from_ts/to_ts was passed. Null when the caller supplied an explicit selectivity-bearing filter."},"resolved_call_sid":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Resolved Call Sid","description":"When ``conversation_id`` was supplied, this is the underlying ``call_sid`` that the lookup resolved to. Useful for callers that want to drill into per-call surfaces afterward without re-querying ``world.entities_synced``. Null when the caller filtered by ``call_sid`` directly or did not filter by conversation."},"resolved_conversation_kind":{"anyOf":[{"type":"string","enum":["call","conversation"]},{"type":"null"}],"title":"Resolved Conversation Kind","description":"``entity_type`` of the conversation entity when ``conversation_id`` was supplied (``call`` for voice/sim, ``conversation`` for text/sms/whatsapp/email). Null otherwise."}},"type":"object","required":["items","count","has_more"],"title":"PromptLogListResponse"},"PromptLogEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"effective_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective At"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"prompt_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Type"},"turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Index"},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt"},"history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"History"},"full_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Prompt"},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model"},"llm_response":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Response"},"state_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Name"},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action"},"tool_names":{"items":{"type":"string"},"type":"array","title":"Tool Names"},"has_tools":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Tools"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"data_parse_error":{"type":"boolean","title":"Data Parse Error","default":false}},"type":"object","required":["event_id","workspace_id"],"title":"PromptLogEntry","description":"One ``prompt_log`` event projection — full LLM input + output for a turn.\n\nUnbounded string fields (``system_prompt``, ``full_prompt``,\n``llm_response``) reflect the producer's payload as-is — typically\n1-50 KB each, occasionally larger for long histories. SDK consumers\nshould not assume a max length."}}}} ``` ## The ProviderType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ProviderType":{"type":"string","enum":["twilio","websocket","ses","sendblue","meta"],"title":"ProviderType","description":"Messaging provider that implements a channel.\n\nMultiple providers may serve the same ChannelKind."}}}} ``` ## The ProvisionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ProvisionResponse":{"properties":{"workspace":{"$ref":"#/components/schemas/WorkspaceResponse"}},"type":"object","required":["workspace"],"title":"ProvisionResponse"},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"topic_modeling_enabled":{"type":"boolean","title":"Topic Modeling Enabled"},"delta_sharing_enabled":{"type":"boolean","title":"Delta Sharing Enabled"},"delta_sharing_mode":{"type":"string","enum":["open","databricks"],"title":"Delta Sharing Mode"},"delta_sharing_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delta Sharing Identifier"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","backend_org_id","region","connector_type","topic_modeling_enabled","delta_sharing_enabled","delta_sharing_mode","delta_sharing_identifier","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}}} ``` ## The QualityBreakdown object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"QualityBreakdown":{"properties":{"score":{"type":"number","title":"Score"},"components":{"items":{"$ref":"#/components/schemas/QualityComponent"},"type":"array","title":"Components"},"workspace_avg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Workspace Avg"},"workspace_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Workspace Percentile"}},"type":"object","required":["score","components"],"title":"QualityBreakdown","description":"Structured breakdown of how quality score was computed."},"QualityComponent":{"properties":{"name":{"type":"string","enum":["latency","silence","barge_ins","loops","escalation","tool_failures"],"title":"Name","description":"Quality dimension"},"penalty":{"type":"number","title":"Penalty","description":"Penalty subtracted from the score"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Raw measured value"},"threshold":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Threshold","description":"Threshold that was exceeded"},"severity":{"type":"string","enum":["none","minor","major","critical"],"title":"Severity","description":"Severity of the penalty","default":"none"}},"type":"object","required":["name","penalty"],"title":"QualityComponent","description":"Single quality score component with penalty and context."}}}} ``` ## The QualityComponent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"QualityComponent":{"properties":{"name":{"type":"string","enum":["latency","silence","barge_ins","loops","escalation","tool_failures"],"title":"Name","description":"Quality dimension"},"penalty":{"type":"number","title":"Penalty","description":"Penalty subtracted from the score"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Raw measured value"},"threshold":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Threshold","description":"Threshold that was exceeded"},"severity":{"type":"string","enum":["none","minor","major","critical"],"title":"Severity","description":"Severity of the penalty","default":"none"}},"type":"object","required":["name","penalty"],"title":"QualityComponent","description":"Single quality score component with penalty and context."}}}} ``` ## The QuietHours object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"QuietHours":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":false},"start_hour":{"type":"integer","maximum":23,"minimum":0,"title":"Start Hour","default":21},"end_hour":{"type":"integer","maximum":23,"minimum":0,"title":"End Hour","default":8},"timezone":{"type":"string","maxLength":64,"title":"Timezone","default":"America/New_York"}},"type":"object","title":"QuietHours","description":"Quiet hours — no outbound outreach during this window."}}}} ``` ## The RankedAnomalyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RankedAnomalyResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/RankedAnomalyRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"RankedAnomalyResponse"},"RankedAnomalyRow":{"properties":{"indicator":{"type":"string","title":"Indicator","default":"t2d_risk"},"district_name":{"type":"string","title":"District Name"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lat"},"lon":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lon"},"rate_per_1k":{"type":"number","title":"Rate Per 1K","default":0},"territory_mean":{"type":"number","title":"Territory Mean","default":0},"residual":{"type":"number","title":"Residual","default":0},"cohort_size":{"type":"integer","title":"Cohort Size","default":0},"is_anomaly":{"type":"boolean","title":"Is Anomaly","default":true},"alert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alert Id"},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity"},"priority_score":{"type":"number","title":"Priority Score","default":0},"impact":{"type":"number","title":"Impact","default":0},"narrative":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrative"},"decomposition":{"items":{"$ref":"#/components/schemas/DecompositionRow"},"type":"array","title":"Decomposition","default":[]}},"type":"object","required":["district_name"],"title":"RankedAnomalyRow"},"DecompositionRow":{"properties":{"feature_name":{"type":"string","title":"Feature Name"},"beta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Beta"},"delta_x":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta X"},"contribution":{"type":"number","title":"Contribution"},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"},"ci_lo":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ci Lo"},"ci_hi":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ci Hi"}},"type":"object","required":["feature_name","contribution"],"title":"DecompositionRow"}}}} ``` ## The RankedAnomalyRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RankedAnomalyRow":{"properties":{"indicator":{"type":"string","title":"Indicator","default":"t2d_risk"},"district_name":{"type":"string","title":"District Name"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lat"},"lon":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lon"},"rate_per_1k":{"type":"number","title":"Rate Per 1K","default":0},"territory_mean":{"type":"number","title":"Territory Mean","default":0},"residual":{"type":"number","title":"Residual","default":0},"cohort_size":{"type":"integer","title":"Cohort Size","default":0},"is_anomaly":{"type":"boolean","title":"Is Anomaly","default":true},"alert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alert Id"},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity"},"priority_score":{"type":"number","title":"Priority Score","default":0},"impact":{"type":"number","title":"Impact","default":0},"narrative":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Narrative"},"decomposition":{"items":{"$ref":"#/components/schemas/DecompositionRow"},"type":"array","title":"Decomposition","default":[]}},"type":"object","required":["district_name"],"title":"RankedAnomalyRow"},"DecompositionRow":{"properties":{"feature_name":{"type":"string","title":"Feature Name"},"beta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Beta"},"delta_x":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta X"},"contribution":{"type":"number","title":"Contribution"},"family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"},"ci_lo":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ci Lo"},"ci_hi":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ci Hi"}},"type":"object","required":["feature_name","contribution"],"title":"DecompositionRow"}}}} ``` ## The RealtimeCustomVoice object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."}}}} ``` ## The RealtimeSemanticVadConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."}}}} ``` ## The RealtimeServerVadConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."}}}} ``` ## The RealtimeSessionConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."}}}} ``` ## The RealtimeTranscriptionConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."}}}} ``` ## The RealtimeTruncationConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."}}}} ``` ## The RecommendRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RecommendRequest":{"properties":{"session_id":{"type":"string","maxLength":64,"title":"Session Id"},"n":{"type":"integer","maximum":20,"minimum":1,"title":"N","default":5}},"type":"object","required":["session_id"],"title":"RecommendRequest"}}}} ``` ## The RecommendResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RecommendResponse":{"properties":{"suggestions":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Suggestions","description":"LLM-generated caller message suggestions"}},"type":"object","required":["suggestions"],"title":"RecommendResponse"}}}} ``` ## The RecordingUrlsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RecordingUrlsResponse":{"properties":{"call_sid":{"type":"string","title":"Call Sid","description":"Twilio call SID"},"inbound_url":{"type":"string","title":"Inbound Url","description":"Presigned URL for the inbound (caller) WAV"},"outbound_url":{"type":"string","title":"Outbound Url","description":"Presigned URL for the outbound (agent) WAV"},"stereo_url":{"type":"string","title":"Stereo Url","description":"Presigned URL for the merged stereo (caller left / agent right) WAV"}},"type":"object","required":["call_sid","inbound_url","outbound_url","stereo_url"],"title":"RecordingUrlsResponse","description":"Presigned S3 URLs for a call recording's WAV objects."}}}} ``` ## The RegisterSchemaRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RegisterSchemaRequest":{"properties":{"name":{"$ref":"#/components/schemas/_DatasetSlug"},"file_type":{"$ref":"#/components/schemas/_FileType"},"accepted_file_types":{"items":{"$ref":"#/components/schemas/_FileType"},"type":"array","maxItems":16,"title":"Accepted File Types","description":"Document only — the SET of accepted file types (V265, e.g.\n``[\"pdf\",\"docx\",\"md\"]``). Empty → single-type (just ``file_type``).\n``file_type`` is included as the primary. Mixing in a tabular type\n(csv/xls/xlsx) is rejected; snapshot datasets are single-type.","default":[]},"primary_key":{"items":{"$ref":"#/components/schemas/_FieldName"},"type":"array","maxItems":32,"title":"Primary Key","description":"Snapshot only — the canonical PK column(s). Empty/ignored for documents.","default":[]},"schema":{"items":{"$ref":"#/components/schemas/SchemaFieldSpec"},"type":"array","maxItems":500,"title":"Schema","description":"Snapshot only — canonical field list ``[{name, type}]`` (wire key ``schema``).","default":[]},"document_processing":{"anyOf":[{"$ref":"#/components/schemas/DocumentProcessingSpec"},{"type":"null"}],"description":"Document only — extraction config; defaulted server-side when omitted."},"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","required":["name","file_type"],"title":"RegisterSchemaRequest","description":"Create Schema payload (intake-ui-mvp-design.md §5.4, §5.9).\n\n``ingestion_mode`` is inferred from ``file_type`` (csv/xls/xlsx → snapshot;\nelse document) — not part of the wire contract. Snapshot datasets require\n``primary_key`` + ``schema``; document datasets take an optional\n``document_processing`` config and ignore primary_key/schema. The backend\napplies the other hidden defaults (``on_schema_change=additive``,\n``schema_version`` auto)."},"_DatasetSlug":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$"},"_FileType":{"type":"string","maxLength":16,"minLength":1,"pattern":"^[a-z0-9]+$"},"_FieldName":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"SchemaFieldSpec":{"properties":{"name":{"$ref":"#/components/schemas/_FieldName"},"type":{"$ref":"#/components/schemas/IntakeFieldType"}},"type":"object","required":["name","type"],"title":"SchemaFieldSpec"},"IntakeFieldType":{"type":"string","enum":["str","int","float","bool","date","datetime"],"title":"IntakeFieldType","description":"Allowed ``schema[].type`` values for a registered contract.\n\nConfirmed set (intake-ui-mvp design contract point #1): scalars plus\nISO date/datetime. Coercion semantics live in :func:`_coerces`."},"DocumentProcessingSpec":{"properties":{"retain_source":{"type":"boolean","title":"Retain Source","default":true},"extraction_mode":{"type":"string","enum":["text_extract","OCR","hybrid"],"title":"Extraction Mode","default":"text_extract"}},"type":"object","title":"DocumentProcessingSpec","description":"Processing config for a document dataset (``ingestion_mode=document``).\n\nDocuments have no schema/primary-key/CDC; this is what the contract carries\ninstead (docs/plans/intake_file_processing_pipeline.md §5.9). Page-split /\noutput-metadata rules are stored in the same jsonb and may be added later\nwithout a migration."}}}} ``` ## The RegisterSourceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RegisterSourceRequest":{"properties":{"display_name":{"type":"string","maxLength":200,"minLength":1,"title":"Display Name"},"drive_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Drive Id"},"folders":{"items":{"$ref":"#/components/schemas/DriveFolderMapping"},"type":"array","maxItems":100,"minItems":1,"title":"Folders"},"impersonate_subject":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}],"title":"Impersonate Subject"}},"type":"object","required":["display_name","folders"],"title":"RegisterSourceRequest","description":"Register a Google Shared Drive intake source (design §3).\n\nThe credential is not part of the wire contract and nothing needs provisioning:\nthe source authenticates as the unified platform-infra intake service account,\nimpersonated from the pod's workload identity. Grant access Drive-side — share\nthe folder with that SA's email, or set ``impersonate_subject`` for the DWD\nmodel. ``drive_id`` is optional (resolved at sync if omitted)."},"DriveFolderMapping":{"properties":{"folder_id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Folder Id"},"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"contains_phi":{"type":"boolean","title":"Contains Phi","default":true}},"type":"object","required":["folder_id","dataset"],"title":"DriveFolderMapping","description":"One Google Drive folder ↔ one intake dataset.\n\n``folder_id`` is the Drive folder id (the identity — never the folder name,\nwhich can be renamed/moved). One folder maps to exactly one dataset."}}}} ``` ## The RegisteredFunction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RegisteredFunction":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description"},"when_to_use":{"type":"string","maxLength":2048,"title":"When To Use","default":""},"function_type":{"type":"string","enum":["sql","ai","udtf","python"],"title":"Function Type","default":"sql"},"returns":{"type":"string","enum":["table","scalar"],"title":"Returns","default":"table"},"returns_type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Returns Type","default":"string"},"parameters":{"items":{"$ref":"#/components/schemas/platform_lib__platform_functions__models__Parameter"},"type":"array","maxItems":32,"title":"Parameters"},"returns_columns":{"items":{"$ref":"#/components/schemas/ReturnColumn"},"type":"array","maxItems":32,"title":"Returns Columns"},"body":{"type":"string","maxLength":8192,"minLength":1,"title":"Body"},"timeout_ms":{"type":"integer","maximum":60000,"minimum":100,"title":"Timeout Ms","default":30000}},"additionalProperties":false,"type":"object","required":["name","description","body"],"title":"RegisteredFunction","description":"The authored shape of a platform function.\n\nIdentical wire format whether it's authored as a YAML file in the\nrepo or POSTed to ``/v1/{ws}/functions/deploy``. The deploy\npipeline validates this, derives the JSON Schema for the LLM tool\nspec, and INSERTs a row into ``platform.functions`` with the next\nmonotonic ``version`` per ``(workspace_id, name)``. For\n``python`` / ``udtf`` rows, deploy ALSO issues\n``CREATE OR REPLACE FUNCTION`` against the warehouse to materialize\nthe UC UDF."},"platform_lib__platform_functions__models__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted function-test or playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Typed declaration of one input parameter.\n\nFor SQL function types, ``name`` becomes the ``:name`` placeholder\nin the SQL template. For Python function types, ``name`` becomes\nthe positional argument name in ``def main(...)`` and the input\ncolumn name on the UC UDF signature.\n\nThe ``description`` propagates into the LLM tool spec (this is\nwhat Databricks' Agent Framework reads, and what Anthropic's\ntool-use spec exposes to the model). Missing descriptions\nsilently break tool selection — the registration layer rejects\nempty strings."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."},"ReturnColumn":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"title":"Description","default":""}},"additionalProperties":false,"type":"object","required":["name","type"],"title":"ReturnColumn","description":"One column in a UDTF's output schema.\n\nUC ``RETURNS TABLE( , , ...)`` requires\ndeclaring the schema at deploy time. This list anchors that\nschema for ``function_type=udtf`` rows. ``name`` becomes the\ncolumn name in the result rows; ``type`` maps to a Databricks\nSQL type via the same ``ParameterType`` Literal we use for inputs."}}}} ``` ## The RegisteredFunctionListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RegisteredFunctionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RegisteredFunctionResponse"},"type":"array","title":"Items"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["items","count"],"title":"RegisteredFunctionListResponse"},"RegisteredFunctionResponse":{"properties":{"name":{"type":"string","title":"Name"},"function_type":{"type":"string","title":"Function Type"},"returns_kind":{"type":"string","title":"Returns Kind"},"description":{"type":"string","title":"Description","default":""},"when_to_use":{"type":"string","title":"When To Use","default":""},"parameters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Parameters"},"sql_template":{"type":"string","title":"Sql Template"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"timeout_ms":{"type":"integer","title":"Timeout Ms","default":30000},"last_test_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test At"},"last_test_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Status"},"last_test_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Error"},"last_test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Test Duration Ms"},"deployed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed At"},"deployed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed By"}},"type":"object","required":["name","function_type","returns_kind","sql_template"],"title":"RegisteredFunctionResponse","description":"Single row from ``platform.functions``."}}}} ``` ## The RegisteredFunctionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RegisteredFunctionResponse":{"properties":{"name":{"type":"string","title":"Name"},"function_type":{"type":"string","title":"Function Type"},"returns_kind":{"type":"string","title":"Returns Kind"},"description":{"type":"string","title":"Description","default":""},"when_to_use":{"type":"string","title":"When To Use","default":""},"parameters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Parameters"},"sql_template":{"type":"string","title":"Sql Template"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"timeout_ms":{"type":"integer","title":"Timeout Ms","default":30000},"last_test_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test At"},"last_test_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Status"},"last_test_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Error"},"last_test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Test Duration Ms"},"deployed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed At"},"deployed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed By"}},"type":"object","required":["name","function_type","returns_kind","sql_template"],"title":"RegisteredFunctionResponse","description":"Single row from ``platform.functions``."}}}} ``` ## The RejectProposalRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RejectProposalRequest":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":1,"title":"Reason"}},"type":"object","required":["reason"],"title":"RejectProposalRequest"}}}} ``` ## The RejectSurfaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RejectSurfaceRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason"}},"type":"object","title":"RejectSurfaceRequest"}}}} ``` ## The RelationshipToDeveloper object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RelationshipToDeveloper":{"properties":{"ownership":{"type":"string","title":"Ownership"},"type":{"type":"string","title":"Type"},"conversation_visibility":{"type":"string","title":"Conversation Visibility"},"thought_visibility":{"type":"string","title":"Thought Visibility"}},"type":"object","required":["ownership","type","conversation_visibility","thought_visibility"],"title":"RelationshipToDeveloper"}}}} ``` ## The RenameColumnAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RenameColumnAction":{"properties":{"op":{"type":"string","const":"rename_column","title":"Op"},"from":{"$ref":"#/components/schemas/IdentifierString"},"to":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","from","to"],"title":"RenameColumnAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The ResolvePreviewRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ResolvePreviewRequest":{"properties":{"auth_claims":{"items":{"$ref":"#/components/schemas/ExternalAuthClaim"},"type":"array","maxItems":32,"title":"Auth Claims","default":[]}},"additionalProperties":false,"type":"object","title":"ResolvePreviewRequest"},"ExternalAuthClaim":{"properties":{"namespace":{"type":"string","maxLength":64,"pattern":"^[a-z][a-z0-9_.:-]{0,63}$","title":"Namespace"},"key":{"type":"string","maxLength":64,"pattern":"^[a-z][a-z0-9_.:-]{0,63}$","title":"Key"},"value":{"type":"string","maxLength":256,"minLength":1,"title":"Value"}},"additionalProperties":false,"type":"object","required":["namespace","key","value"],"title":"ExternalAuthClaim","description":"One normalized customer assertion: the exact tuple ``(namespace, key, value)``.\n\n``value`` is preserved byte-for-byte (bounded length only) — Amigo does not\nlowercase, alias, or rewrite it. ``namespace`` and ``key`` are bounded canonical\nidentifiers. Arrays, objects, numbers, booleans, and null are rejected for every\nfield (v1 values are non-empty strings)."}}}} ``` ## The ResolvePreviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ResolvePreviewResponse":{"properties":{"roles":{"items":{"$ref":"#/components/schemas/MappedRole"},"type":"array","title":"Roles"},"grants":{"items":{"$ref":"#/components/schemas/EffectiveGrant"},"type":"array","title":"Grants"},"unmapped_claim_count":{"type":"integer","title":"Unmapped Claim Count"}},"type":"object","required":["roles","grants","unmapped_claim_count"],"title":"ResolvePreviewResponse"},"MappedRole":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","name"],"title":"MappedRole"},"EffectiveGrant":{"properties":{"resource_type":{"$ref":"#/components/schemas/_ResourceType"},"resource_key":{"type":"string","title":"Resource Key"},"access":{"$ref":"#/components/schemas/_Access"}},"type":"object","required":["resource_type","resource_key","access"],"title":"EffectiveGrant"},"_ResourceType":{"type":"string","enum":["integration_endpoint","skill","kb_scope"]},"_Access":{"type":"string","enum":["read","write"]}}}} ``` ## The ResolveTemplateRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ResolveTemplateRequest":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"}},"type":"object","required":["entity_id"],"title":"ResolveTemplateRequest","description":"Resolve a form template for a specific entity."}}}} ``` ## The ResolveTemplateResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ResolveTemplateResponse":{"properties":{"spec":{"$ref":"#/components/schemas/SurfaceSpec"},"prefilled_count":{"type":"integer","title":"Prefilled Count"},"total_fields":{"type":"integer","title":"Total Fields"}},"type":"object","required":["spec","prefilled_count","total_fields"],"title":"ResolveTemplateResponse","description":"Resolved SurfaceSpec with prefill values."},"SurfaceSpec":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"fields":{"items":{"$ref":"#/components/schemas/SurfaceField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"web"},"expires_in_hours":{"type":"integer","maximum":8760,"minimum":1,"title":"Expires In Hours","default":168},"context":{"additionalProperties":true,"type":"object","title":"Context"},"resource_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Resource Type"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/SurfaceSection"},"type":"array"},{"type":"null"}],"title":"Sections"},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"}},"type":"object","required":["entity_id","title","fields"],"title":"SurfaceSpec","description":"A complete surface specification generated by an agent.\n\nThe agent reads the HSM (entity state, relationships,\nconfidence gaps) and produces this spec. The spec is stored as a\nworld.event and rendered by platform-api into a patient-facing page."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"SurfaceField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"prefill_value":{"anyOf":[{},{"type":"null"}],"title":"Prefill Value"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"}},"type":"object","required":["key","label","field_type"],"title":"SurfaceField","description":"A single data collection field in a surface spec.\n\nGenerated by agents from HSM analysis. Each field maps\nto a specific piece of data the world model needs."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."},"SurfaceSection":{"properties":{"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["title","field_keys"],"title":"SurfaceSection","description":"A page/step in a multi-page surface form."}}}} ``` ## The ResolvedToolItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ResolvedToolItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"tool_type":{"type":"string","title":"Tool Type"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"states":{"items":{"type":"string"},"type":"array","title":"States"},"tier":{"type":"string","title":"Tier","default":"world"},"is_write":{"type":"boolean","title":"Is Write","default":false},"additional_instructions":{"additionalProperties":{"type":"string"},"type":"object","title":"Additional Instructions"}},"type":"object","required":["tool_name","tool_type"],"title":"ResolvedToolItem"}}}} ``` ## The Resource object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Resource":{"properties":{"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"}},"type":"object","required":["attributes"],"title":"Resource"},"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"$ref":"#/components/schemas/AnyValue"}},"type":"object","required":["key","value"],"title":"KeyValue","description":"OTLP ``KeyValue`` attribute pair."},"AnyValue":{"additionalProperties":true,"type":"object"}}}} ``` ## The ResourceSpans object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ResourceSpans":{"properties":{"resource":{"$ref":"#/components/schemas/Resource"},"scopeSpans":{"items":{"$ref":"#/components/schemas/ScopeSpans"},"type":"array","title":"Scopespans"}},"type":"object","required":["resource","scopeSpans"],"title":"ResourceSpans"},"Resource":{"properties":{"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"}},"type":"object","required":["attributes"],"title":"Resource"},"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"$ref":"#/components/schemas/AnyValue"}},"type":"object","required":["key","value"],"title":"KeyValue","description":"OTLP ``KeyValue`` attribute pair."},"AnyValue":{"additionalProperties":true,"type":"object"},"ScopeSpans":{"properties":{"scope":{"$ref":"#/components/schemas/InstrumentationScope"},"spans":{"items":{"$ref":"#/components/schemas/Span"},"type":"array","title":"Spans"}},"type":"object","required":["scope","spans"],"title":"ScopeSpans"},"InstrumentationScope":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"}},"type":"object","required":["name","version"],"title":"InstrumentationScope"},"Span":{"properties":{"traceId":{"type":"string","title":"Traceid"},"spanId":{"type":"string","title":"Spanid"},"name":{"type":"string","title":"Name"},"kind":{"type":"integer","title":"Kind"},"startTimeUnixNano":{"type":"string","title":"Starttimeunixnano"},"endTimeUnixNano":{"type":"string","title":"Endtimeunixnano"},"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"},"status":{"$ref":"#/components/schemas/Status"}},"type":"object","required":["traceId","spanId","name","kind","startTimeUnixNano","endTimeUnixNano","attributes","status"],"title":"Span","description":"OTLP ``Span`` in OTLP/JSON encoding (ids hex, timestamps decimal-string)."},"Status":{"properties":{"code":{"type":"integer","title":"Code"}},"type":"object","required":["code"],"title":"Status","description":"OTLP ``Status`` — 0=UNSET, 1=OK, 2=ERROR."}}}} ``` ## The RestIntegrationResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RestIntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Integration ID."},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace ID."},"name":{"type":"string","title":"Name","description":"Slug-like identifier, immutable post-create."},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active."},"managed":{"type":"boolean","title":"Managed","description":"Whether the integration is system-managed and protected from workspace CRUD.","default":false},"approval_policy":{"type":"string","enum":["none","writes","all"],"title":"Approval Policy","description":"Human-in-the-loop approval gate. ``none`` = no approval required;\n``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the integration was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the integration was last updated."},"kind":{"type":"string","const":"rest","title":"Kind","description":"Discriminator.","default":"rest"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations."},"auth":{"anyOf":[{"$ref":"#/components/schemas/StaticHeaderAuthDict"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthDict"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthDict"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthDict"},{"type":"null"}],"title":"Auth","description":"Authentication configuration (lib TypedDict union)."},"endpoint_count":{"type":"integer","title":"Endpoint Count","description":"Number of configured endpoints. Fetch the full list via GET /endpoints."}},"type":"object","required":["id","workspace_id","name","display_name","enabled","created_at","updated_at","base_url","endpoint_count"],"title":"RestIntegrationResponse","description":"REST variant — base URL, auth config, endpoint count."},"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer \"``."},"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."},"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}}} ``` ## The RetentionPolicyRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RetentionPolicyRequest":{"properties":{"call_recordings_days":{"anyOf":[{"type":"integer","maximum":36500,"minimum":365},{"type":"null"}],"title":"Call Recordings Days"},"call_transcripts_days":{"anyOf":[{"type":"integer","maximum":36500,"minimum":365},{"type":"null"}],"title":"Call Transcripts Days"},"audit_log_days":{"anyOf":[{"type":"integer","maximum":36500,"minimum":365},{"type":"null"}],"title":"Audit Log Days"},"world_events_days":{"anyOf":[{"type":"integer","maximum":36500,"minimum":365},{"type":"null"}],"title":"World Events Days"},"phi_data_days":{"anyOf":[{"type":"integer","maximum":36500,"minimum":365},{"type":"null"}],"title":"Phi Data Days"},"legal_hold":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Legal Hold"},"legal_hold_reason":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","title":"RetentionPolicyRequest"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The RetentionPolicyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RetentionPolicyResponse":{"properties":{"call_recordings_days":{"type":"integer","title":"Call Recordings Days"},"call_transcripts_days":{"type":"integer","title":"Call Transcripts Days"},"audit_log_days":{"type":"integer","title":"Audit Log Days"},"world_events_days":{"type":"integer","title":"World Events Days"},"phi_data_days":{"type":"integer","title":"Phi Data Days"},"legal_hold":{"type":"boolean","title":"Legal Hold"},"legal_hold_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Hold Reason"}},"type":"object","required":["call_recordings_days","call_transcripts_days","audit_log_days","world_events_days","phi_data_days","legal_hold"],"title":"RetentionPolicyResponse"}}}} ``` ## The ReturnColumn object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ReturnColumn":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"title":"Description","default":""}},"additionalProperties":false,"type":"object","required":["name","type"],"title":"ReturnColumn","description":"One column in a UDTF's output schema.\n\nUC ``RETURNS TABLE( , , ...)`` requires\ndeclaring the schema at deploy time. This list anchors that\nschema for ``function_type=udtf`` rows. ``name`` becomes the\ncolumn name in the result rows; ``type`` maps to a Databricks\nSQL type via the same ``ParameterType`` Literal we use for inputs."}}}} ``` ## The ReviewActionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ReviewActionResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"action":{"type":"string","enum":["approved","rejected"],"title":"Action"}},"type":"object","required":["surface_id","status","action"],"title":"ReviewActionResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."}}}} ``` ## The ReviewMetrics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ReviewMetrics":{"properties":{"queue_depth":{"type":"integer","title":"Queue Depth"},"pending_by_priority":{"additionalProperties":{"type":"integer"},"type":"object","title":"Pending By Priority"},"approved_7d":{"type":"integer","title":"Approved 7D"},"rejected_7d":{"type":"integer","title":"Rejected 7D"},"avg_review_time_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Review Time Hours"},"total_items":{"type":"integer","title":"Total Items","default":0}},"type":"object","required":["queue_depth","pending_by_priority","approved_7d","rejected_7d"],"title":"ReviewMetrics"}}}} ``` ## The ReviewQueueListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ReviewQueueListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SurfaceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ReviewQueueListResponse"},"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"},"review_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Notes"},"reviewed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Reviewed By"},"reviewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed At"},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archived At"},"archive_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archive Reason"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The RiskSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RiskSummary":{"properties":{"composite_score":{"type":"number","title":"Composite Score","description":"Overall risk score 0.0 to 1.0","default":0},"level":{"type":"string","enum":["low","medium","high","critical"],"title":"Level","description":"Risk level","default":"low"}},"type":"object","title":"RiskSummary","description":"Aggregated risk signals across the call.\n\nFree-form residual on the raw ``risk_summary`` JSONB:\n``signals: list[{name, raw_score, weight, weighted_score, detail}]``\n— the per-signal breakdown that aggregates into ``composite_score``.\nNot exposed via this typed shape; consumers needing per-signal\ndetail read the JSONB endpoint."}}}} ``` ## The RoleEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RoleEntry":{"properties":{"name":{"type":"string","title":"Name"},"priority":{"type":"integer","title":"Priority"},"description":{"type":"string","title":"Description"},"permission_names":{"items":{"type":"string"},"type":"array","title":"Permission Names"}},"type":"object","required":["name","priority","description","permission_names"],"title":"RoleEntry"}}}} ``` ## The RoleGrantItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RoleGrantItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"role_id":{"type":"string","format":"uuid","title":"Role Id"},"resource_type":{"$ref":"#/components/schemas/_ResourceType"},"resource_key":{"type":"string","title":"Resource Key"},"access":{"$ref":"#/components/schemas/_Access"},"param_binding":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param Binding"},"status":{"type":"string","enum":["active","superseded"],"title":"Status"},"changed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Changed By"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","role_id","resource_type","resource_key","access","status","created_at"],"title":"RoleGrantItem"},"_ResourceType":{"type":"string","enum":["integration_endpoint","skill","kb_scope"]},"_Access":{"type":"string","enum":["read","write"]}}}} ``` ## The RoleGrantKeysBinding object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The RotateApiKeyRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RotateApiKeyRequest":{"properties":{"duration_days":{"type":"integer","maximum":90,"minimum":1,"title":"Duration Days"}},"type":"object","required":["duration_days"],"title":"RotateApiKeyRequest"}}}} ``` ## The Run object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Run":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"kind":{"type":"string","enum":["conversation","framework"],"title":"Kind"},"status":{"type":"string","enum":["running","paused","completed","failed","timed_out"],"title":"Status"},"channel":{"anyOf":[{"type":"string","enum":["voice","text","sms","email","web"]},{"type":"null"}],"title":"Channel"},"framework":{"anyOf":[{"type":"string","enum":["claude-agent-sdk","openai-agents"]},{"type":"null"}],"title":"Framework"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Count"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"source_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Call Sid"},"source_conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Conversation Id"},"source_framework_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Framework Run Id"},"takeover":{"$ref":"#/components/schemas/TakeoverEligibility","description":"Channel-neutral takeover eligibility, derived from this run's own fields.\n\nA computed field (not a stored one) so eligibility is derived in ONE place and\ncan never drift across the reader's per-source builders — every ``Run``, however\nconstructed, exposes a consistent ``takeover`` on the wire + in OpenAPI.","readOnly":true}},"type":"object","required":["run_id","workspace_id","kind","status","started_at","takeover"],"title":"Run","description":"One item in the canonical unified Runs read model.\n\n``run_id`` is a dedicated UUID (not an overloaded ``call_sid`` / ``conversation_id``);\nthe originating subsystem's ids are kept as ``source_*`` provenance fields so a\nrun can always be traced back to its channel/framework origin. Conversation runs\ncarry a ``channel`` and no ``framework``; framework runs carry a ``framework`` and\nno ``channel`` — enforced below."},"TakeoverEligibility":{"properties":{"eligible":{"type":"boolean","title":"Eligible"},"mode_options":{"items":{"type":"string","enum":["listen","takeover"]},"type":"array","title":"Mode Options","default":[]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["eligible"],"title":"TakeoverEligibility","description":"Whether an operator can take a run over, and how — the channel-neutral signal the\nconsole keys on instead of a per-channel heuristic.\n\n``eligible`` = an operator may take this run over right now. ``mode_options`` = the\ntakeover modes valid for the run's channel (voice exposes ``listen`` + ``takeover``;\nenumerated asynchronous channels expose authored-turn ``takeover`` only).\n``reason`` = a short, human-facing explanation when NOT eligible (e.g.\n``\"run is not live\"``, ``\"channel not yet supported\"``), so the console can\nrender an honest disabled-state tooltip rather than a bare greyed button.\nServer-computed (see ``Run.takeover``) so eligibility rules live in one place and the\nconsole never re-derives them."}}}} ``` ## The RunAuthoredTurnRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunAuthoredTurnRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"text":{"type":"string","maxLength":4000,"minLength":1,"title":"Text"}},"type":"object","required":["operator_id","text"],"title":"RunAuthoredTurnRequest"}}}} ``` ## The RunAuthoredTurnResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunAuthoredTurnResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"staged":{"type":"boolean","title":"Staged"}},"type":"object","required":["run_id","staged"],"title":"RunAuthoredTurnResponse"}}}} ``` ## The RunGuidanceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunGuidanceRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"message":{"type":"string","maxLength":5000,"minLength":1,"title":"Message"}},"type":"object","required":["operator_id","message"],"title":"RunGuidanceRequest","description":"Operator guidance for a live run. ``operator_id`` is in the body because this\nrouter is not under ``/operators/{operator_id}`` — it is bound to the authenticated\ncaller by ``_enforce_operator_identity`` (no impersonation)."}}}} ``` ## The RunGuidanceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunGuidanceResponse":{"properties":{"status":{"type":"string","enum":["delivered","queued_no_subscriber","deduplicated","failed","unknown"],"title":"Status","description":"Delivery status"},"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"Run the guidance was sent to"}},"type":"object","required":["status","run_id"],"title":"RunGuidanceResponse"}}}} ``` ## The RunHandbackRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunHandbackRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"}},"type":"object","required":["operator_id"],"title":"RunHandbackRequest"}}}} ``` ## The RunHandbackResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunHandbackResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"success":{"type":"boolean","title":"Success"}},"type":"object","required":["run_id","success"],"title":"RunHandbackResponse"}}}} ``` ## The RunSimulationBenchmarkRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunSimulationBenchmarkRequest":{"properties":{"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Required Tags"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Optional world entity UUID to bind caller context for every selected saved-case run. When omitted, each case falls back to fixtures.case_specific.entity_id if present."},"max_cases":{"type":"integer","maximum":200,"minimum":1,"title":"Max Cases","default":20},"max_turns":{"type":"integer","maximum":40,"minimum":1,"title":"Max Turns","default":20},"concurrency":{"type":"integer","maximum":20,"minimum":1,"title":"Concurrency","default":1},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"exploration":{"anyOf":[{"$ref":"#/components/schemas/ExplorationConfig"},{"type":"null"}]}},"type":"object","title":"RunSimulationBenchmarkRequest"},"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"}}}} ``` ## The RunSimulationCaseRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunSimulationCaseRequest":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Optional world entity UUID to bind caller context for this saved-case run. When omitted, the runner falls back to fixtures.case_specific.entity_id if present."},"max_turns":{"type":"integer","maximum":40,"minimum":1,"title":"Max Turns","default":20},"concurrency":{"type":"integer","maximum":20,"minimum":1,"title":"Concurrency","default":1},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"exploration":{"anyOf":[{"$ref":"#/components/schemas/ExplorationConfig"},{"type":"null"}]}},"type":"object","title":"RunSimulationCaseRequest"},"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"}}}} ``` ## The RunSwitchModeRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunSwitchModeRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"participant_call_sid":{"type":"string","maxLength":64,"title":"Participant Call Sid"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"}},"type":"object","required":["operator_id","participant_call_sid","mode"],"title":"RunSwitchModeRequest"}}}} ``` ## The RunSwitchModeResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunSwitchModeResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"}},"type":"object","required":["run_id","mode"],"title":"RunSwitchModeResponse"}}}} ``` ## The RunTakeoverRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunTakeoverRequest":{"properties":{"operator_id":{"type":"string","format":"uuid","title":"Operator Id"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","default":"takeover"}},"type":"object","required":["operator_id"],"title":"RunTakeoverRequest"}}}} ``` ## The RunTakeoverResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunTakeoverResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"},"participant_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Call Sid"},"conference_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conference Sid"}},"type":"object","required":["run_id","mode"],"title":"RunTakeoverResponse"}}}} ``` ## The RunTrajectoryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunTrajectoryResponse":{"properties":{"steps":{"items":{"$ref":"#/components/schemas/TrajectoryStep"},"type":"array","title":"Steps"},"truncated":{"type":"boolean","title":"Truncated"}},"type":"object","required":["steps","truncated"],"title":"RunTrajectoryResponse"},"TrajectoryStep":{"properties":{"seq":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seq"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"},"actor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"tool_input_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Input Summary"},"tool_result_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Result Summary"},"tool_succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tool Succeeded"},"decision_from_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision From State"},"decision_to_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision To State"},"effective_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective At"}},"type":"object","title":"TrajectoryStep","description":"One structural step of a framework run's trajectory. Fields are best-effort\n(only those the step actually carries are present), all optional, and free ``str``\nfor the same read-model resilience the ``Run`` descriptive fields use."}}}} ``` ## The RunsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunsResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/Run"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"RunsResponse"},"Run":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"kind":{"type":"string","enum":["conversation","framework"],"title":"Kind"},"status":{"type":"string","enum":["running","paused","completed","failed","timed_out"],"title":"Status"},"channel":{"anyOf":[{"type":"string","enum":["voice","text","sms","email","web"]},{"type":"null"}],"title":"Channel"},"framework":{"anyOf":[{"type":"string","enum":["claude-agent-sdk","openai-agents"]},{"type":"null"}],"title":"Framework"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn Count"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"source_call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Call Sid"},"source_conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Conversation Id"},"source_framework_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Framework Run Id"},"takeover":{"$ref":"#/components/schemas/TakeoverEligibility","description":"Channel-neutral takeover eligibility, derived from this run's own fields.\n\nA computed field (not a stored one) so eligibility is derived in ONE place and\ncan never drift across the reader's per-source builders — every ``Run``, however\nconstructed, exposes a consistent ``takeover`` on the wire + in OpenAPI.","readOnly":true}},"type":"object","required":["run_id","workspace_id","kind","status","started_at","takeover"],"title":"Run","description":"One item in the canonical unified Runs read model.\n\n``run_id`` is a dedicated UUID (not an overloaded ``call_sid`` / ``conversation_id``);\nthe originating subsystem's ids are kept as ``source_*`` provenance fields so a\nrun can always be traced back to its channel/framework origin. Conversation runs\ncarry a ``channel`` and no ``framework``; framework runs carry a ``framework`` and\nno ``channel`` — enforced below."},"TakeoverEligibility":{"properties":{"eligible":{"type":"boolean","title":"Eligible"},"mode_options":{"items":{"type":"string","enum":["listen","takeover"]},"type":"array","title":"Mode Options","default":[]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["eligible"],"title":"TakeoverEligibility","description":"Whether an operator can take a run over, and how — the channel-neutral signal the\nconsole keys on instead of a per-channel heuristic.\n\n``eligible`` = an operator may take this run over right now. ``mode_options`` = the\ntakeover modes valid for the run's channel (voice exposes ``listen`` + ``takeover``;\nenumerated asynchronous channels expose authored-turn ``takeover`` only).\n``reason`` = a short, human-facing explanation when NOT eligible (e.g.\n``\"run is not live\"``, ``\"channel not yet supported\"``), so the console can\nrender an honest disabled-state tooltip rather than a bare greyed button.\nServer-computed (see ``Run.takeover``) so eligibility rules live in one place and the\nconsole never re-derives them."}}}} ``` ## The RunsSummaryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"RunsSummaryResponse":{"properties":{"total":{"type":"integer","title":"Total"},"live":{"type":"integer","title":"Live"},"running":{"type":"integer","title":"Running"},"paused":{"type":"integer","title":"Paused"},"completed":{"type":"integer","title":"Completed"},"failed":{"type":"integer","title":"Failed"},"timed_out":{"type":"integer","title":"Timed Out"},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status"},"by_kind":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Kind"}},"type":"object","required":["total","live","running","paused","completed","failed","timed_out","by_status","by_kind"],"title":"RunsSummaryResponse","description":"Aggregate run counts for the Runs page summary strip.\n\nHonest workspace totals the paginated list cannot derive client-side (it only\nholds the loaded page). ``by_status`` carries the full canonical breakdown\n(incl. any status beyond the named convenience fields); ``by_kind`` splits\nframework vs conversation. ``live`` = running + paused."}}}} ``` ## The Runtime object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Runtime":{"properties":{"engage_model":{"type":"string","title":"Engage Model","default":""},"channel_kind":{"type":"string","title":"Channel Kind","default":""},"language":{"type":"string","title":"Language","default":""},"caller_context":{"type":"string","title":"Caller Context","default":""}},"type":"object","title":"Runtime"}}}} ``` ## The SafetyState object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SafetyState":{"properties":{"peak_concern_level":{"type":"integer","title":"Peak Concern Level","default":0},"concern_turn_count":{"type":"integer","title":"Concern Turn Count","default":0},"trajectory":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trajectory"},"triage_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Triage History","default":[]},"concept_matches":{"items":{"$ref":"#/components/schemas/ConceptMatch"},"type":"array","title":"Concept Matches","default":[]}},"type":"object","title":"SafetyState"},"ConceptMatch":{"properties":{"concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity"},"agent_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Action"},"agent_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Confidence"},"agent_reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Reasoning"},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"At"}},"type":"object","title":"ConceptMatch"}}}} ``` ## The SafetySummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SafetySummary":{"properties":{"match_count":{"type":"integer","title":"Match Count","description":"Number of safety filter matches","default":0}},"type":"object","title":"SafetySummary","description":"Safety filter results.\n\nFree-form residual on the raw ``safety_summary`` JSONB:\n``actions: dict | list`` — escalation handler actions taken\nwhen ``match_count > 0``. Not exposed via this typed shape."}}}} ``` ## The SaveFieldResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SaveFieldResponse":{"properties":{"status":{"type":"string","const":"saved","title":"Status","default":"saved"}},"type":"object","title":"SaveFieldResponse","description":"Acknowledgement returned when a field is auto-saved."}}}} ``` ## The Scenario object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Scenario":{"properties":{"description":{"type":"string","maxLength":512,"title":"Description"},"temperament":{"type":"string","maxLength":32,"title":"Temperament","default":"neutral"},"initial_message":{"type":"string","maxLength":1000,"title":"Initial Message"},"scenario_instructions":{"type":"string","maxLength":2000,"title":"Scenario Instructions"},"persona":{"$ref":"#/components/schemas/ScenarioPersona"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"}},"type":"object","required":["description","initial_message","scenario_instructions"],"title":"Scenario"},"ScenarioPersona":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name","default":""},"role":{"type":"string","maxLength":64,"title":"Role","default":"patient"},"communication_style":{"type":"string","maxLength":512,"title":"Communication Style","default":""},"default_language":{"type":"string","maxLength":16,"title":"Default Language","default":"en-US"},"background":{"type":"string","maxLength":2000,"title":"Background","default":""}},"type":"object","title":"ScenarioPersona"}}}} ``` ## The ScenarioPersona object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ScenarioPersona":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name","default":""},"role":{"type":"string","maxLength":64,"title":"Role","default":"patient"},"communication_style":{"type":"string","maxLength":512,"title":"Communication Style","default":""},"default_language":{"type":"string","maxLength":16,"title":"Default Language","default":"en-US"},"background":{"type":"string","maxLength":2000,"title":"Background","default":""}},"type":"object","title":"ScenarioPersona"}}}} ``` ## The SchedulingRuleSetListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SchedulingRuleSetListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SchedulingRuleSetResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"SchedulingRuleSetListResponse"},"SchedulingRuleSetResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"agent_kind":{"type":"string","enum":["tms","ketamine","general"],"title":"Agent Kind"},"rule_kind":{"type":"string","enum":["clinic_open_hours","tms_mapping_release","tms_session_grid","ketamine_block_overlap","ninety_day_rolling","concurrent_start_block"],"title":"Rule Kind"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"is_active":{"type":"boolean","title":"Is Active"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","agent_kind","rule_kind","params","is_active","created_by","created_at","updated_at"],"title":"SchedulingRuleSetResponse","description":"Wire shape for a single rule set. ``params`` stays as ``dict``\nhere (not the discriminated union) so add-a-new-kind doesn't break\nolder clients still on the previous SDK version — the SDK's typed\nhelpers can re-validate into ``RuleParams`` when needed."}}}} ``` ## The SchedulingRuleSetResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SchedulingRuleSetResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"agent_kind":{"type":"string","enum":["tms","ketamine","general"],"title":"Agent Kind"},"rule_kind":{"type":"string","enum":["clinic_open_hours","tms_mapping_release","tms_session_grid","ketamine_block_overlap","ninety_day_rolling","concurrent_start_block"],"title":"Rule Kind"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"is_active":{"type":"boolean","title":"Is Active"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","agent_kind","rule_kind","params","is_active","created_by","created_at","updated_at"],"title":"SchedulingRuleSetResponse","description":"Wire shape for a single rule set. ``params`` stays as ``dict``\nhere (not the discriminated union) so add-a-new-kind doesn't break\nolder clients still on the previous SDK version — the SDK's typed\nhelpers can re-validate into ``RuleParams`` when needed."}}}} ``` ## The SchemaFieldSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SchemaFieldSpec":{"properties":{"name":{"$ref":"#/components/schemas/_FieldName"},"type":{"$ref":"#/components/schemas/IntakeFieldType"}},"type":"object","required":["name","type"],"title":"SchemaFieldSpec"},"_FieldName":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"IntakeFieldType":{"type":"string","enum":["str","int","float","bool","date","datetime"],"title":"IntakeFieldType","description":"Allowed ``schema[].type`` values for a registered contract.\n\nConfirmed set (intake-ui-mvp design contract point #1): scalars plus\nISO date/datetime. Coercion semantics live in :func:`_coerces`."}}}} ``` ## The SchemaResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SchemaResponse":{"properties":{"lakebase_tables":{"additionalProperties":{"additionalProperties":{"type":"string"},"type":"object"},"type":"object","title":"Lakebase Tables"},"databricks_catalogs":{"items":{"type":"string"},"type":"array","title":"Databricks Catalogs"},"uc_functions":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Uc Functions"},"ai_functions":{"items":{"type":"string"},"type":"array","title":"Ai Functions"}},"type":"object","required":["lakebase_tables","databricks_catalogs","uc_functions","ai_functions"],"title":"SchemaResponse"}}}} ``` ## The ScopeSpans object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ScopeSpans":{"properties":{"scope":{"$ref":"#/components/schemas/InstrumentationScope"},"spans":{"items":{"$ref":"#/components/schemas/Span"},"type":"array","title":"Spans"}},"type":"object","required":["scope","spans"],"title":"ScopeSpans"},"InstrumentationScope":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"}},"type":"object","required":["name","version"],"title":"InstrumentationScope"},"Span":{"properties":{"traceId":{"type":"string","title":"Traceid"},"spanId":{"type":"string","title":"Spanid"},"name":{"type":"string","title":"Name"},"kind":{"type":"integer","title":"Kind"},"startTimeUnixNano":{"type":"string","title":"Starttimeunixnano"},"endTimeUnixNano":{"type":"string","title":"Endtimeunixnano"},"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"},"status":{"$ref":"#/components/schemas/Status"}},"type":"object","required":["traceId","spanId","name","kind","startTimeUnixNano","endTimeUnixNano","attributes","status"],"title":"Span","description":"OTLP ``Span`` in OTLP/JSON encoding (ids hex, timestamps decimal-string)."},"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"$ref":"#/components/schemas/AnyValue"}},"type":"object","required":["key","value"],"title":"KeyValue","description":"OTLP ``KeyValue`` attribute pair."},"AnyValue":{"additionalProperties":true,"type":"object"},"Status":{"properties":{"code":{"type":"integer","title":"Code"}},"type":"object","required":["code"],"title":"Status","description":"OTLP ``Status`` — 0=UNSET, 1=OK, 2=ERROR."}}}} ``` ## The ScoreSessionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ScoreSessionRequest":{"properties":{"score":{"type":"number","maximum":100,"minimum":0,"title":"Score"},"score_rationale":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Score Rationale"}},"type":"object","required":["score"],"title":"ScoreSessionRequest"}}}} ``` ## The SearchString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SearchString":{"type":"string","maxLength":200,"minLength":1}}}} ``` ## The SendGuidanceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SendGuidanceRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"message":{"type":"string","maxLength":5000,"minLength":1,"title":"Message"}},"type":"object","required":["call_sid","message"],"title":"SendGuidanceRequest"}}}} ``` ## The SendGuidanceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SendGuidanceResponse":{"properties":{"status":{"type":"string","enum":["delivered","queued_no_subscriber","deduplicated","failed","unknown"],"title":"Status","description":"Delivery status"},"call_sid":{"type":"string","title":"Call Sid","description":"Call SID the guidance was sent to"}},"type":"object","required":["status","call_sid"],"title":"SendGuidanceResponse"}}}} ``` ## The Service object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Service":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet-Output"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity","default":3},"channel_type":{"type":"string","enum":["voice","text"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig-Output"},{"type":"null"}]},"accepted_context":{"items":{"$ref":"#/components/schemas/ContextKeySpec"},"type":"array","maxItems":100,"title":"Accepted Context"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","name","description","agent_id","context_graph_id","keyterms","is_active","version_sets","tags"],"title":"Service","description":"A service links an agent + context graph + version sets."},"VersionSet-Output":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig-Output":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The ServiceBindingRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceBindingRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"}},"type":"object","required":["service_id"],"title":"ServiceBindingRequest"}}}} ``` ## The ServiceBindingResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceBindingResponse":{"properties":{"use_case_id":{"type":"string","format":"uuid","title":"Use Case Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"channel":{"type":"string","enum":["inbound_voice","outbound_voice","email","sms","imessage","whatsapp"],"title":"Channel"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["use_case_id","service_id","workspace_id","channel","created_at","updated_at"],"title":"ServiceBindingResponse"}}}} ``` ## The ServiceCost object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceCost":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for cost that could not be attributed."},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"This service's priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / total priced cost in the selected scope, after any service filter.\nNull when the service has no priced cost or the denominator is zero or unavailable."}},"type":"object","required":["service_id","calculated_cost_usd","cost_share"],"title":"ServiceCost","description":"Cost attributed to one service."}}}} ``` ## The ServiceForwardingConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2}}}} ``` ## The ServiceListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ServiceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ServiceListResponse"},"ServiceResponse":{"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"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Graph Name"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet-Output"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity"},"channel_type":{"type":"string","enum":["voice","text"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig-Output"},{"type":"null"}]},"accepted_context":{"items":{"$ref":"#/components/schemas/ContextKeySpec"},"type":"array","title":"Accepted Context"},"is_system":{"type":"boolean","title":"Is System","default":false},"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","agent_id","context_graph_id","keyterms","is_active","version_sets","tags","tool_capacity","created_at","updated_at"],"title":"ServiceResponse"},"VersionSet-Output":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig-Output":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The ServiceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceResponse":{"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"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"context_graph_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context Graph Name"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"is_active":{"type":"boolean","title":"Is Active"},"version_sets":{"additionalProperties":{"$ref":"#/components/schemas/VersionSet-Output"},"type":"object","title":"Version Sets"},"tags":{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","title":"Tags"},"tool_capacity":{"type":"integer","title":"Tool Capacity"},"channel_type":{"type":"string","enum":["voice","text"],"title":"Channel Type","default":"voice"},"environment":{"type":"string","enum":["sandbox","production"],"title":"Environment","default":"production"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig-Output"},{"type":"null"}]},"accepted_context":{"items":{"$ref":"#/components/schemas/ContextKeySpec"},"type":"array","title":"Accepted Context"},"is_system":{"type":"boolean","title":"Is System","default":false},"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","agent_id","context_graph_id","keyterms","is_active","version_sets","tags","tool_capacity","created_at","updated_at"],"title":"ServiceResponse"},"VersionSet-Output":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig-Output":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The ServiceTag object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"}}}} ``` ## The ServiceUsage object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceUsage":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for usage that could not be attributed."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["service_id","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ServiceUsage","description":"Usage attributed to one service."}}}} ``` ## The ServiceVoiceConfig-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceVoiceConfig-Input":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2}}}} ``` ## The ServiceVoiceConfig-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ServiceVoiceConfig-Output":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2}}}} ``` ## The SessionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SessionResponse":{"properties":{"id":{"type":"string","title":"Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id"],"title":"SessionResponse"}}}} ``` ## The SetColumnDefaultAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SetColumnDefaultAction":{"properties":{"op":{"type":"string","const":"set_column_default","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"default":{"$ref":"#/components/schemas/Default"}},"type":"object","required":["op","name","default"],"title":"SetColumnDefaultAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"}}}} ``` ## The SetColumnNullableAction object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SetColumnNullableAction":{"properties":{"op":{"type":"string","const":"set_column_nullable","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"nullable":{"type":"boolean","title":"Nullable"}},"type":"object","required":["op","name","nullable"],"title":"SetColumnNullableAction"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"}}}} ``` ## The SignalResponseAlignment object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SignalResponseAlignment":{"properties":{"signal":{"type":"string","maxLength":2000,"minLength":1,"title":"Signal","description":"The signal observed (e.g. caller tone shift, tool result, silence)"},"agent_response":{"type":"string","maxLength":2000,"minLength":1,"title":"Agent Response","description":"What the agent did in response"},"alignment":{"type":"string","enum":["aligned","misaligned","partial"],"title":"Alignment","description":"Whether the response was aligned, misaligned, or partial"},"insight":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Insight","description":"Short insight on why the alignment went the way it did"}},"type":"object","required":["signal","agent_response","alignment"],"title":"SignalResponseAlignment","description":"Whether the agent's response aligned with a salient signal in the call."}}}} ``` ## The SimCaseAssertionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimCaseAssertionResponse":{"properties":{"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (metric + assertion verdicts),\nso the console renders each drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["eval_key","eval_type","checks"],"title":"SimCaseAssertionResponse"},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."}}}} ``` ## The SimCasePerfResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimCasePerfResponse":{"properties":{"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"case_name":{"type":"string","maxLength":512,"title":"Case Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0},"latest_run_id":{"type":"string","format":"uuid","title":"Latest Run Id"},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"assertions":{"items":{"$ref":"#/components/schemas/SimCaseAssertionResponse"},"type":"array","title":"Assertions"}},"type":"object","required":["case_name","latest_run_id"],"title":"SimCasePerfResponse"},"SimCaseAssertionResponse":{"properties":{"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (metric + assertion verdicts),\nso the console renders each drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["eval_key","eval_type","checks"],"title":"SimCaseAssertionResponse"},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."}}}} ``` ## The SimMetricPerfResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimMetricPerfResponse":{"properties":{"metric_key":{"type":"string","maxLength":128,"title":"Metric Key"},"label":{"type":"string","maxLength":128,"title":"Label"},"per_run":{"items":{"$ref":"#/components/schemas/SimMetricRunPointResponse"},"type":"array","title":"Per Run"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (mirrors SimCaseAssertionResponse)\nso the console renders each metric drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["metric_key","label","checks"],"title":"SimMetricPerfResponse"},"SimMetricRunPointResponse":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0}},"type":"object","title":"SimMetricRunPointResponse","description":"One run's contribution to a metric: the mean value that run (null for\nnon-numeric metrics) plus how many conversations passed / were measured."},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."}}}} ``` ## The SimMetricRunPointResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimMetricRunPointResponse":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0}},"type":"object","title":"SimMetricRunPointResponse","description":"One run's contribution to a metric: the mean value that run (null for\nnon-numeric metrics) plus how many conversations passed / were measured."}}}} ``` ## The SimPerformanceOverviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimPerformanceOverviewResponse":{"properties":{"overall_pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall Pass Rate"},"evals_run":{"type":"integer","title":"Evals Run","default":0},"needs_attention_count":{"type":"integer","title":"Needs Attention Count","default":0},"runs_analyzed":{"type":"integer","title":"Runs Analyzed","default":0}},"type":"object","title":"SimPerformanceOverviewResponse"}}}} ``` ## The SimSuitePerfResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimSuitePerfResponse":{"properties":{"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"suite_name":{"type":"string","maxLength":512,"title":"Suite Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"cases":{"items":{"$ref":"#/components/schemas/SimCasePerfResponse"},"type":"array","title":"Cases"}},"type":"object","required":["suite_name"],"title":"SimSuitePerfResponse"},"SimCasePerfResponse":{"properties":{"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"case_name":{"type":"string","maxLength":512,"title":"Case Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0},"latest_run_id":{"type":"string","format":"uuid","title":"Latest Run Id"},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"assertions":{"items":{"$ref":"#/components/schemas/SimCaseAssertionResponse"},"type":"array","title":"Assertions"}},"type":"object","required":["case_name","latest_run_id"],"title":"SimCasePerfResponse"},"SimCaseAssertionResponse":{"properties":{"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (metric + assertion verdicts),\nso the console renders each drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["eval_key","eval_type","checks"],"title":"SimCaseAssertionResponse"},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."}}}} ``` ## The SimulationBenchmarkAggregateSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationBenchmarkAggregateSummary":{"properties":{"selected_count":{"type":"integer","title":"Selected Count"},"started_count":{"type":"integer","title":"Started Count"},"skipped_count":{"type":"integer","title":"Skipped Count"},"failed_to_start_count":{"type":"integer","title":"Failed To Start Count"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"}},"type":"object","required":["selected_count","started_count","skipped_count","failed_to_start_count"],"title":"SimulationBenchmarkAggregateSummary"}}}} ``` ## The SimulationBenchmarkBreakdownSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationBenchmarkBreakdownSummary":{"properties":{"run_count":{"type":"integer","title":"Run Count","default":0},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0}},"type":"object","title":"SimulationBenchmarkBreakdownSummary"}}}} ``` ## The SimulationBenchmarkCaseResult object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationBenchmarkCaseResult":{"properties":{"case_id":{"type":"string","format":"uuid","title":"Case Id"},"status":{"type":"string","enum":["started","skipped","failed_to_start"],"title":"Status"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"result_pointer":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Pointer"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason"}},"type":"object","required":["case_id","status"],"title":"SimulationBenchmarkCaseResult"}}}} ``` ## The SimulationBenchmarkPerRunSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationBenchmarkPerRunSummary":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"session_ids":{"items":{"type":"string","maxLength":128},"type":"array","title":"Session Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"terminal_session_count":{"type":"integer","title":"Terminal Session Count","default":0},"scored_session_count":{"type":"integer","title":"Scored Session Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"score_rationales":{"items":{"type":"string","maxLength":2000},"type":"array","title":"Score Rationales"},"capability_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Capability Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"},"immediate_average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immediate Average Score"},"immediate_passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Immediate Passed"},"immediate_pass_count":{"type":"integer","title":"Immediate Pass Count","default":0},"immediate_fail_count":{"type":"integer","title":"Immediate Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"}},"type":"object","required":["run_id","service_id","status"],"title":"SimulationBenchmarkPerRunSummary"}}}} ``` ## The SimulationBenchmarkResultsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationBenchmarkResultsResponse":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"},"per_run":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkPerRunSummary"},"type":"array","title":"Per Run"},"capability_breakdown":{"additionalProperties":{"$ref":"#/components/schemas/SimulationBenchmarkBreakdownSummary"},"type":"object","title":"Capability Breakdown"},"missing_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Missing Run Ids"}},"type":"object","required":["run_ids","total_runs"],"title":"SimulationBenchmarkResultsResponse"},"SimulationBenchmarkPerRunSummary":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"session_ids":{"items":{"type":"string","maxLength":128},"type":"array","title":"Session Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"terminal_session_count":{"type":"integer","title":"Terminal Session Count","default":0},"scored_session_count":{"type":"integer","title":"Scored Session Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"score_rationales":{"items":{"type":"string","maxLength":2000},"type":"array","title":"Score Rationales"},"capability_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Capability Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"},"immediate_average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immediate Average Score"},"immediate_passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Immediate Passed"},"immediate_pass_count":{"type":"integer","title":"Immediate Pass Count","default":0},"immediate_fail_count":{"type":"integer","title":"Immediate Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"}},"type":"object","required":["run_id","service_id","status"],"title":"SimulationBenchmarkPerRunSummary"},"SimulationBenchmarkBreakdownSummary":{"properties":{"run_count":{"type":"integer","title":"Run Count","default":0},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0}},"type":"object","title":"SimulationBenchmarkBreakdownSummary"}}}} ``` ## The SimulationBenchmarkRunResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationBenchmarkRunResponse":{"properties":{"batch_id":{"type":"string","format":"uuid","title":"Batch Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"selected_case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Selected Case Ids"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"cases":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkCaseResult"},"type":"array","title":"Cases"},"skipped_cases":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkCaseResult"},"type":"array","title":"Skipped Cases"},"failed_to_start_cases":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkCaseResult"},"type":"array","title":"Failed To Start Cases"},"aggregate_summary":{"$ref":"#/components/schemas/SimulationBenchmarkAggregateSummary"}},"type":"object","required":["batch_id","required_tags","selected_case_ids","run_ids","cases","skipped_cases","failed_to_start_cases","aggregate_summary"],"title":"SimulationBenchmarkRunResponse"},"SimulationBenchmarkCaseResult":{"properties":{"case_id":{"type":"string","format":"uuid","title":"Case Id"},"status":{"type":"string","enum":["started","skipped","failed_to_start"],"title":"Status"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"result_pointer":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Pointer"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason"}},"type":"object","required":["case_id","status"],"title":"SimulationBenchmarkCaseResult"},"SimulationBenchmarkAggregateSummary":{"properties":{"selected_count":{"type":"integer","title":"Selected Count"},"started_count":{"type":"integer","title":"Started Count"},"skipped_count":{"type":"integer","title":"Skipped Count"},"failed_to_start_count":{"type":"integer","title":"Failed To Start Count"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"}},"type":"object","required":["selected_count","started_count","skipped_count","failed_to_start_count"],"title":"SimulationBenchmarkAggregateSummary"}}}} ``` ## The SimulationCaseAssertionEval object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The SimulationCaseGrounding object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."}}}} ``` ## The SimulationCaseListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationCaseListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SimulationCaseResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"SimulationCaseListResponse"},"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The SimulationCaseMetricEval object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"}}}} ``` ## The SimulationCaseResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The SimulationCaseScenario object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."}}}} ``` ## The SimulationEvalResultResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"}}}} ``` ## The SimulationIntelligenceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationIntelligenceResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"intelligence":{"additionalProperties":true,"type":"object","title":"Intelligence"}},"type":"object","required":["session_id","intelligence"],"title":"SimulationIntelligenceResponse"}}}} ``` ## The SimulationObservation object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationObservation":{"properties":{"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"agent_text":{"type":"string","title":"Agent Text"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details","default":[]},"selected_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action"},"empathy_tier":{"type":"integer","title":"Empathy Tier","default":0},"has_pause":{"type":"boolean","title":"Has Pause","default":false},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"}},"type":"object","required":["state_before","state_after","state_changed","agent_text","is_terminal"],"title":"SimulationObservation"},"ToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"input":{"type":"string","title":"Input","default":""},"result":{"type":"string","title":"Result","default":""},"call_id":{"type":"string","title":"Call Id","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","required":["tool_name"],"title":"ToolCallDetail","description":"Rich tool call data from a simulation step."}}}} ``` ## The SimulationPerformanceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationPerformanceResponse":{"properties":{"overview":{"$ref":"#/components/schemas/SimPerformanceOverviewResponse"},"metrics":{"items":{"$ref":"#/components/schemas/SimMetricPerfResponse"},"type":"array","title":"Metrics"},"by_case":{"items":{"$ref":"#/components/schemas/SimCasePerfResponse"},"type":"array","title":"By Case"},"by_suite":{"items":{"$ref":"#/components/schemas/SimSuitePerfResponse"},"type":"array","title":"By Suite"}},"type":"object","required":["overview"],"title":"SimulationPerformanceResponse","description":"Aggregated Simulations overview: one request in place of the console's\nformer one-detail-fetch-per-run fan-out."},"SimPerformanceOverviewResponse":{"properties":{"overall_pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall Pass Rate"},"evals_run":{"type":"integer","title":"Evals Run","default":0},"needs_attention_count":{"type":"integer","title":"Needs Attention Count","default":0},"runs_analyzed":{"type":"integer","title":"Runs Analyzed","default":0}},"type":"object","title":"SimPerformanceOverviewResponse"},"SimMetricPerfResponse":{"properties":{"metric_key":{"type":"string","maxLength":128,"title":"Metric Key"},"label":{"type":"string","maxLength":128,"title":"Label"},"per_run":{"items":{"$ref":"#/components/schemas/SimMetricRunPointResponse"},"type":"array","title":"Per Run"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (mirrors SimCaseAssertionResponse)\nso the console renders each metric drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["metric_key","label","checks"],"title":"SimMetricPerfResponse"},"SimMetricRunPointResponse":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0}},"type":"object","title":"SimMetricRunPointResponse","description":"One run's contribution to a metric: the mean value that run (null for\nnon-numeric metrics) plus how many conversations passed / were measured."},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."},"SimCasePerfResponse":{"properties":{"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"case_name":{"type":"string","maxLength":512,"title":"Case Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0},"latest_run_id":{"type":"string","format":"uuid","title":"Latest Run Id"},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"assertions":{"items":{"$ref":"#/components/schemas/SimCaseAssertionResponse"},"type":"array","title":"Assertions"}},"type":"object","required":["case_name","latest_run_id"],"title":"SimCasePerfResponse"},"SimCaseAssertionResponse":{"properties":{"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (metric + assertion verdicts),\nso the console renders each drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["eval_key","eval_type","checks"],"title":"SimCaseAssertionResponse"},"SimSuitePerfResponse":{"properties":{"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"suite_name":{"type":"string","maxLength":512,"title":"Suite Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","default":0},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"cases":{"items":{"$ref":"#/components/schemas/SimCasePerfResponse"},"type":"array","title":"Cases"}},"type":"object","required":["suite_name"],"title":"SimSuitePerfResponse"}}}} ``` ## The SimulationProxyErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}}} ``` ## The SimulationRunResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"objective":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Objective"},"bridge_request":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Bridge Request"},"scenarios":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Scenarios"},"snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Snapshot"},"total_scenarios_requested":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Scenarios Requested"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"},"eval_results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Eval Results"},"eval_result_count":{"type":"integer","title":"Eval Result Count","default":0},"eval_pass_count":{"type":"integer","title":"Eval Pass Count","default":0},"eval_fail_count":{"type":"integer","title":"Eval Fail Count","default":0},"eval_error_count":{"type":"integer","title":"Eval Error Count","default":0},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``eval_results``. Raw ``eval_results``\nstay intact; this rides alongside so the console renders checks without\nreverse-engineering actual.latest vs actual.judge vs score.","readOnly":true}},"type":"object","required":["id","service_id","status","checks"],"title":"SimulationRunResponse","description":"Full run payload — used by GET /runs/{run_id} for replay flows."},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Score Label"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."}}}} ``` ## The SimulationSessionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"greeting":{"type":"string","title":"Greeting"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"snapshot":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}},"type":"object","required":["session_id","greeting","is_terminal","snapshot"],"title":"SimulationSessionResponse"},"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"barge_in_enabled":true,"greeting_shield_s":0,"safety_response":"suspend_forward","context_strategy":"full","block_forward_call":false,"block_forward_call_after_turns":-1}},"conversation_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"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","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"}}}} ``` ## The SimulationSnapshotResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"barge_in_enabled":true,"greeting_shield_s":0,"safety_response":"suspend_forward","context_strategy":"full","block_forward_call":false,"block_forward_call_after_turns":-1}},"conversation_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"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","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"}}}} ``` ## The SimulationStateResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"}}}} ``` ## The SimulationStepResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationStepResponse":{"properties":{"observation":{"$ref":"#/components/schemas/SimulationObservation"},"snapshot":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}},"type":"object","required":["observation","snapshot"],"title":"SimulationStepResponse"},"SimulationObservation":{"properties":{"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"agent_text":{"type":"string","title":"Agent Text"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details","default":[]},"selected_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action"},"empathy_tier":{"type":"integer","title":"Empathy Tier","default":0},"has_pause":{"type":"boolean","title":"Has Pause","default":false},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"}},"type":"object","required":["state_before","state_after","state_changed","agent_text","is_terminal"],"title":"SimulationObservation"},"ToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"input":{"type":"string","title":"Input","default":""},"result":{"type":"string","title":"Result","default":""},"call_id":{"type":"string","title":"Call Id","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","required":["tool_name"],"title":"ToolCallDetail","description":"Rich tool call data from a simulation step."},"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"barge_in_enabled":true,"greeting_shield_s":0,"safety_response":"suspend_forward","context_strategy":"full","block_forward_call":false,"block_forward_call_after_turns":-1}},"conversation_history":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"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","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"}}}} ``` ## The SimulationSuiteResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationSuiteResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","name","case_count"],"title":"SimulationSuiteResponse","description":"HTTP response shape for first-class simulation suites."}}}} ``` ## The SimulationSuiteRunResultsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationSuiteRunResultsResponse":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"},"per_run":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkPerRunSummary"},"type":"array","title":"Per Run"},"capability_breakdown":{"additionalProperties":{"$ref":"#/components/schemas/SimulationBenchmarkBreakdownSummary"},"type":"object","title":"Capability Breakdown"},"missing_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Missing Run Ids"},"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"summary":{"$ref":"#/components/schemas/SimulationSuiteRunSummary"}},"type":"object","required":["run_ids","total_runs","suite_run_id","summary"],"title":"SimulationSuiteRunResultsResponse"},"SimulationBenchmarkPerRunSummary":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"session_ids":{"items":{"type":"string","maxLength":128},"type":"array","title":"Session Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"terminal_session_count":{"type":"integer","title":"Terminal Session Count","default":0},"scored_session_count":{"type":"integer","title":"Scored Session Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"score_rationales":{"items":{"type":"string","maxLength":2000},"type":"array","title":"Score Rationales"},"capability_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Capability Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"},"immediate_average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immediate Average Score"},"immediate_passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Immediate Passed"},"immediate_pass_count":{"type":"integer","title":"Immediate Pass Count","default":0},"immediate_fail_count":{"type":"integer","title":"Immediate Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"}},"type":"object","required":["run_id","service_id","status"],"title":"SimulationBenchmarkPerRunSummary"},"SimulationBenchmarkBreakdownSummary":{"properties":{"run_count":{"type":"integer","title":"Run Count","default":0},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0}},"type":"object","title":"SimulationBenchmarkBreakdownSummary"},"SimulationSuiteRunSummary":{"properties":{"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"expected_case_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Expected Case Count"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"}},"type":"object","required":["suite_run_id","run_ids","total_runs","status"],"title":"SimulationSuiteRunSummary"}}}} ``` ## The SimulationSuiteRunSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationSuiteRunSummary":{"properties":{"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"expected_case_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Expected Case Count"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"}},"type":"object","required":["suite_run_id","run_ids","total_runs","status"],"title":"SimulationSuiteRunSummary"}}}} ``` ## The SimulationTurnPolicyResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationTurnPolicyResponse":{"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","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"}}}} ``` ## The SkillContextGraphReference object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SkillContextGraphReference":{"properties":{"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"context_graph_name":{"type":"string","title":"Context Graph Name"},"version":{"type":"integer","title":"Version"},"states":{"items":{"$ref":"#/components/schemas/SkillStateReference"},"type":"array","title":"States"}},"type":"object","required":["context_graph_id","context_graph_name","version","states"],"title":"SkillContextGraphReference"},"SkillStateReference":{"properties":{"state_name":{"type":"string","title":"State Name"},"tool_spec_category":{"type":"string","title":"Tool Spec Category"}},"type":"object","required":["state_name","tool_spec_category"],"title":"SkillStateReference"}}}} ``` ## The SkillListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SkillListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SkillResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"SkillListResponse"},"SkillResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model"},"max_tokens":{"type":"integer","title":"Max Tokens"},"max_result_chars":{"type":"integer","title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S"},"thinking_effort":{"anyOf":[{"$ref":"#/components/schemas/ThinkingEffort"},{"type":"null"}]},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P"},"enable_caching":{"type":"boolean","title":"Enable Caching"},"enable_citations":{"type":"boolean","title":"Enable Citations"},"use_structured_output":{"type":"boolean","title":"Use Structured Output"},"integration_tools":{"items":{"$ref":"#/components/schemas/src__models__IntegrationToolRef"},"type":"array","title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/src__models__StaticToolDef"},"type":"array","title":"Static Tools"},"enabled":{"type":"boolean","title":"Enabled"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns"},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled"},"approval_required":{"type":"boolean","title":"Approval Required"},"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","slug","name","description","system_prompt","input_schema","result_schema","model","max_tokens","max_result_chars","max_input_tokens","timeout_s","thinking_effort","temperature","top_p","enable_caching","enable_citations","use_structured_output","integration_tools","static_tools","enabled","max_agent_turns","checkpoint_enabled","approval_required","created_at","updated_at"],"title":"SkillResponse"},"ThinkingEffort":{"type":"string","enum":["low","medium","high"]},"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}}} ``` ## The SkillReferencesResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SkillReferencesResponse":{"properties":{"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"skill_slug":{"type":"string","title":"Skill Slug"},"context_graph_references":{"items":{"$ref":"#/components/schemas/SkillContextGraphReference"},"type":"array","title":"Context Graph References"},"service_references":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Service References"}},"type":"object","required":["skill_id","skill_slug","context_graph_references","service_references"],"title":"SkillReferencesResponse"},"SkillContextGraphReference":{"properties":{"context_graph_id":{"type":"string","format":"uuid","title":"Context Graph Id"},"context_graph_name":{"type":"string","title":"Context Graph Name"},"version":{"type":"integer","title":"Version"},"states":{"items":{"$ref":"#/components/schemas/SkillStateReference"},"type":"array","title":"States"}},"type":"object","required":["context_graph_id","context_graph_name","version","states"],"title":"SkillContextGraphReference"},"SkillStateReference":{"properties":{"state_name":{"type":"string","title":"State Name"},"tool_spec_category":{"type":"string","title":"Tool Spec Category"}},"type":"object","required":["state_name","tool_spec_category"],"title":"SkillStateReference"}}}} ``` ## The SkillResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SkillResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"type":"string","title":"Model"},"max_tokens":{"type":"integer","title":"Max Tokens"},"max_result_chars":{"type":"integer","title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"type":"number","title":"Timeout S"},"thinking_effort":{"anyOf":[{"$ref":"#/components/schemas/ThinkingEffort"},{"type":"null"}]},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P"},"enable_caching":{"type":"boolean","title":"Enable Caching"},"enable_citations":{"type":"boolean","title":"Enable Citations"},"use_structured_output":{"type":"boolean","title":"Use Structured Output"},"integration_tools":{"items":{"$ref":"#/components/schemas/src__models__IntegrationToolRef"},"type":"array","title":"Integration Tools"},"static_tools":{"items":{"$ref":"#/components/schemas/src__models__StaticToolDef"},"type":"array","title":"Static Tools"},"enabled":{"type":"boolean","title":"Enabled"},"max_agent_turns":{"type":"integer","title":"Max Agent Turns"},"checkpoint_enabled":{"type":"boolean","title":"Checkpoint Enabled"},"approval_required":{"type":"boolean","title":"Approval Required"},"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","slug","name","description","system_prompt","input_schema","result_schema","model","max_tokens","max_result_chars","max_input_tokens","timeout_s","thinking_effort","temperature","top_p","enable_caching","enable_citations","use_structured_output","integration_tools","static_tools","enabled","max_agent_turns","checkpoint_enabled","approval_required","created_at","updated_at"],"title":"SkillResponse"},"ThinkingEffort":{"type":"string","enum":["low","medium","high"]},"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}}} ``` ## The SkillStateReference object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SkillStateReference":{"properties":{"state_name":{"type":"string","title":"State Name"},"tool_spec_category":{"type":"string","title":"Tool Spec Category"}},"type":"object","required":["state_name","tool_spec_category"],"title":"SkillStateReference"}}}} ``` ## The SlugString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"}}}} ``` ## The SourceBreakdownItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceBreakdownItem":{"properties":{"source_system":{"type":"string","title":"Source System"},"entity_type":{"type":"string","title":"Entity Type"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["source_system","entity_type","count"],"title":"SourceBreakdownItem"}}}} ``` ## The SourceBreakdownResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceBreakdownResponse":{"properties":{"breakdown":{"items":{"$ref":"#/components/schemas/SourceBreakdownItem"},"type":"array","title":"Breakdown"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["breakdown","total"],"title":"SourceBreakdownResponse"},"SourceBreakdownItem":{"properties":{"source_system":{"type":"string","title":"Source System"},"entity_type":{"type":"string","title":"Entity Type"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["source_system","entity_type","count"],"title":"SourceBreakdownItem"}}}} ``` ## The SourceEventItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceEventItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_type":{"type":"string","title":"Event Type"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"source":{"type":"string","title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"confidence":{"type":"number","title":"Confidence"},"ingested_at":{"type":"string","format":"date-time","title":"Ingested At"}},"type":"object","required":["id","event_type","source","confidence","ingested_at"],"title":"SourceEventItem"}}}} ``` ## The SourceEventListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceEventListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SourceEventItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"SourceEventListResponse"},"SourceEventItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_type":{"type":"string","title":"Event Type"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"source":{"type":"string","title":"Source"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"confidence":{"type":"number","title":"Confidence"},"ingested_at":{"type":"string","format":"date-time","title":"Ingested At"}},"type":"object","required":["id","event_type","source","confidence","ingested_at"],"title":"SourceEventItem"}}}} ``` ## The SourceFailureItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceFailureItem":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"type":"string","title":"Event Type"},"fhir_resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Type"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"ingested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ingested At"}},"type":"object","required":["event_id","event_type"],"title":"SourceFailureItem"}}}} ``` ## The SourceHistoryItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceHistoryItem":{"properties":{"bucket":{"type":"string","title":"Bucket"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"event_count":{"type":"integer","title":"Event Count"}},"type":"object","required":["bucket","event_count"],"title":"SourceHistoryItem"}}}} ``` ## The SourceListItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"is_active":{"type":"boolean","title":"Is Active"},"health_status":{"type":"string","enum":["unknown","healthy","degraded"],"title":"Health Status"},"last_poll":{"anyOf":[{"$ref":"#/components/schemas/LastPollInfo"},{"type":"null"}]},"event_count":{"type":"integer","title":"Event Count","default":0},"last_sync_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Sync At"}},"type":"object","required":["id","name","source_type","is_active","health_status"],"title":"SourceListItem"},"LastPollInfo":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"duration_ms":{"type":"integer","title":"Duration Ms","default":0},"event_count":{"type":"integer","title":"Event Count","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"LastPollInfo"}}}} ``` ## The SourceOverviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceOverviewResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"is_active":{"type":"boolean","title":"Is Active"},"health_status":{"type":"string","enum":["unknown","healthy","degraded"],"title":"Health Status"},"last_sync_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Sync At"},"last_sync_status":{"anyOf":[{"type":"string","enum":["success","error"]},{"type":"null"}],"title":"Last Sync Status"},"last_sync_event_count":{"type":"integer","title":"Last Sync Event Count","default":0},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"event_count":{"type":"integer","title":"Event Count","default":0},"entity_count":{"type":"integer","title":"Entity Count","default":0},"last_poll":{"anyOf":[{"$ref":"#/components/schemas/LastPollInfo"},{"type":"null"}]},"recent_failures":{"items":{"$ref":"#/components/schemas/SourceFailureItem"},"type":"array","title":"Recent Failures","default":[]},"outbound":{"$ref":"#/components/schemas/OutboundSummary","default":{"total":0,"synced":0,"failed":0,"pending":0}}},"type":"object","required":["id","name","source_type","is_active","health_status"],"title":"SourceOverviewResponse"},"LastPollInfo":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"duration_ms":{"type":"integer","title":"Duration Ms","default":0},"event_count":{"type":"integer","title":"Event Count","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"LastPollInfo"},"SourceFailureItem":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"type":"string","title":"Event Type"},"fhir_resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Type"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"ingested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ingested At"}},"type":"object","required":["event_id","event_type"],"title":"SourceFailureItem"},"OutboundSummary":{"properties":{"total":{"type":"integer","title":"Total","default":0},"synced":{"type":"integer","title":"Synced","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Synced At"}},"type":"object","title":"OutboundSummary"}}}} ``` ## The SourceStatus object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceStatus":{"properties":{"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"source_type":{"type":"string","enum":["ehr","fhir_store","snowflake"],"title":"Source Type"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"status":{"type":"string","title":"Status"},"last_poll_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Poll At"},"last_poll_duration_ms":{"type":"integer","title":"Last Poll Duration Ms","default":0},"last_poll_event_count":{"type":"integer","title":"Last Poll Event Count","default":0},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"consecutive_errors":{"type":"integer","title":"Consecutive Errors","default":0},"connection_healthy":{"type":"boolean","title":"Connection Healthy","default":true}},"type":"object","required":["data_source_id","workspace_id","source_type","status"],"title":"SourceStatus"}}}} ``` ## The SourceSyncResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SourceSyncResponse":{"properties":{"batches":{"items":{"$ref":"#/components/schemas/SyncBatchRow"},"type":"array","title":"Batches"}},"type":"object","required":["batches"],"title":"SourceSyncResponse"},"SyncBatchRow":{"properties":{"batch_id":{"type":"string","format":"uuid","title":"Batch Id"},"dataset":{"type":"string","title":"Dataset"},"files_found":{"type":"integer","title":"Files Found"},"status":{"type":"string","title":"Status"}},"type":"object","required":["batch_id","dataset","files_found","status"],"title":"SyncBatchRow","description":"One batch produced by a source sync (one per mapped folder/dataset)."}}}} ``` ## The Span object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Span":{"properties":{"traceId":{"type":"string","title":"Traceid"},"spanId":{"type":"string","title":"Spanid"},"name":{"type":"string","title":"Name"},"kind":{"type":"integer","title":"Kind"},"startTimeUnixNano":{"type":"string","title":"Starttimeunixnano"},"endTimeUnixNano":{"type":"string","title":"Endtimeunixnano"},"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"},"status":{"$ref":"#/components/schemas/Status"}},"type":"object","required":["traceId","spanId","name","kind","startTimeUnixNano","endTimeUnixNano","attributes","status"],"title":"Span","description":"OTLP ``Span`` in OTLP/JSON encoding (ids hex, timestamps decimal-string)."},"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"$ref":"#/components/schemas/AnyValue"}},"type":"object","required":["key","value"],"title":"KeyValue","description":"OTLP ``KeyValue`` attribute pair."},"AnyValue":{"additionalProperties":true,"type":"object"},"Status":{"properties":{"code":{"type":"integer","title":"Code"}},"type":"object","required":["code"],"title":"Status","description":"OTLP ``Status`` — 0=UNSET, 1=OK, 2=ERROR."}}}} ``` ## The SqlQueryRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SqlQueryRequest":{"properties":{"sql":{"type":"string","maxLength":50000,"minLength":1,"title":"Sql","description":"Read-only SQL query against Databricks."}},"type":"object","required":["sql"],"title":"SqlQueryRequest"}}}} ``` ## The SqlQueryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SqlQueryResponse":{"properties":{"results":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Results"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"SqlQueryResponse"}}}} ``` ## The StartSessionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StartSessionRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"World model entity UUID. Provide either entity_id or canonical_id."},"canonical_id":{"anyOf":[{"$ref":"#/components/schemas/CanonicalIdString"},{"type":"null"}],"description":"World model canonical_id of the form 'source:resource_type:id' (e.g. 'charmhealth:Patient:67890'). The structural regex on CanonicalIdString blocks spaces, names, DOBs, and similar regulated content. Resolved against the SDP-projected world.entities_synced table; a freshly-created entity may not be visible yet if the projection is lagging. Provide either entity_id or canonical_id, not both."},"channel_kind":{"type":"string","const":"web","title":"Channel Kind"},"greeting":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Greeting","description":"Custom greeting. Agent auto-greets if omitted."}},"type":"object","required":["service_id","channel_kind"],"title":"StartSessionRequest"},"CanonicalIdString":{"type":"string","maxLength":256,"minLength":3,"pattern":"^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$"}}}} ``` ## The StartSessionResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StartSessionResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"session_status":{"type":"string","enum":["created","already_active"],"title":"Session Status"},"channel_kind":{"type":"string","const":"web","title":"Channel Kind"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["conversation_id","session_status","channel_kind","entity_id","service_id","created_at"],"title":"StartSessionResponse"}}}} ``` ## The StateTransition object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StateTransition":{"properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"previous_state":{"type":"string","title":"Previous State","default":""},"next_state":{"type":"string","title":"Next State","default":""},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"from_state":{"type":"string","title":"From State","readOnly":true},"to_state":{"type":"string","title":"To State","readOnly":true}},"type":"object","required":["from_state","to_state"],"title":"StateTransition"}}}} ``` ## The StaticHeaderAuthDict object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer \"``."}}}} ``` ## The StaticHeaderAuthRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StaticHeaderAuthRequest":{"properties":{"type":{"type":"string","const":"static_header","title":"Type","default":"static_header"},"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name","description":"Outbound header name (RFC 7230 tchar)."}},"type":"object","required":["header_name"],"title":"StaticHeaderAuthRequest","description":"Static workspace-level secret used verbatim as a single header value."}}}} ``` ## The StaticToolDef-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StaticToolDef-Input":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}}} ``` ## The Status object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Status":{"properties":{"code":{"type":"integer","title":"Code"}},"type":"object","required":["code"],"title":"Status","description":"OTLP ``Status`` — 0=UNSET, 1=OK, 2=ERROR."}}}} ``` ## The StatusWriteBackRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StatusWriteBackRequest":{"properties":{"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Error Reason"},"curated_path":{"anyOf":[{"$ref":"#/components/schemas/_VolumePath"},{"type":"null"}]},"cdc_path":{"anyOf":[{"$ref":"#/components/schemas/_VolumePath"},{"type":"null"}]}},"type":"object","required":["status"],"title":"StatusWriteBackRequest","description":"Status advance written by the async CDC job (P4).\n\nThe job posts the terminal verdict after conform/validate/diff. ``error_reason``\nmust be PHI-safe (the engine reports column + type + counts only — never cell\nvalues). ``curated_path``/``cdc_path`` are set only on a clean verdict."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]},"_VolumePath":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z0-9/._-]+$"}}}} ``` ## The StepRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StepRequest":{"properties":{"session_id":{"type":"string","maxLength":64,"title":"Session Id"},"caller_text":{"type":"string","maxLength":2000,"title":"Caller Text"},"emotion":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Valence"}},"type":"object","required":["session_id","caller_text"],"title":"StepRequest"}}}} ``` ## The StoredParameter object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StoredParameter":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"StoredParameter","description":"One typed input parameter to a workspace data query — trusted shape.\n\nRead-path model: the DB's CHECK constraints already enforced ``name``\nregex and ``type`` enum on write, and the deploy endpoint's strict\n:class:`Parameter` validators enforced ``description`` length and\ntypo-rejection at the inbound network edge. After that, every\nconstruction of this model (DB read projection, executor binding,\nagent-engine spec, outbound response) is trusted — no 422 surface.\n\n``default is None`` is the canonical \"required\" signal: the executor\nraises if a caller omits a required argument, otherwise substitutes\nthe stored default."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The StratifiedFitRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StratifiedFitRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"outcome_key":{"type":"string","title":"Outcome Key"},"outcome_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outcome Name"},"cohort":{"type":"string","title":"Cohort"},"region":{"type":"string","title":"Region"},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N"},"base_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Base Rate"},"auroc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Auroc"},"intercept":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Intercept"},"coefficients_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coefficients Json"},"is_pooled_fallback":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Pooled Fallback"}},"type":"object","required":["workspace_id","outcome_key","cohort","region"],"title":"StratifiedFitRow"}}}} ``` ## The StratifiedFitsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StratifiedFitsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/StratifiedFitRow"},"type":"array","title":"Items"}},"type":"object","required":["workspace_id","count","items"],"title":"StratifiedFitsResponse"},"StratifiedFitRow":{"properties":{"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"labs"}],"title":"Workspace Id"},"outcome_key":{"type":"string","title":"Outcome Key"},"outcome_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outcome Name"},"cohort":{"type":"string","title":"Cohort"},"region":{"type":"string","title":"Region"},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N"},"base_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Base Rate"},"auroc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Auroc"},"intercept":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Intercept"},"coefficients_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coefficients Json"},"is_pooled_fallback":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Pooled Fallback"}},"type":"object","required":["workspace_id","outcome_key","cohort","region"],"title":"StratifiedFitRow"}}}} ``` ## The StrippedNonemptyString object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StrippedNonemptyString":{"type":"string","minLength":1}}}} ``` ## The SubToolLog object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SubToolLog":{"properties":{"tool_name":{"type":"string","title":"Tool Name","description":"Name of the tool that was invoked"},"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Input parameters passed to the tool"},"output":{"type":"string","title":"Output","description":"Raw output returned by the tool"},"duration_ms":{"type":"number","title":"Duration Ms","description":"Execution time in milliseconds"},"succeeded":{"type":"boolean","title":"Succeeded","description":"Whether the tool invocation succeeded"},"round":{"type":"integer","title":"Round","description":"Agent reasoning round in which the tool was called"}},"type":"object","required":["tool_name","input","output","duration_ms","succeeded","round"],"title":"SubToolLog"}}}} ``` ## The SubToolLogItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SubToolLogItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name","default":""},"input":{"additionalProperties":true,"type":"object","title":"Input"},"output":{"type":"string","title":"Output","default":""},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","title":"SubToolLogItem"}}}} ``` ## The SuggestionsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SuggestionsResponse":{"properties":{"suggestions":{"items":{"type":"string"},"type":"array","title":"Suggestions"}},"type":"object","required":["suggestions"],"title":"SuggestionsResponse"}}}} ``` ## The SurfaceErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceErrorResponse":{"properties":{"error_code":{"type":"string","maxLength":64,"title":"Error Code","description":"Machine-readable error code."},"message":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Message","description":"Human-readable error message. Omitted for token-validator errors that only carry ``reason``."},"reason":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Reason","description":"Debug detail from the token validator (e.g. ``token expired``)."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Optional structured validation details for 422 responses."}},"type":"object","required":["error_code"],"title":"SurfaceErrorResponse","description":"Error envelope returned by patient-facing surface JSON endpoints.\n\nFrontend (forms-app) reads ``error_code`` for branching and ``message``\nfor user-visible copy. ``reason`` is a debug-only field set by the token\nvalidator. ``details`` is set when a request body fails server-side\nvalidation."}}}} ``` ## The SurfaceField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"prefill_value":{"anyOf":[{},{"type":"null"}],"title":"Prefill Value"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"}},"type":"object","required":["key","label","field_type"],"title":"SurfaceField","description":"A single data collection field in a surface spec.\n\nGenerated by agents from HSM analysis. Each field maps\nto a specific piece of data the world model needs."},"NameString":{"type":"string","maxLength":256,"minLength":1},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The SurfaceListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SurfaceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"SurfaceListResponse"},"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"},"review_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Notes"},"reviewed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Reviewed By"},"reviewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed At"},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archived At"},"archive_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archive Reason"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The SurfaceProgressResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceProgressResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"total_fields":{"type":"integer","title":"Total Fields"},"filled_count":{"type":"integer","title":"Filled Count"},"empty_count":{"type":"integer","title":"Empty Count"},"filled_keys":{"items":{"type":"string"},"type":"array","title":"Filled Keys"},"empty_keys":{"items":{"type":"string"},"type":"array","title":"Empty Keys"},"required_empty_keys":{"items":{"type":"string"},"type":"array","title":"Required Empty Keys"}},"type":"object","required":["surface_id","total_fields","filled_count","empty_count","filled_keys","empty_keys","required_empty_keys"],"title":"SurfaceProgressResponse"}}}} ``` ## The SurfaceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"},"review_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Notes"},"reviewed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Reviewed By"},"reviewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed At"},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archived At"},"archive_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archive Reason"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The SurfaceSection object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceSection":{"properties":{"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["title","field_keys"],"title":"SurfaceSection","description":"A page/step in a multi-page surface form."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The SurfaceSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceSpec":{"properties":{"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"fields":{"items":{"$ref":"#/components/schemas/SurfaceField"},"type":"array","maxItems":200,"minItems":1,"title":"Fields"},"channel":{"$ref":"#/components/schemas/ChannelType","default":"web"},"expires_in_hours":{"type":"integer","maximum":8760,"minimum":1,"title":"Expires In Hours","default":168},"context":{"additionalProperties":true,"type":"object","title":"Context"},"resource_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Resource Type"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/SurfaceSection"},"type":"array"},{"type":"null"}],"title":"Sections"},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"}},"type":"object","required":["entity_id","title","fields"],"title":"SurfaceSpec","description":"A complete surface specification generated by an agent.\n\nThe agent reads the HSM (entity state, relationships,\nconfidence gaps) and produces this spec. The spec is stored as a\nworld.event and rendered by platform-api into a patient-facing page."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"SurfaceField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"prefill_value":{"anyOf":[{},{"type":"null"}],"title":"Prefill Value"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"}},"type":"object","required":["key","label","field_type"],"title":"SurfaceField","description":"A single data collection field in a surface spec.\n\nGenerated by agents from HSM analysis. Each field maps\nto a specific piece of data the world model needs."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."},"SurfaceSection":{"properties":{"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["title","field_keys"],"title":"SurfaceSection","description":"A page/step in a multi-page surface form."}}}} ``` ## The SurfaceSpecResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceSpecResponse":{"properties":{"surface_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Surface Id"},"entity_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Entity Id"},"status":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Status"},"spec":{"$ref":"#/components/schemas/PatientSurfaceSpec"},"saved_values":{"additionalProperties":true,"type":"object","title":"Saved Values"}},"type":"object","required":["spec"],"title":"SurfaceSpecResponse","description":"Surface render bundle returned to forms-app SSR."},"PatientSurfaceSpec":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Description"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields"},"sections":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Sections"},"branding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Branding"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"completion_title":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Context"}},"type":"object","title":"PatientSurfaceSpec","description":"Patient-facing surface spec — what forms-app renders.\n\nFree-form by design: ``fields``/``sections``/``branding`` are forwarded\nfrom the upstream surface document as raw dicts. Renamed from\n``SurfaceSpec`` to avoid an OpenAPI schema-name collision with\n``platform_lib.surfaces.models.SurfaceSpec`` (which would otherwise\nforce FastAPI to namespace both classes and rename the existing\n``SurfaceSpec`` schema in the committed openapi.json)."}}}} ``` ## The SurfaceStatus object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."}}}} ``` ## The SwitchChannelRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SwitchChannelRequest":{"properties":{"channel":{"$ref":"#/components/schemas/ChannelKind","description":"Target channel to move the conversation to (sms or imessage)."},"recipient":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}],"description":"Recipient address on the new channel (E.164). Required for sms/imessage."},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id","description":"Channel-manager use case for the new channel (resolves the sender). Required for sms/imessage."},"reason":{"$ref":"#/components/schemas/NameString","description":"Why the conversation is being moved (e.g. escalation, customer_request)."},"dispatch_opener":{"type":"boolean","title":"Dispatch Opener","description":"If true, immediately drive one agent turn on the new channel (e.g. 'I'll text you now').","default":false},"instruction":{"anyOf":[{"$ref":"#/components/schemas/BackgroundString"},{"type":"null"}],"description":"Optional context steering the opener when dispatch_opener=true."}},"type":"object","required":["channel","reason"],"title":"SwitchChannelRequest"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"NameString":{"type":"string","maxLength":256,"minLength":1},"BackgroundString":{"type":"string","maxLength":10000}}}} ``` ## The SwitchModeRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SwitchModeRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"participant_call_sid":{"type":"string","maxLength":64,"title":"Participant Call Sid","default":""},"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode"}},"type":"object","required":["call_sid","mode"],"title":"SwitchModeRequest","description":"Request to toggle operator mode on an active call."}}}} ``` ## The SwitchModeResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SwitchModeResponse":{"properties":{"mode":{"type":"string","enum":["listen","takeover"],"title":"Mode","description":"New operator mode"}},"type":"object","required":["mode"],"title":"SwitchModeResponse"}}}} ``` ## The SyncBatchRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SyncBatchRow":{"properties":{"batch_id":{"type":"string","format":"uuid","title":"Batch Id"},"dataset":{"type":"string","title":"Dataset"},"files_found":{"type":"integer","title":"Files Found"},"status":{"type":"string","title":"Status"}},"type":"object","required":["batch_id","dataset","files_found","status"],"title":"SyncBatchRow","description":"One batch produced by a source sync (one per mapped folder/dataset)."}}}} ``` ## The SyncFailureEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SyncFailureEntry":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"type":"string","title":"Event Type"},"fhir_resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Type"},"fhir_resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Resource Id"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["event_id","event_type","fhir_resource_type","fhir_resource_id","sync_error","created_at"],"title":"SyncFailureEntry"}}}} ``` ## The SyncHistoryEntry object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SyncHistoryEntry":{"properties":{"date":{"type":"string","title":"Date"},"event_count":{"type":"integer","title":"Event Count"},"synced_count":{"type":"integer","title":"Synced Count"},"failed_count":{"type":"integer","title":"Failed Count"}},"type":"object","required":["date","event_count","synced_count","failed_count"],"title":"SyncHistoryEntry"}}}} ``` ## The TMSMappingReleaseParams object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TMSMappingReleaseParams":{"properties":{"rule_kind":{"type":"string","const":"tms_mapping_release","title":"Rule Kind","default":"tms_mapping_release"},"reservation_window_hours":{"type":"integer","maximum":720,"minimum":0,"title":"Reservation Window Hours"},"weekend_skip":{"type":"boolean","title":"Weekend Skip","default":true}},"type":"object","required":["reservation_window_hours"],"title":"TMSMappingReleaseParams","description":"How long before a TMS mapping appointment its slot is released\nback to the pool. ``weekend_skip=True`` adds Saturday + Sunday days\nto the wall-clock countdown (clinic doesn't release on weekends)."}}}} ``` ## The TMSSessionGridParams object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TMSSessionGridParams":{"properties":{"rule_kind":{"type":"string","const":"tms_session_grid","title":"Rule Kind","default":"tms_session_grid"},"interval_minutes":{"type":"integer","maximum":120,"minimum":5,"title":"Interval Minutes"},"boundary_minutes":{"items":{"type":"integer"},"type":"array","maxItems":60,"minItems":1,"title":"Boundary Minutes"}},"type":"object","required":["interval_minutes","boundary_minutes"],"title":"TMSSessionGridParams","description":"TMS sessions only start at fixed minute-of-hour boundaries\n(e.g. ``:00`` and ``:30``) so the technician can run them\nback-to-back without gaps."}}}} ``` ## The TakeoverEligibility object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TakeoverEligibility":{"properties":{"eligible":{"type":"boolean","title":"Eligible"},"mode_options":{"items":{"type":"string","enum":["listen","takeover"]},"type":"array","title":"Mode Options","default":[]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["eligible"],"title":"TakeoverEligibility","description":"Whether an operator can take a run over, and how — the channel-neutral signal the\nconsole keys on instead of a per-channel heuristic.\n\n``eligible`` = an operator may take this run over right now. ``mode_options`` = the\ntakeover modes valid for the run's channel (voice exposes ``listen`` + ``takeover``;\nenumerated asynchronous channels expose authored-turn ``takeover`` only).\n``reason`` = a short, human-facing explanation when NOT eligible (e.g.\n``\"run is not live\"``, ``\"channel not yet supported\"``), so the console can\nrender an honest disabled-state tooltip rather than a bare greyed button.\nServer-computed (see ``Run.takeover``) so eligibility rules live in one place and the\nconsole never re-derives them."}}}} ``` ## The TargetSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TargetSpec":{"properties":{"desired_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Desired States"},"non_desired_states":{"items":{"$ref":"#/components/schemas/NonDesiredState"},"type":"array","maxItems":50,"title":"Non Desired States"},"ordered_pathways":{"items":{"$ref":"#/components/schemas/OrderedPathway"},"type":"array","maxItems":20,"title":"Ordered Pathways"},"completion_criteria":{"$ref":"#/components/schemas/CompletionCriteria"}},"type":"object","title":"TargetSpec"},"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"},"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"},"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"}}}} ``` ## The TestCallerNumbersRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestCallerNumbersRequest":{"properties":{"numbers":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Numbers"}},"type":"object","required":["numbers"],"title":"TestCallerNumbersRequest"}}}} ``` ## The TestCallerNumbersResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestCallerNumbersResponse":{"properties":{"numbers":{"items":{"type":"string"},"type":"array","title":"Numbers"}},"type":"object","required":["numbers"],"title":"TestCallerNumbersResponse"}}}} ``` ## The TestCredentialIdsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestCredentialIdsRequest":{"properties":{"credential_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"title":"Credential Ids"}},"type":"object","required":["credential_ids"],"title":"TestCredentialIdsRequest"}}}} ``` ## The TestCredentialIdsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestCredentialIdsResponse":{"properties":{"credential_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Credential Ids"}},"type":"object","required":["credential_ids"],"title":"TestCredentialIdsResponse"}}}} ``` ## The TestInvokeResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestInvokeResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"row_count":{"type":"integer","title":"Row Count","default":0},"status":{"type":"string","title":"Status","default":"pass"},"error":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Error"},"test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Test Duration Ms"}},"type":"object","title":"TestInvokeResponse","description":"Response shape for ``POST /v1/{ws}/functions/{name}/test``.\n\nStructural superset of :class:`InvokeResponse`. Adds ``status`` and\n``error`` so the DC can render the executor's failure detail inline\nrather than a generic \"Invocation failed.\" The underlying invoke\nuses the same path; ``status`` / ``error`` are filled in by\n``service.test`` after catching any ``HTTPException`` (503) from the\nexecutor, so the route never bubbles a 5xx for a logical SQL\nfailure — it's still a 200 with ``status=fail`` so the caller can\nshow the message.\n\nInvariant (enforced by :func:`_check_error_when_fail`):\n``status == \"fail\" → error is not None and len(error) > 0``."}}}} ``` ## The TestSkillRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestSkillRequest":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Input parameters to pass to the skill executor."},"static_tool_mocks":{"additionalProperties":{"$ref":"#/components/schemas/_ToolMockValue"},"propertyNames":{"$ref":"#/components/schemas/_ToolMockKey"},"type":"object","maxProperties":64,"title":"Static Tool Mocks","description":"Map of static tool name (max 128 chars) to mocked output string (max 16 KB). Up to 64 entries."}},"type":"object","required":["input"],"title":"TestSkillRequest"},"_ToolMockValue":{"type":"string","maxLength":16384},"_ToolMockKey":{"type":"string","maxLength":128,"minLength":1}}}} ``` ## The TestSkillResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TestSkillResponse":{"properties":{"result":{"type":"string","title":"Result","description":"Final result text produced by the skill"},"duration_ms":{"type":"number","title":"Duration Ms","description":"Total execution time in milliseconds"},"input_tokens":{"type":"integer","title":"Input Tokens","description":"Number of input tokens consumed"},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Number of output tokens generated"},"cached_tokens":{"type":"integer","title":"Cached Tokens","description":"Number of tokens served from cache"},"rounds":{"type":"integer","title":"Rounds","description":"Number of agent reasoning rounds executed"},"sub_tool_logs":{"items":{"$ref":"#/components/schemas/SubToolLog"},"type":"array","title":"Sub Tool Logs","description":"Chronological log of tool invocations"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the skill execution failed"}},"type":"object","required":["result","duration_ms","input_tokens","output_tokens","cached_tokens","rounds","sub_tool_logs"],"title":"TestSkillResponse"},"SubToolLog":{"properties":{"tool_name":{"type":"string","title":"Tool Name","description":"Name of the tool that was invoked"},"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Input parameters passed to the tool"},"output":{"type":"string","title":"Output","description":"Raw output returned by the tool"},"duration_ms":{"type":"number","title":"Duration Ms","description":"Execution time in milliseconds"},"succeeded":{"type":"boolean","title":"Succeeded","description":"Whether the tool invocation succeeded"},"round":{"type":"integer","title":"Round","description":"Agent reasoning round in which the tool was called"}},"type":"object","required":["tool_name","input","output","duration_ms","succeeded","round"],"title":"SubToolLog"}}}} ``` ## The ThinkingEffort object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ThinkingEffort":{"type":"string","enum":["low","medium","high"]}}}} ``` ## The ThroughputBucket object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ThroughputBucket":{"properties":{"bucket":{"type":"string","title":"Bucket"},"source_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source System"},"event_count":{"type":"integer","title":"Event Count"}},"type":"object","required":["bucket","event_count"],"title":"ThroughputBucket"}}}} ``` ## The TimelineActor object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TimelineActor":{"properties":{"kind":{"type":"string","enum":["agent","human","operator","system","tool"],"title":"Kind"},"role":{"type":"string","enum":["agent","caller","operator","runtime","state","tool"],"title":"Role"},"label":{"type":"string","title":"Label"},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Id"}},"type":"object","required":["kind","role","label"],"title":"TimelineActor"}}}} ``` ## The TimelineLaneDefinition object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TimelineLaneDefinition":{"properties":{"id":{"type":"string","maxLength":160,"minLength":1,"title":"Id","description":"Stable canonical lane id used by timeline visualizations. Segments attach via TimelineSegment.lane_id; consumers should not re-infer lanes from CSS or pixel positions."},"track":{"type":"string","enum":["agent","caller","operator","system","tool"],"title":"Track","description":"High-level actor-semantic track for styling and grouping."},"label":{"type":"string","title":"Label","description":"Display label for the lane."},"order":{"type":"integer","title":"Order","description":"Stable vertical order within the timeline lane model."},"actor":{"anyOf":[{"$ref":"#/components/schemas/TimelineActor"},{"type":"null"}],"description":"Actor represented by this lane when applicable."}},"type":"object","required":["id","track","label","order"],"title":"TimelineLaneDefinition"},"TimelineActor":{"properties":{"kind":{"type":"string","enum":["agent","human","operator","system","tool"],"title":"Kind"},"role":{"type":"string","enum":["agent","caller","operator","runtime","state","tool"],"title":"Role"},"label":{"type":"string","title":"Label"},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Id"}},"type":"object","required":["kind","role","label"],"title":"TimelineActor"}}}} ``` ## The TimelineSegment object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TimelineSegment":{"properties":{"type":{"type":"string","enum":["agent_speech","barge_in","caller_speech","filler_hesitation","filler_nav","greeting","interrupted_speech","processing_gap","silence","silence_check","state_transition","tool_call"],"title":"Type"},"lane":{"type":"string","enum":["agent","caller","events","operator","system","tool"],"title":"Lane"},"track":{"anyOf":[{"type":"string","enum":["agent","caller","operator","system","tool"]},{"type":"null"}],"title":"Track","description":"Actor-semantic display track for the segment. Inferred for legacy producers."},"lane_id":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Lane Id","description":"Canonical lane id. Must match PlaybackTimeline.lanes[].id after platform normalization."},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order","description":"Canonical event order after platform time/lane normalization."},"actor":{"anyOf":[{"$ref":"#/components/schemas/TimelineActor"},{"type":"null"}],"description":"Actor responsible for the segment. Inferred for legacy producers."},"start":{"type":"number","title":"Start"},"end":{"type":"number","title":"End"},"label":{"type":"string","title":"Label"},"turn_index":{"type":"integer","title":"Turn Index"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eot Confidence"},"audio_window_start":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window Start"},"audio_window_end":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window End"},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Render Ms"},"audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Ttfb Ms"},"e2e_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"E2E Ttfb Ms"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"parent_call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Call Id"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name"},"endpoint_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Name"},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"},"succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Succeeded"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"from_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From State"},"to_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To State"},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Valence"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"type":"object","required":["type","lane","start","end","label","turn_index"],"title":"TimelineSegment"},"TimelineActor":{"properties":{"kind":{"type":"string","enum":["agent","human","operator","system","tool"],"title":"Kind"},"role":{"type":"string","enum":["agent","caller","operator","runtime","state","tool"],"title":"Role"},"label":{"type":"string","title":"Label"},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Participant Id"}},"type":"object","required":["kind","role","label"],"title":"TimelineActor"}}}} ``` ## The TimelineTimebase object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TimelineTimebase":{"properties":{"unit":{"type":"string","const":"seconds","title":"Unit","description":"Timeline offsets are always seconds.","default":"seconds"},"origin":{"type":"string","enum":["media_start","call_start","synthetic"],"title":"Origin","description":"Zero point used for segment start/end offsets.","default":"media_start"},"start":{"type":"number","title":"Start","description":"Visible/canonical timeline range start in seconds.","default":0},"end":{"type":"number","title":"End","description":"Visible/canonical timeline range end in seconds.","default":0}},"type":"object","title":"TimelineTimebase"}}}} ``` ## The ToolCall object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolCall":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output"},"output_truncated":{"type":"boolean","title":"Output Truncated","default":false},"output_original_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Original Length"},"output_truncated_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Truncated To"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name"},"endpoint_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Name"},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"}},"type":"object","required":["tool_name"],"title":"ToolCall"}}}} ``` ## The ToolCallDetail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"input":{"type":"string","title":"Input","default":""},"result":{"type":"string","title":"Result","default":""},"call_id":{"type":"string","title":"Call Id","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","required":["tool_name"],"title":"ToolCallDetail","description":"Rich tool call data from a simulation step."}}}} ``` ## The ToolCallSpec object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."}}}} ``` ## The ToolCatalogResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolCatalogResponse":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/ResolvedToolItem"},"type":"array","title":"Tools"}},"type":"object","required":["tools"],"title":"ToolCatalogResponse"},"ResolvedToolItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"tool_type":{"type":"string","title":"Tool Type"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"states":{"items":{"type":"string"},"type":"array","title":"States"},"tier":{"type":"string","title":"Tier","default":"world"},"is_write":{"type":"boolean","title":"Is Write","default":false},"additional_instructions":{"additionalProperties":{"type":"string"},"type":"object","title":"Additional Instructions"}},"type":"object","required":["tool_name","tool_type"],"title":"ResolvedToolItem"}}}} ``` ## The ToolDescriptor object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolDescriptor":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}}},"type":"object","required":["name"],"title":"ToolDescriptor"}}}} ``` ## The ToolExecuteRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolExecuteRequest":{"properties":{"tool_type":{"type":"string","maxLength":64,"title":"Tool Type","description":"world_tool — other tool families use their dedicated endpoints"},"tool_name":{"$ref":"#/components/schemas/NameString","description":"Fully qualified tool name"},"service_id":{"type":"string","format":"uuid","title":"Service Id","description":"Service ID that owns the HSM"},"input_params":{"additionalProperties":true,"type":"object","title":"Input Params","description":"Parameters to pass to the tool handler"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"Optional entity ID for context"},"dry_run":{"type":"boolean","title":"Dry Run","description":"If true, write tools are simulated without persistence","default":false}},"type":"object","required":["tool_type","tool_name","service_id"],"title":"ToolExecuteRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The ToolExecuteResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolExecuteResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"dry_run":{"type":"boolean","title":"Dry Run","default":false},"source":{"type":"string","title":"Source","default":"tool_test"},"tool_type":{"type":"string","title":"Tool Type","default":""},"tier":{"type":"string","title":"Tier","default":"world"},"is_write":{"type":"boolean","title":"Is Write","default":false},"sub_tool_logs":{"items":{"$ref":"#/components/schemas/SubToolLogItem"},"type":"array","title":"Sub Tool Logs"},"blocked_side_effects":{"items":{"type":"string"},"type":"array","title":"Blocked Side Effects"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"ToolExecuteResponse"},"SubToolLogItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name","default":""},"input":{"additionalProperties":true,"type":"object","title":"Input"},"output":{"type":"string","title":"Output","default":""},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","title":"SubToolLogItem"}}}} ``` ## The ToolResolveResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolResolveResponse":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/ResolvedToolItem"},"type":"array","title":"Tools"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"}},"type":"object","required":["tools","service_id","workspace_id"],"title":"ToolResolveResponse"},"ResolvedToolItem":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"tool_type":{"type":"string","title":"Tool Type"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"states":{"items":{"type":"string"},"type":"array","title":"States"},"tier":{"type":"string","title":"Tier","default":"world"},"is_write":{"type":"boolean","title":"Is Write","default":false},"additional_instructions":{"additionalProperties":{"type":"string"},"type":"object","title":"Additional Instructions"}},"type":"object","required":["tool_name","tool_type"],"title":"ResolvedToolItem"}}}} ``` ## The ToolSummary object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolSummary":{"properties":{"total_calls":{"type":"integer","title":"Total Calls","description":"Total tool invocations","default":0},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful tool invocations","default":0},"failed":{"type":"integer","title":"Failed","description":"Failed tool invocations","default":0},"failure_rate":{"type":"number","title":"Failure Rate","description":"Tool failure rate 0.0 to 1.0","default":0}},"type":"object","title":"ToolSummary","description":"Tool usage statistics.\n\nFree-form residual on the raw ``tool_summary`` JSONB:\n``by_tool: list[{name, calls, succeeded, failed, avg_duration_ms}]``\n— per-tool breakdown. Not exposed via this typed shape."}}}} ``` ## The Tools object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Tools":{"properties":{"descriptors":{"items":{"$ref":"#/components/schemas/ToolDescriptor"},"type":"array","title":"Descriptors","default":[]},"read_tool_names":{"items":{"type":"string"},"type":"array","title":"Read Tool Names","default":[]},"write_tool_names":{"items":{"type":"string"},"type":"array","title":"Write Tool Names","default":[]}},"type":"object","title":"Tools","description":"Discovery hint — the neutral descriptors. NOT the enforcement (the MCP\nedge is; a remote agent discovers live schemas from the server too)."},"ToolDescriptor":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}}},"type":"object","required":["name"],"title":"ToolDescriptor"}}}} ``` ## The TraceAnalysisListItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TraceAnalysisListItem":{"properties":{"call_sid":{"type":"string","maxLength":128,"minLength":1,"title":"Call Sid","description":"Call identifier"},"call_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Call Entity Id","description":"Associated world.entities_synced call row UUID"},"outcome":{"anyOf":[{"type":"string","enum":["succeeded","partially","failed","abandoned"]},{"type":"null"}],"title":"Outcome","description":"Overall call outcome"},"summary":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Summary","description":"Short call summary"},"emotional_arc":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Emotional Arc","description":"Caller emotional trajectory string"},"key_moment_count":{"type":"integer","minimum":0,"title":"Key Moment Count","description":"Number of key moments identified","default":0},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At","description":"When the analysis was produced"}},"type":"object","required":["call_sid"],"title":"TraceAnalysisListItem","description":"Compact summary of a trace analysis row for list views."}}}} ``` ## The TraceAnalysisListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TraceAnalysisListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TraceAnalysisListItem"},"type":"array","title":"Items","description":"Trace analysis summaries"},"has_more":{"type":"boolean","title":"Has More","description":"Whether more rows are available beyond this page","default":false},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token","description":"Token to pass as ``continuation_token`` for the next page (None when exhausted)"}},"type":"object","title":"TraceAnalysisListResponse","description":"Paginated list response for trace analyses."},"TraceAnalysisListItem":{"properties":{"call_sid":{"type":"string","maxLength":128,"minLength":1,"title":"Call Sid","description":"Call identifier"},"call_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Call Entity Id","description":"Associated world.entities_synced call row UUID"},"outcome":{"anyOf":[{"type":"string","enum":["succeeded","partially","failed","abandoned"]},{"type":"null"}],"title":"Outcome","description":"Overall call outcome"},"summary":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Summary","description":"Short call summary"},"emotional_arc":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Emotional Arc","description":"Caller emotional trajectory string"},"key_moment_count":{"type":"integer","minimum":0,"title":"Key Moment Count","description":"Number of key moments identified","default":0},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At","description":"When the analysis was produced"}},"type":"object","required":["call_sid"],"title":"TraceAnalysisListItem","description":"Compact summary of a trace analysis row for list views."}}}} ``` ## The TraceAnalysisResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TraceAnalysisResponse":{"properties":{"call_sid":{"type":"string","maxLength":128,"minLength":1,"title":"Call Sid","description":"Call identifier (Twilio call SID or direct session ID)"},"status":{"type":"string","enum":["ready","pending","unavailable"],"title":"Status","description":"ready: analysis complete. pending: call completed, analysis processing. unavailable: analysis not possible for this call.","default":"ready"},"summary":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Summary","description":"2-3 sentence narrative of the call - the emotional story, not just what happened"},"outcome":{"anyOf":[{"type":"string","enum":["succeeded","partially","failed","abandoned"]},{"type":"null"}],"title":"Outcome","description":"Overall call outcome"},"key_moment_count":{"type":"integer","minimum":0,"title":"Key Moment Count","description":"Number of key decision moments identified (typically 3-8)","default":0},"key_moments":{"items":{"$ref":"#/components/schemas/TraceKeyMoment"},"type":"array","maxItems":100,"title":"Key Moments","description":"Key decision points with causal attribution to audio inputs"},"emotional_arc":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Emotional Arc","description":"Caller emotional trajectory as a readable sequence (e.g. 'curious -> confused -> frustrated -> relieved')"},"emotional_shifts":{"items":{"$ref":"#/components/schemas/EmotionalShift"},"type":"array","maxItems":100,"title":"Emotional Shifts","description":"Critical emotional state changes detected in the caller's voice"},"interaction_dynamics":{"anyOf":[{"$ref":"#/components/schemas/InteractionDynamics"},{"type":"null"}],"description":"System-level conversation flow analysis"},"coaching":{"items":{"$ref":"#/components/schemas/CoachingItem"},"type":"array","maxItems":50,"title":"Coaching","description":"Specific, actionable agent improvements tied to exact moments in this call"},"counterfactuals":{"items":{"$ref":"#/components/schemas/Counterfactual"},"type":"array","maxItems":50,"title":"Counterfactuals","description":"Alternative actions that would have meaningfully changed the outcome"},"deep_understanding":{"anyOf":[{"type":"string","maxLength":10000,"minLength":1},{"type":"null"}],"title":"Deep Understanding","description":"Synthesis of why this call went the way it did - combining audio perception with execution data"},"signal_response_alignment":{"items":{"$ref":"#/components/schemas/SignalResponseAlignment"},"type":"array","maxItems":50,"title":"Signal Response Alignment","description":"Per-signal alignment analysis: whether the agent's response matched each salient signal"},"missed_opportunities":{"items":{"type":"string","maxLength":2000,"minLength":1},"type":"array","maxItems":50,"title":"Missed Opportunities","description":"Moments where the agent could have taken a better action"},"emergent_patterns":{"items":{"type":"string","maxLength":2000,"minLength":1},"type":"array","maxItems":50,"title":"Emergent Patterns","description":"Cross-call or cross-turn patterns detected by the analysis"},"call_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Call Entity Id","description":"UUID string of the associated world.entities_synced call row (if resolved)"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At","description":"When the analysis was produced by the pipeline"}},"type":"object","required":["call_sid"],"title":"TraceAnalysisResponse","description":"Deep call understanding produced by the Amigo intelligence pipeline.\n\nAnalyzes the raw call audio to identify emotional dynamics, key decision\nmoments, and actionable coaching - understanding that exceeds what either\nparticipant had during the call itself.\n\n**Latency note**: This endpoint reads from the analytics data warehouse.\nExpect 500ms-2s response time, not sub-10ms like transactional endpoints."},"TraceKeyMoment":{"properties":{"timestamp_seconds":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Timestamp Seconds","description":"Approximate position in the recording (seconds from start)"},"what_happened":{"type":"string","maxLength":2000,"minLength":1,"title":"What Happened","description":"Plain-English description of the agent's decision"},"quality":{"anyOf":[{"type":"string","enum":["optimal","adequate","suboptimal"]},{"type":"null"}],"title":"Quality","description":"Assessment of the decision quality"},"reasoning":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Reasoning","description":"Why this was the right or wrong choice given the audio context"},"decision_factors":{"items":{"$ref":"#/components/schemas/DecisionFactor"},"type":"array","maxItems":20,"title":"Decision Factors","description":"Specific audio inputs that drove this decision"},"alternative":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Alternative","description":"What else the agent could have done and the likely outcome"}},"type":"object","required":["what_happened"],"title":"TraceKeyMoment","description":"A key decision point identified from the call audio."},"DecisionFactor":{"properties":{"factor":{"type":"string","maxLength":2000,"minLength":1,"title":"Factor","description":"What specifically drove this decision - exact words heard or tone described"},"source_type":{"type":"string","title":"Source Type","description":"Category of the audio input"}},"type":"object","required":["factor","source_type"],"title":"DecisionFactor","description":"A specific audio input that drove an agent decision."},"EmotionalShift":{"properties":{"timestamp_seconds":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Timestamp Seconds","description":"When the shift occurred (seconds from start)"},"from_state":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"From State","description":"Emotional state before the shift"},"to_state":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"To State","description":"Emotional state after the shift"},"trigger":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Trigger","description":"What caused the shift - exact words and tone"},"agent_awareness":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Agent Awareness","description":"Whether the agent noticed and responded to this shift"}},"type":"object","title":"EmotionalShift","description":"A critical emotional state change detected in the caller's voice."},"InteractionDynamics":{"properties":{"turn_taking_quality":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Turn Taking Quality","description":"How well speakers managed turn-taking - interruptions, overlaps, pacing"},"information_density":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Information Density","description":"Whether the agent gave too much or too little information per turn"},"repair_effectiveness":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Repair Effectiveness","description":"How misunderstandings were detected and resolved"},"rapport_trajectory":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Rapport Trajectory","description":"How the interpersonal dynamic evolved across the call"}},"type":"object","title":"InteractionDynamics","description":"System-level analysis of the conversation as a whole."},"CoachingItem":{"properties":{"moment_timestamp":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Moment Timestamp","description":"Position in the recording this coaching applies to (seconds)"},"observation":{"type":"string","maxLength":2000,"minLength":1,"title":"Observation","description":"What was observed in the audio at this moment"},"recommendation":{"type":"string","maxLength":2000,"minLength":1,"title":"Recommendation","description":"Specific improvement the agent should make"},"expected_impact":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Expected Impact","description":"How this improvement would change the interaction"}},"type":"object","required":["observation","recommendation"],"title":"CoachingItem","description":"A specific, actionable improvement tied to an exact moment in the call."},"Counterfactual":{"properties":{"timestamp_seconds":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Timestamp Seconds","description":"When the alternative action was available (seconds)"},"actual":{"type":"string","maxLength":2000,"minLength":1,"title":"Actual","description":"What the agent actually did"},"alternative":{"type":"string","maxLength":2000,"minLength":1,"title":"Alternative","description":"What it could have done instead"},"predicted_impact":{"type":"string","maxLength":2000,"minLength":1,"title":"Predicted Impact","description":"How the call would have gone differently"}},"type":"object","required":["actual","alternative","predicted_impact"],"title":"Counterfactual","description":"An alternative action that would have meaningfully changed the call outcome."},"SignalResponseAlignment":{"properties":{"signal":{"type":"string","maxLength":2000,"minLength":1,"title":"Signal","description":"The signal observed (e.g. caller tone shift, tool result, silence)"},"agent_response":{"type":"string","maxLength":2000,"minLength":1,"title":"Agent Response","description":"What the agent did in response"},"alignment":{"type":"string","enum":["aligned","misaligned","partial"],"title":"Alignment","description":"Whether the response was aligned, misaligned, or partial"},"insight":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Insight","description":"Short insight on why the alignment went the way it did"}},"type":"object","required":["signal","agent_response","alignment"],"title":"SignalResponseAlignment","description":"Whether the agent's response aligned with a salient signal in the call."}}}} ``` ## The TraceKeyMoment object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TraceKeyMoment":{"properties":{"timestamp_seconds":{"anyOf":[{"type":"number","maximum":86400,"minimum":0},{"type":"null"}],"title":"Timestamp Seconds","description":"Approximate position in the recording (seconds from start)"},"what_happened":{"type":"string","maxLength":2000,"minLength":1,"title":"What Happened","description":"Plain-English description of the agent's decision"},"quality":{"anyOf":[{"type":"string","enum":["optimal","adequate","suboptimal"]},{"type":"null"}],"title":"Quality","description":"Assessment of the decision quality"},"reasoning":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Reasoning","description":"Why this was the right or wrong choice given the audio context"},"decision_factors":{"items":{"$ref":"#/components/schemas/DecisionFactor"},"type":"array","maxItems":20,"title":"Decision Factors","description":"Specific audio inputs that drove this decision"},"alternative":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Alternative","description":"What else the agent could have done and the likely outcome"}},"type":"object","required":["what_happened"],"title":"TraceKeyMoment","description":"A key decision point identified from the call audio."},"DecisionFactor":{"properties":{"factor":{"type":"string","maxLength":2000,"minLength":1,"title":"Factor","description":"What specifically drove this decision - exact words heard or tone described"},"source_type":{"type":"string","title":"Source Type","description":"Category of the audio input"}},"type":"object","required":["factor","source_type"],"title":"DecisionFactor","description":"A specific audio input that drove an agent decision."}}}} ``` ## The TracesExportRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TracesExportRequest":{"properties":{"start_time":{"type":"string","format":"date-time","title":"Start Time","description":"Inclusive lower bound on span ``effective_at`` (ISO-8601)."},"end_time":{"type":"string","format":"date-time","title":"End Time","description":"Exclusive upper bound on span ``effective_at`` (ISO-8601)."},"limit":{"type":"integer","maximum":1000,"exclusiveMinimum":0,"title":"Limit","description":"Max spans per page (1-1000).","default":500},"continuation_token":{"title":"Continuation Token","description":"Opaque page cursor — round-trip the value from the previous response."}},"type":"object","required":["start_time","end_time"],"title":"TracesExportRequest"}}}} ``` ## The TracesExportResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TracesExportResponse":{"properties":{"resourceSpans":{"items":{"$ref":"#/components/schemas/ResourceSpans"},"type":"array","title":"Resourcespans","description":"OTLP/JSON ``ResourceSpans`` envelope (empty list when no spans match)."},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["resourceSpans","has_more"],"title":"TracesExportResponse","description":"Paginated PULL response — NOT a bare OTLP ``ExportTraceServiceRequest``.\n\n``resourceSpans`` is OTLP/JSON-conformant; to forward to an OTLP collector,\nextract ``.resourceSpans`` and re-wrap as ``{\"resourceSpans\": [...]}`` (a\nstrict protojson push receiver rejects the ``has_more``/``continuation_token``\nsiblings). Round-trip ``continuation_token`` to page."},"ResourceSpans":{"properties":{"resource":{"$ref":"#/components/schemas/Resource"},"scopeSpans":{"items":{"$ref":"#/components/schemas/ScopeSpans"},"type":"array","title":"Scopespans"}},"type":"object","required":["resource","scopeSpans"],"title":"ResourceSpans"},"Resource":{"properties":{"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"}},"type":"object","required":["attributes"],"title":"Resource"},"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"$ref":"#/components/schemas/AnyValue"}},"type":"object","required":["key","value"],"title":"KeyValue","description":"OTLP ``KeyValue`` attribute pair."},"AnyValue":{"additionalProperties":true,"type":"object"},"ScopeSpans":{"properties":{"scope":{"$ref":"#/components/schemas/InstrumentationScope"},"spans":{"items":{"$ref":"#/components/schemas/Span"},"type":"array","title":"Spans"}},"type":"object","required":["scope","spans"],"title":"ScopeSpans"},"InstrumentationScope":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"}},"type":"object","required":["name","version"],"title":"InstrumentationScope"},"Span":{"properties":{"traceId":{"type":"string","title":"Traceid"},"spanId":{"type":"string","title":"Spanid"},"name":{"type":"string","title":"Name"},"kind":{"type":"integer","title":"Kind"},"startTimeUnixNano":{"type":"string","title":"Starttimeunixnano"},"endTimeUnixNano":{"type":"string","title":"Endtimeunixnano"},"attributes":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Attributes"},"status":{"$ref":"#/components/schemas/Status"}},"type":"object","required":["traceId","spanId","name","kind","startTimeUnixNano","endTimeUnixNano","attributes","status"],"title":"Span","description":"OTLP ``Span`` in OTLP/JSON encoding (ids hex, timestamps decimal-string)."},"Status":{"properties":{"code":{"type":"integer","title":"Code"}},"type":"object","required":["code"],"title":"Status","description":"OTLP ``Status`` — 0=UNSET, 1=OK, 2=ERROR."}}}} ``` ## The TrajectoryStep object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TrajectoryStep":{"properties":{"seq":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seq"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind"},"actor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"tool_input_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Input Summary"},"tool_result_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Result Summary"},"tool_succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tool Succeeded"},"decision_from_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision From State"},"decision_to_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision To State"},"effective_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective At"}},"type":"object","title":"TrajectoryStep","description":"One structural step of a framework run's trajectory. Fields are best-effort\n(only those the step actually carries are present), all optional, and free ``str``\nfor the same read-model resilience the ``Run`` descriptive fields use."}}}} ``` ## The TranscriptSegment object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TranscriptSegment":{"properties":{"speaker_role":{"type":"string","title":"Speaker Role"},"transcript":{"type":"string","title":"Transcript"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"escalation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Id"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"}},"type":"object","required":["speaker_role","transcript","timestamp","escalation_id","confidence"],"title":"TranscriptSegment"}}}} ``` ## The TriggerFireResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerFireResponse":{"properties":{"fired_event_id":{"type":"string","format":"uuid","title":"Fired Event Id"},"trigger_id":{"type":"string","format":"uuid","title":"Trigger Id"},"status":{"type":"string","const":"fired","title":"Status","default":"fired"}},"type":"object","required":["fired_event_id","trigger_id"],"title":"TriggerFireResponse"}}}} ``` ## The TriggerListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TriggerResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"TriggerListResponse"},"TriggerResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name","description":"Trigger display name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description"},"event_type":{"type":"string","title":"Event Type","description":"Event type pattern to match"},"event_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Event Filter","description":"JSONPath filter on event data"},"action_id":{"type":"string","format":"uuid","title":"Action Id","description":"Action (skill) to invoke when fired"},"input_template":{"additionalProperties":true,"type":"object","title":"Input Template","description":"Input template merged with event data"},"schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule","description":"Cron schedule expression (e.g. '0 9 * * 1-5')"},"timezone":{"type":"string","title":"Timezone","description":"IANA timezone for schedule evaluation"},"next_fire_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Fire At","description":"Next scheduled fire time"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the trigger is active"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Entity ID of the creator"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the trigger was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the trigger was last updated"}},"type":"object","required":["id","workspace_id","name","event_type","action_id","input_template","timezone","is_active"],"title":"TriggerResponse"}}}} ``` ## The TriggerResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name","description":"Trigger display name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description"},"event_type":{"type":"string","title":"Event Type","description":"Event type pattern to match"},"event_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Event Filter","description":"JSONPath filter on event data"},"action_id":{"type":"string","format":"uuid","title":"Action Id","description":"Action (skill) to invoke when fired"},"input_template":{"additionalProperties":true,"type":"object","title":"Input Template","description":"Input template merged with event data"},"schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule","description":"Cron schedule expression (e.g. '0 9 * * 1-5')"},"timezone":{"type":"string","title":"Timezone","description":"IANA timezone for schedule evaluation"},"next_fire_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Fire At","description":"Next scheduled fire time"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the trigger is active"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Entity ID of the creator"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the trigger was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the trigger was last updated"}},"type":"object","required":["id","workspace_id","name","event_type","action_id","input_template","timezone","is_active"],"title":"TriggerResponse"}}}} ``` ## The TriggerRunListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerRunListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TriggerRunResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"TriggerRunListResponse"},"TriggerRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"trigger_id":{"type":"string","format":"uuid","title":"Trigger Id"},"fired_event_id":{"type":"string","format":"uuid","title":"Fired Event Id"},"source":{"type":"string","enum":["cron","manual","webhook","event"],"title":"Source","description":"Source that fired the trigger"},"input_override":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Override","description":"Per-run input overrides"},"status":{"type":"string","enum":["queued","running","succeeded","failed","dead"],"title":"Status","description":"Run status"},"attempt_count":{"type":"integer","title":"Attempt Count","description":"Number of claim attempts"},"max_attempts":{"type":"integer","title":"Max Attempts","description":"Maximum claim attempts before dead-lettering"},"next_attempt_at":{"type":"string","format":"date-time","title":"Next Attempt At","description":"Next eligible claim time"},"claimed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claimed By","description":"Dispatcher consumer that claimed the run"},"claimed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Claimed At","description":"When the run was claimed"},"lease_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Lease Expires At","description":"When the running lease expires"},"result_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Text","description":"Text result emitted by the action"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Failure detail, if any"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was enqueued"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the run row last changed"}},"type":"object","required":["id","workspace_id","trigger_id","fired_event_id","source","status","attempt_count","max_attempts","next_attempt_at","created_at","updated_at"],"title":"TriggerRunResponse"}}}} ``` ## The TriggerRunResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"trigger_id":{"type":"string","format":"uuid","title":"Trigger Id"},"fired_event_id":{"type":"string","format":"uuid","title":"Fired Event Id"},"source":{"type":"string","enum":["cron","manual","webhook","event"],"title":"Source","description":"Source that fired the trigger"},"input_override":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Override","description":"Per-run input overrides"},"status":{"type":"string","enum":["queued","running","succeeded","failed","dead"],"title":"Status","description":"Run status"},"attempt_count":{"type":"integer","title":"Attempt Count","description":"Number of claim attempts"},"max_attempts":{"type":"integer","title":"Max Attempts","description":"Maximum claim attempts before dead-lettering"},"next_attempt_at":{"type":"string","format":"date-time","title":"Next Attempt At","description":"Next eligible claim time"},"claimed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claimed By","description":"Dispatcher consumer that claimed the run"},"claimed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Claimed At","description":"When the run was claimed"},"lease_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Lease Expires At","description":"When the running lease expires"},"result_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Text","description":"Text result emitted by the action"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Failure detail, if any"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was enqueued"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the run row last changed"}},"type":"object","required":["id","workspace_id","trigger_id","fired_event_id","source","status","attempt_count","max_attempts","next_attempt_at","created_at","updated_at"],"title":"TriggerRunResponse"}}}} ``` ## The TriggerSyncConflictDetails object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerSyncConflictDetails":{"properties":{"last_poll_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Poll At"},"last_poll_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Poll Duration Ms"}},"type":"object","title":"TriggerSyncConflictDetails","description":"Operational fields included in a 409 to power UI affordances like\n\"syncing for 30s\" — strict allowlist, never the whole status entry."}}}} ``` ## The TriggerSyncConflictResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerSyncConflictResponse":{"properties":{"message":{"type":"string","title":"Message"},"details":{"$ref":"#/components/schemas/TriggerSyncConflictDetails"}},"type":"object","required":["message","details"],"title":"TriggerSyncConflictResponse","description":"Body shape for the 409 returned by POST /sync when the source is\nalready mid-poll. Documented in OpenAPI so SDK consumers get a typed\nAlreadySyncing error instead of an opaque blob."},"TriggerSyncConflictDetails":{"properties":{"last_poll_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Poll At"},"last_poll_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Poll Duration Ms"}},"type":"object","title":"TriggerSyncConflictDetails","description":"Operational fields included in a 409 to power UI affordances like\n\"syncing for 30s\" — strict allowlist, never the whole status entry."}}}} ``` ## The TriggerSyncResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerSyncResponse":{"properties":{"status":{"type":"string","const":"started","title":"Status"},"data_source_id":{"type":"string","format":"uuid","title":"Data Source Id"},"triggered_at":{"type":"string","format":"date-time","title":"Triggered At"}},"type":"object","required":["status","data_source_id","triggered_at"],"title":"TriggerSyncResponse"}}}} ``` ## The TriggerableEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerableEvent":{"type":"string","enum":["amigo.trigger.cron","appointment.booked","appointment.cancelled","appointment.confirmed","booking.requested","call.ended","call.intelligence","call.outcome","channel.message.received","conversation.channel_switched","conversation.started","conversation.turn_recorded","coverage.created","entity.enriched","entity.resolved","medication.refill_requested","outbound.initiated","outbound.scheduled","patient.created","patient.updated","relationship.established","review.approve","review.correct","review.reject","surface.created","surface.submitted","ticket.created","triage.completed","trigger.completed","trigger.failed","trigger.fired"],"title":"TriggerableEvent","description":"Closed set of world events that trigger definitions may subscribe to.\n\nThe database column intentionally remains text for compatibility with old\nrows, but API writes must choose from this list so typoed event names do\nnot silently create never-matching triggers."}}}} ``` ## The Turn object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"Turn":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string"},{"type":"null"}],"title":"Id"},"trigger":{"type":"string","title":"Trigger","default":""},"user_transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Transcript"},"agent_transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Transcript"},"agent_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Action"},"interrupted":{"type":"boolean","title":"Interrupted","default":false},"filler_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filler Type"},"speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker Id"},"speaker_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker Role"},"emotion_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emotion Label"},"emotion_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Emotion Valence"},"compound_emotions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Compound Emotions"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eot Confidence"},"state":{"type":"string","title":"State","default":""},"tool_calls":{"items":{"$ref":"#/components/schemas/ToolCall"},"type":"array","title":"Tool Calls","default":[]},"state_transitions":{"items":{"$ref":"#/components/schemas/StateTransition"},"type":"array","title":"State Transitions","default":[]},"inner_thoughts":{"items":{"type":"string"},"type":"array","title":"Inner Thoughts","default":[]},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp"},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"user_speech_start_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"User Speech Start Ms"},"user_speech_end_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"User Speech End Ms"},"agent_speech_start_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Speech Start Ms"},"agent_speech_end_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Agent Speech End Ms"},"audio_window_start_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window Start Ms"},"audio_window_end_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Window End Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"render_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Render Ms"},"audio_ttfb_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Ttfb Ms"},"signal_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Kind"},"signal_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Source"},"state_before":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Before"},"state_after":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State After"},"primary_effect_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Effect Kind"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"},"tool_succeeded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tool Succeeded"},"tool_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tool Ms"},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality"},"empathy_tier":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Tier"},"decision_bearing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Decision Bearing"}},"type":"object","title":"Turn"},"ToolCall":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output"},"output_truncated":{"type":"boolean","title":"Output Truncated","default":false},"output_original_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Original Length"},"output_truncated_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Truncated To"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name"},"endpoint_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Name"},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"}},"type":"object","required":["tool_name"],"title":"ToolCall"},"StateTransition":{"properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"previous_state":{"type":"string","title":"Previous State","default":""},"next_state":{"type":"string","title":"Next State","default":""},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"},"from_state":{"type":"string","title":"From State","readOnly":true},"to_state":{"type":"string","title":"To State","readOnly":true}},"type":"object","required":["from_state","to_state"],"title":"StateTransition"}}}} ``` ## The TurnConversationSnapshot object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnConversationSnapshot":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed","paused"],"title":"Status"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"updated_at":{"type":"string","title":"Updated At"},"context_graph_state":{"anyOf":[{"$ref":"#/components/schemas/ContextGraphState-Output"},{"type":"null"}]}},"type":"object","required":["id","status","updated_at"],"title":"TurnConversationSnapshot"},"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."}}}} ``` ## The TurnDelivery object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnDelivery":{"properties":{"delivery_id":{"type":"string","format":"uuid","title":"Delivery Id","description":"Stable identifier for this background delivery."},"request_id":{"type":"string","format":"uuid","title":"Request Id","description":"Stable poll request identifier bound to this claim."},"receipt":{"type":"string","format":"uuid","title":"Receipt","description":"Opaque receipt required to acknowledge this delivery."}},"type":"object","required":["delivery_id","request_id","receipt"],"title":"TurnDelivery"}}}} ``` ## The TurnDeliveryAckRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnDeliveryAckRequest":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"receipt":{"type":"string","format":"uuid","title":"Receipt"}},"additionalProperties":false,"type":"object","required":["request_id","receipt"],"title":"TurnDeliveryAckRequest"}}}} ``` ## The TurnPolicy object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnPolicy":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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)."}}}} ``` ## The TurnRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnRequest":{"properties":{"message":{"type":"string","maxLength":10000,"title":"Message","default":""},"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","maxItems":20},{"type":"null"}],"title":"Content"},"media_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Media Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"context":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Context","description":"Injected into the agent's prompt as caller/patient context for this turn."},"viewport_width":{"anyOf":[{"type":"integer","maximum":500,"minimum":20},{"type":"null"}],"title":"Viewport Width"},"viewport_height":{"anyOf":[{"type":"integer","maximum":500,"minimum":5},{"type":"null"}],"title":"Viewport Height"},"wait_for_final":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Wait For Final","description":"Synchronous callers only: when a turn hands work to a background tool (``background_pending``), await the real answer inline (bounded, ~30s) instead of returning the acknowledgement immediately. On completion the response carries the final answer with ``background_pending=false``; on timeout it returns ``background_pending=true`` — resolve it later with ``poll=true``. ``null`` (default) inherits the channel policy (web = do not wait). Ignored with ``poll=true`` (422)."},"suppress_filler":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Suppress Filler","description":"Synchronous callers only: when a turn ends ``background_pending``, omit the filler/acknowledgement text from ``output`` so a batch caller never mistakes the ack for the answer (``output`` is empty; ``background_pending=true`` is the poll-later signal). ``null`` (default) inherits the channel policy. Ignored with ``poll=true`` (422)."}},"type":"object","title":"TurnRequest"},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."}}}} ``` ## The TurnResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnResponse":{"properties":{"turn_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Turn Id","description":"Identifier of the user exchange this turn created — or, for ``poll=true`` and greeting-kickoff turns (empty ``message``), the exchange the returned messages attach to. A background delivery keeps the originating exchange even when later user turns already exist. Deterministic: matches the ``turn_id`` on this conversation's history turns, so it can anchor durable per-turn artifacts (e.g. feedback) across page reloads. Null only when the conversation has no user exchange yet (a poll or kickoff before the first user message)."},"input":{"$ref":"#/components/schemas/ConversationTurn"},"output":{"items":{"$ref":"#/components/schemas/ConversationTurn"},"type":"array","title":"Output"},"tool_calls":{"items":{"$ref":"#/components/schemas/ConversationToolCallDetail"},"type":"array","title":"Tool Calls","default":[]},"artifacts":{"items":{"$ref":"#/components/schemas/ClientArtifact"},"type":"array","title":"Artifacts","default":[]},"conversation":{"$ref":"#/components/schemas/TurnConversationSnapshot"},"background_pending":{"type":"boolean","title":"Background Pending","description":"Whether this turn's ``output`` is the final answer, or only an acknowledgement that\nwork is still running in the background.\n\n``false`` (default): ``output`` is the complete agent response for this turn.\n\n``true``: a tool crossed the server's blocking window and was handed to a background\ntask, so ``output`` is NOT the final answer — the definitive assistant answer is\nproduced later, out-of-band. Under delivery protocol v2, collect it by re-issuing\n``POST …/turns`` with ``poll=true`` (a no-message, receipt-backed claim), render or\ndurably persist the returned answer, then acknowledge its exact delivery receipt.\nThis is the per-conversation delivery contract — see\nthe web-integration paved path. (The workspace observer bus,\n``GET /v1/{workspace_id}/events/stream``, mirrors this activity as ``text.agent_message``\n/ ``text.tool_started`` / ``text.background_result`` for *dashboards* watching many\nconversations, but is not the per-chat delivery path.) A client that treats a\n``background_pending=true`` turn as complete without polling and acknowledging will\nmiss the final answer.","default":false},"delivery":{"anyOf":[{"$ref":"#/components/schemas/TurnDelivery"},{"type":"null"}],"description":"Receipt for a background result returned by ``poll=true``. Render the response successfully, then acknowledge this delivery. Null for ordinary turns and idle/pending polls."},"delivery_protocol_version":{"anyOf":[{"type":"integer","const":2},{"type":"null"}],"title":"Delivery Protocol Version","description":"Version of the durable background-delivery protocol supported by the serving agent. Clients may retry polls only after observing version 2."}},"type":"object","required":["turn_id","input","output","conversation"],"title":"TurnResponse"},"ConversationTurn":{"properties":{"turn_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Turn Id","description":"Stable identifier of the user exchange this message belongs to, derived deterministically from (conversation_id, turn_index) — identical across ``POST /turns`` responses and re-reads of the conversation history. User and agent messages from the same exchange share this value. Null on messages that precede the first user turn (proactive greetings, channel-event preludes)."},"turn_index":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Turn Index","description":"Zero-based ordinal of the user exchange this message belongs to (0 = first user turn). Derived server-side from the conversation's user-turn count — never stored. Null exactly when ``turn_id`` is null."},"role":{"type":"string","enum":["agent","user","system"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelKind"},{"type":"null"}],"description":"Channel this turn occurred on. A conversation that switched channels has a self-describing per-turn history; null on turns written before per-turn attribution or on channel-less internal turns."},"content":{"items":{"$ref":"#/components/schemas/ContentPartPayload"},"type":"array","title":"Content","default":[]},"tool_calls":{"items":{"$ref":"#/components/schemas/ConversationToolCallDetail"},"type":"array","title":"Tool Calls","description":"Tool calls executed during this (agent) turn. Populated only when the request opts in via ``include_tool_calls=true``; empty otherwise and on turns that did not invoke tools.","default":[]},"artifacts":{"items":{"$ref":"#/components/schemas/ClientArtifact"},"type":"array","title":"Artifacts","description":"Validated client-safe outputs produced during this agent turn.","default":[]},"selected_action_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action Description","description":"Description of the context-graph action selected for this turn. Null means no action was selected or no selected action was recorded."},"state_transition":{"anyOf":[{"$ref":"#/components/schemas/ConversationTurnStateTransition"},{"type":"null"}],"description":"Context-graph state transition that occurred during this turn. Null means no transition took place or no transition was recorded. Deprecated: use state_transitions instead. If multiple transitions were recorded, this field reports the first source state and final destination state.","deprecated":true},"state_transitions":{"items":{"$ref":"#/components/schemas/ConversationTurnStateTransition"},"type":"array","title":"State Transitions","description":"Ordered context-graph state transitions that occurred during this turn.","default":[]},"available_actions":{"items":{"$ref":"#/components/schemas/ConversationTurnAvailableAction"},"type":"array","title":"Available Actions","description":"Action choices available in the turn's resolved context-graph state. Empty when actions cannot be resolved or the resolved state is not an action state.","default":[]}},"type":"object","required":["role","text"],"title":"ConversationTurn"},"ChannelKind":{"type":"string","enum":["voice","sms","whatsapp","email","web","imessage"],"title":"ChannelKind","description":"HSM execution channel type.\n\nDetermines how the HSM engine communicates with end users.\nEach kind maps to one or more providers."},"ContentPartPayload":{"properties":{"type":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9._-]*$","title":"Type","default":"text"},"text":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"media_type":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Media Type"},"provider_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Provider Id"},"metadata":{"additionalProperties":true,"type":"object","maxProperties":50,"title":"Metadata"}},"type":"object","title":"ContentPartPayload","description":"HTTP/WebSocket shape for a modality-neutral conversation content part."},"ConversationToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"call_id":{"type":"string","title":"Call Id"},"input":{"additionalProperties":true,"type":"object","title":"Input"},"result":{"type":"string","title":"Result","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true},"duration_ms":{"anyOf":[{"type":"number","maximum":3600000,"minimum":0},{"type":"null"}],"title":"Duration Ms","description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Omitted (null) on legacy turns that did not capture timing."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Failure detail recorded for the tool call when ``succeeded`` is false. Null on successful calls or when no message was captured."}},"type":"object","required":["tool_name","call_id"],"title":"ConversationToolCallDetail"},"ClientArtifact":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"payload":{"$ref":"#/components/schemas/ClientArtifactPayload"}},"type":"object","required":["type","schema_version","payload"],"title":"ClientArtifact","description":"A versioned JSON payload that a client can render as a product component."},"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]},"ConversationTurnStateTransition":{"properties":{"from":{"type":"string","title":"From","description":"Source context-graph state before the turn's state transition."},"to":{"type":"string","title":"To","description":"Destination context-graph state after the turn's state transition."}},"type":"object","required":["from","to"],"title":"ConversationTurnStateTransition"},"ConversationTurnAvailableAction":{"properties":{"description":{"type":"string","title":"Description","description":"Human-readable description of an action available in the turn's state."}},"type":"object","required":["description"],"title":"ConversationTurnAvailableAction"},"TurnConversationSnapshot":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","enum":["active","closed","completed","in-progress","failed","paused"],"title":"Status"},"turn_count":{"type":"integer","title":"Turn Count","default":0},"updated_at":{"type":"string","title":"Updated At"},"context_graph_state":{"anyOf":[{"$ref":"#/components/schemas/ContextGraphState-Output"},{"type":"null"}]}},"type":"object","required":["id","status","updated_at"],"title":"TurnConversationSnapshot"},"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":[]},"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","ephemeral"],"title":"Result Persistence","description":"How this tool call's arguments and result are retained. 'ephemeral' is fail-closed: Platform API authoring must be enabled for the workspace, and Agent Engine honors it only on the inline text/simulation path — voice, background, and external-realtime sessions reject an ephemeral graph at init rather than journal it.","default":"accumulate"},"delivery":{"type":"string","enum":["interrupt","queue"],"title":"Delivery","default":"interrupt"},"failure_delivery":{"anyOf":[{"type":"string","enum":["interrupt","queue"]},{"type":"null"}],"title":"Failure Delivery"},"failure_delivery_by_class":{"anyOf":[{"additionalProperties":{"type":"string","enum":["interrupt","queue"]},"propertyNames":{"$ref":"#/components/schemas/FailureClass"},"type":"object"},{"type":"null"}],"title":"Failure Delivery By Class"},"execution":{"type":"string","enum":["blocking","background"],"title":"Execution","default":"blocking"},"lifecycle":{"type":"string","enum":["coupled","independent"],"title":"Lifecycle","default":"independent"},"context_bindings":{"items":{"type":"string"},"type":"array","title":"Context Bindings"},"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."},"FailureClass":{"type":"string","enum":["timeout","input_rejected","rounds_exhausted","generic"],"title":"FailureClass","description":"Why a tool result is a failure — produced by the executor at RUN time.\n\nUnlike ``ResultDelivery`` (a fixed config-time axis), this is a runtime\nclassification the executor knows at the moment of failure. It flavors the\nagent-facing failure wording and the world-event / status-tool observability,\nand it is ALSO an optional routing key: a state x tool binding may set\n``ToolCallSpec.failure_delivery_by_class`` to deliver differently per class\n(e.g. interrupt on timeout, queue on a generic error). With no per-class map\n(the default), failed results route by the ``failure_delivery`` floor,\nunchanged. Add a member only in the same change that wires a producer for it —\nadding one also widens the per-class routing surface, so it must be a\ndeliberate, produced class."},"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},"safety_response":{"type":"string","enum":["suspend_forward","stay_empathize","alert"],"title":"Safety Response","default":"stay_empathize"},"context_strategy":{"type":"string","enum":["full","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."},"TurnDelivery":{"properties":{"delivery_id":{"type":"string","format":"uuid","title":"Delivery Id","description":"Stable identifier for this background delivery."},"request_id":{"type":"string","format":"uuid","title":"Request Id","description":"Stable poll request identifier bound to this claim."},"receipt":{"type":"string","format":"uuid","title":"Receipt","description":"Opaque receipt required to acknowledge this delivery."}},"type":"object","required":["delivery_id","request_id","receipt"],"title":"TurnDelivery"}}}} ``` ## The TurnTimeline object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnTimeline":{"properties":{"turn_index":{"type":"integer","title":"Turn Index"},"seek_to":{"type":"number","title":"Seek To"},"active_start":{"type":"number","title":"Active Start"},"active_end":{"type":"number","title":"Active End"}},"type":"object","required":["turn_index","seek_to","active_start","active_end"],"title":"TurnTimeline"}}}} ``` ## The UpdateAgentRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateAgentRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]}},"type":"object","title":"UpdateAgentRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The UpdateContextGraphRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"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}}}} ``` ## The UpdateDashboardRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateDashboardRequest":{"properties":{"slug":{"anyOf":[{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9\\-]*$"},{"type":"null"}],"title":"Slug"},"title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"page_context":{"anyOf":[{"type":"string","enum":["home","patients","calls","data","analytics","pipeline","operators","surfaces","compliance","custom"]},{"type":"null"}],"title":"Page Context"},"panels":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":50},{"type":"null"}],"title":"Panels"},"filters":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":20},{"type":"null"}],"title":"Filters"},"refresh_interval":{"anyOf":[{"type":"integer","maximum":86400,"minimum":10},{"type":"null"}],"title":"Refresh Interval"}},"type":"object","title":"UpdateDashboardRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}}} ``` ## The UpdateDataSourceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateDataSourceRequest":{"properties":{"display_name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"connection_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Connection Config"},"entity_types":{"anyOf":[{"items":{"type":"string","maxLength":64,"minLength":1},"type":"array","maxItems":100},{"type":"null"}],"title":"Entity Types"},"field_mappings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Field Mappings"},"sync_strategy":{"anyOf":[{"type":"string","enum":["manual","scheduled","webhook","continuous"]},{"type":"null"}],"title":"Sync Strategy"},"sync_schedule":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Sync Schedule"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"UpdateDataSourceRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1}}}} ``` ## The UpdateOperatorRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateOperatorRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"type":{"anyOf":[{"type":"string","enum":["clinical","administrative","crisis_counselor"]},{"type":"null"}],"title":"Type"},"skills":{"anyOf":[{"items":{"type":"string","maxLength":64,"minLength":1},"type":"array","maxItems":50},{"type":"null"}],"title":"Skills"},"connection_method":{"anyOf":[{"type":"string","enum":["browser","phone"]},{"type":"null"}],"title":"Connection Method"},"phone_number":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"role":{"anyOf":[{"type":"string","enum":["operator","supervisor","admin"]},{"type":"null"}],"title":"Role"},"status":{"anyOf":[{"type":"string","enum":["online","busy","offline"]},{"type":"null"}],"title":"Status"}},"type":"object","title":"UpdateOperatorRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"PhoneE164":{"type":"string","maxLength":16,"minLength":2}}}} ``` ## The UpdateProductionEvalDefinitionRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateProductionEvalDefinitionRequest":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"eval_key":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Eval Key"},"eval_type":{"anyOf":[{"type":"string","enum":["assertion","metric"]},{"type":"null"}],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"expected":{"title":"Expected"},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Params"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"}},"type":"object","title":"UpdateProductionEvalDefinitionRequest"}}}} ``` ## The UpdateSchedulingRuleSetRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateSchedulingRuleSetRequest":{"properties":{"params":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/ClinicOpenHoursParams"},{"$ref":"#/components/schemas/TMSMappingReleaseParams"},{"$ref":"#/components/schemas/TMSSessionGridParams"},{"$ref":"#/components/schemas/KetamineBlockOverlapParams"},{"$ref":"#/components/schemas/NinetyDayRollingParams"},{"$ref":"#/components/schemas/ConcurrentStartBlockParams"}],"discriminator":{"propertyName":"rule_kind","mapping":{"clinic_open_hours":"#/components/schemas/ClinicOpenHoursParams","concurrent_start_block":"#/components/schemas/ConcurrentStartBlockParams","ketamine_block_overlap":"#/components/schemas/KetamineBlockOverlapParams","ninety_day_rolling":"#/components/schemas/NinetyDayRollingParams","tms_mapping_release":"#/components/schemas/TMSMappingReleaseParams","tms_session_grid":"#/components/schemas/TMSSessionGridParams"}}},{"type":"null"}],"title":"Params"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"UpdateSchedulingRuleSetRequest","description":"Partial update — fields not provided are unchanged. ``params``\nmust be the full per-kind shape (no patch within params); send the\nwhole RuleParams or omit."},"ClinicOpenHoursParams":{"properties":{"rule_kind":{"type":"string","const":"clinic_open_hours","title":"Rule Kind","default":"clinic_open_hours"},"timezone":{"type":"string","maxLength":64,"minLength":1,"title":"Timezone"},"monday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"tuesday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"wednesday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"thursday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"friday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"saturday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]},"sunday":{"anyOf":[{"$ref":"#/components/schemas/_DayHours"},{"type":"null"}]}},"type":"object","required":["timezone"],"title":"ClinicOpenHoursParams","description":"Workspace clinic open-hours by weekday.\n\nDays not present mean \"closed.\" Used by the rules engine to skip\nslots outside open hours and (combined with ``weekend_skip``) by the\nTMS-mapping release calculator."},"_DayHours":{"properties":{"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"Start"},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"End"}},"type":"object","required":["start","end"],"title":"_DayHours","description":"Open-hours window for one weekday. Times in 24h ``HH:MM`` form,\ninterpreted in the rule set's ``timezone``."},"TMSMappingReleaseParams":{"properties":{"rule_kind":{"type":"string","const":"tms_mapping_release","title":"Rule Kind","default":"tms_mapping_release"},"reservation_window_hours":{"type":"integer","maximum":720,"minimum":0,"title":"Reservation Window Hours"},"weekend_skip":{"type":"boolean","title":"Weekend Skip","default":true}},"type":"object","required":["reservation_window_hours"],"title":"TMSMappingReleaseParams","description":"How long before a TMS mapping appointment its slot is released\nback to the pool. ``weekend_skip=True`` adds Saturday + Sunday days\nto the wall-clock countdown (clinic doesn't release on weekends)."},"TMSSessionGridParams":{"properties":{"rule_kind":{"type":"string","const":"tms_session_grid","title":"Rule Kind","default":"tms_session_grid"},"interval_minutes":{"type":"integer","maximum":120,"minimum":5,"title":"Interval Minutes"},"boundary_minutes":{"items":{"type":"integer"},"type":"array","maxItems":60,"minItems":1,"title":"Boundary Minutes"}},"type":"object","required":["interval_minutes","boundary_minutes"],"title":"TMSSessionGridParams","description":"TMS sessions only start at fixed minute-of-hour boundaries\n(e.g. ``:00`` and ``:30``) so the technician can run them\nback-to-back without gaps."},"KetamineBlockOverlapParams":{"properties":{"rule_kind":{"type":"string","const":"ketamine_block_overlap","title":"Rule Kind","default":"ketamine_block_overlap"},"window_days":{"type":"integer","maximum":365,"minimum":1,"title":"Window Days"}},"type":"object","required":["window_days"],"title":"KetamineBlockOverlapParams","description":"How many days after a ketamine session to block follow-up\nappointments (clinical safety window)."},"NinetyDayRollingParams":{"properties":{"rule_kind":{"type":"string","const":"ninety_day_rolling","title":"Rule Kind","default":"ninety_day_rolling"},"days":{"type":"integer","maximum":365,"minimum":1,"title":"Days"}},"type":"object","required":["days"],"title":"NinetyDayRollingParams","description":"Rolling-window cap on appointments per patient (e.g. 90 days\nbetween TMS sessions)."},"ConcurrentStartBlockParams":{"properties":{"rule_kind":{"type":"string","const":"concurrent_start_block","title":"Rule Kind","default":"concurrent_start_block"}},"type":"object","title":"ConcurrentStartBlockParams","description":"Disallow two slots starting at the same time within a TMS scope.\nNo additional params — the discriminator is the whole config."}}}} ``` ## The UpdateServiceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateServiceRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id"},"context_graph_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Context Graph Id"},"keyterms":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1},"type":"array","maxItems":500},{"type":"null"}],"title":"Keyterms"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"},"version_sets":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/VersionSet-Input"},"type":"object"},{"type":"null"}],"title":"Version Sets"},"tags":{"anyOf":[{"items":{"$ref":"#/components/schemas/ServiceTag"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tags"},"tool_capacity":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"title":"Tool Capacity"},"channel_type":{"anyOf":[{"type":"string","enum":["voice","text"]},{"type":"null"}],"title":"Channel Type"},"environment":{"anyOf":[{"type":"string","enum":["sandbox","production"]},{"type":"null"}],"title":"Environment"},"voice_config":{"anyOf":[{"$ref":"#/components/schemas/ServiceVoiceConfig-Input"},{"type":"null"}]},"accepted_context":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContextKeySpec"},"type":"array","maxItems":100},{"type":"null"}],"title":"Accepted Context"}},"type":"object","title":"UpdateServiceRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"VersionSet-Input":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."},"ServiceTag":{"properties":{"key":{"type":"string","title":"Key"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"}},"type":"object","required":["key"],"title":"ServiceTag"},"ServiceVoiceConfig-Input":{"properties":{"tts_model":{"anyOf":[{"type":"string","enum":["sonic-turbo","sonic-3"]},{"type":"null"}],"title":"Tts Model"},"max_buffer_delay_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Buffer Delay Ms"},"eager_eot_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eager Eot Threshold"},"eot_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Eot Timeout Ms"},"filler_style":{"type":"string","enum":["backchannel","phrase","silent"],"title":"Filler Style","default":"backchannel"},"filler_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Filler Vocabulary"},"backchannel_delay_ms":{"type":"integer","title":"Backchannel Delay Ms","default":400},"max_response_sentences":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Sentences"},"max_response_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Response Words"},"barge_in_min_speech_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Min Speech S"},"barge_in_cooldown_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Barge In Cooldown S"},"min_tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Tts Speed"},"post_eot_pause_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Post Eot Pause Ms"},"transition_deadline_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transition Deadline Ms"},"progress_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Interval Ms"},"empathy_hold_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empathy Hold Ms"},"filler_cooldown_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filler Cooldown Ms"},"progress_vocabulary":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Progress Vocabulary"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"},"realtime_voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"null"}],"title":"Realtime Voice","description":"Deprecated built-in OpenAI Realtime voice shortcut. Use realtime.voice instead; the two fields are mutually exclusive.","deprecated":true},"realtime":{"anyOf":[{"$ref":"#/components/schemas/RealtimeSessionConfig"},{"type":"null"}]},"forwarding":{"anyOf":[{"$ref":"#/components/schemas/ServiceForwardingConfig"},{"type":"null"}]}},"type":"object","title":"ServiceVoiceConfig","description":"Per-service voice pipeline tuning. Overrides workspace/env defaults.\n\nEach field is optional — None means inherit from the layer above\n(workspace VoiceSettings → env vars → hardcoded defaults)."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."},"RealtimeSessionConfig":{"properties":{"model":{"anyOf":[{"type":"string","enum":["gpt-realtime-1.5","gpt-realtime-2","gpt-realtime-2.1","gpt-realtime-2.1-mini"]},{"type":"null"}],"title":"Model"},"voice":{"anyOf":[{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"$ref":"#/components/schemas/RealtimeCustomVoice"},{"type":"null"}],"title":"Voice"},"speed":{"anyOf":[{"type":"number","maximum":1.5,"minimum":0.25},{"type":"null"}],"title":"Speed"},"noise_reduction":{"anyOf":[{"type":"string","enum":["near_field","far_field","off"]},{"type":"null"}],"title":"Noise Reduction","description":"Input noise reduction. Omit or set null to use the Platform default; set 'off' to disable it."},"transcription":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTranscriptionConfig"},{"type":"null"}]},"turn_detection":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/RealtimeServerVadConfig"},{"$ref":"#/components/schemas/RealtimeSemanticVadConfig"}],"discriminator":{"propertyName":"type","mapping":{"semantic_vad":"#/components/schemas/RealtimeSemanticVadConfig","server_vad":"#/components/schemas/RealtimeServerVadConfig"}}},{"type":"null"}],"title":"Turn Detection"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Reasoning Effort"},"max_output_tokens":{"anyOf":[{"type":"integer","maximum":4096,"minimum":1},{"type":"string","const":"inf"},{"type":"null"}],"title":"Max Output Tokens"},"truncation":{"anyOf":[{"$ref":"#/components/schemas/RealtimeTruncationConfig"},{"type":"null"}]},"required_tool_on_first_caller_turn":{"anyOf":[{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_.:-]*$"},{"type":"null"}],"title":"Required Tool On First Caller Turn","description":"Force one named function on the first caller-generated response, excluding the inbound greeting, then restore automatic tool choice. Runtime accepts this only for source_override='test' sessions and tools that the executor verifies are read-only or side-effect-free."}},"additionalProperties":false,"type":"object","title":"RealtimeSessionConfig","description":"Typed OpenAI Realtime session controls for a service."},"RealtimeCustomVoice":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^voice_[A-Za-z0-9_-]+$","title":"Id"}},"additionalProperties":false,"type":"object","required":["id"],"title":"RealtimeCustomVoice","description":"Approved OpenAI custom voice reference."},"RealtimeTranscriptionConfig":{"properties":{"model":{"type":"string","enum":["whisper-1","gpt-4o-mini-transcribe","gpt-4o-transcribe"],"title":"Model","default":"gpt-4o-transcribe"},"language":{"anyOf":[{"type":"string","maxLength":35,"minLength":2,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},{"type":"null"}],"title":"Language"},"prompt":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Prompt"}},"additionalProperties":false,"type":"object","title":"RealtimeTranscriptionConfig","description":"Asynchronous caller-audio transcription used for transcripts and observability."},"RealtimeServerVadConfig":{"properties":{"type":{"type":"string","const":"server_vad","title":"Type","default":"server_vad"},"threshold":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Threshold"},"prefix_padding_ms":{"anyOf":[{"type":"integer","maximum":5000,"minimum":0},{"type":"null"}],"title":"Prefix Padding Ms"},"silence_duration_ms":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Silence Duration Ms"},"idle_timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":5000},{"type":"null"}],"title":"Idle Timeout Ms"}},"additionalProperties":false,"type":"object","title":"RealtimeServerVadConfig","description":"Volume-based turn detection controls."},"RealtimeSemanticVadConfig":{"properties":{"type":{"type":"string","const":"semantic_vad","title":"Type","default":"semantic_vad"},"eagerness":{"type":"string","enum":["auto","low","medium","high"],"title":"Eagerness","default":"auto"}},"additionalProperties":false,"type":"object","title":"RealtimeSemanticVadConfig","description":"Semantic turn detection controls."},"RealtimeTruncationConfig":{"properties":{"type":{"type":"string","enum":["auto","disabled","retention_ratio"],"title":"Type","default":"auto"},"retention_ratio":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Retention Ratio"},"post_instructions_tokens":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Post Instructions Tokens"}},"additionalProperties":false,"type":"object","title":"RealtimeTruncationConfig","description":"Conversation context truncation strategy."},"ServiceForwardingConfig":{"properties":{"forward_to":{"anyOf":[{"$ref":"#/components/schemas/PhoneE164"},{"type":"null"}]},"warm_transfer":{"type":"boolean","title":"Warm Transfer"}},"type":"object","required":["forward_to","warm_transfer"],"title":"ServiceForwardingConfig","description":"Per-service call-forwarding destination + transfer mechanism.\n\nPresence of this block is the whole gate for the ``forward_call`` tool:\nNone means the agent cannot transfer at all. When present, ``forward_to``\npicks the destination mode, and the tool schema follows it — a static\nservice gets an argument-less tool, a dynamic one gets a required\n``phone_number``. Nothing cascades: a service is one mode or the other."},"PhoneE164":{"type":"string","maxLength":16,"minLength":2},"ContextKeySpec":{"properties":{"key":{"$ref":"#/components/schemas/SlugString"},"type":{"type":"string","enum":["string","number"],"title":"Type"},"description":{"$ref":"#/components/schemas/DescriptionString"},"required":{"type":"boolean","title":"Required"}},"type":"object","required":["key","type","description","required"],"title":"ContextKeySpec","description":"One key a conversation may supply as start-time context for a service.\n\nThe value is validated against ``type`` at conversation start; a tool can then\nbind the key to one of its parameters (injected, hidden from the model)."},"SlugString":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"}}}} ``` ## The UpdateSimulationCaseRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateSimulationCaseRequest":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Persona"},"description":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Description"},"scenario":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseScenario"},{"type":"null"}]},"grounding":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseGrounding"},{"type":"null"}]},"evals":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","maxItems":100},{"type":"null"}],"title":"Evals"},"tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"additionalProperties":false,"type":"object","title":"UpdateSimulationCaseRequest","description":"Partial update for one durable simulation case.\n\nMirrors the nested ``CreateSimulationCaseItem`` shape with every field\noptional so ``model_dump(exclude_unset=True)`` only emits the keys the\ncaller actually sent. Reuses the same nested submodels as create so the\ndurable fields (``scenario``, ``grounding``, ``evals``, ``metadata``) can\nbe PATCHed. ``extra=\"forbid\"`` rejects the retired pre-V192 flat fields\n(scenario_instructions, initial_message, temperament, fixtures,\nconstraints, target_spec, assertions, provenance) with 422 instead of\nsilently dropping them."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"}}}} ``` ## The UpdateSimulationSuiteRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateSimulationSuiteRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"case_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500},{"type":"null"}],"title":"Case Ids"},"required_tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Required Tags"},"tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"additionalProperties":false,"type":"object","title":"UpdateSimulationSuiteRequest"}}}} ``` ## The UpdateSkillRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateSkillRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"system_prompt":{"anyOf":[{"$ref":"#/components/schemas/BackgroundString"},{"type":"null"}]},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema"},"result_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Schema"},"model":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Model"},"max_tokens":{"anyOf":[{"type":"integer","maximum":200000,"minimum":1},{"type":"null"}],"title":"Max Tokens"},"max_result_chars":{"anyOf":[{"type":"integer","maximum":200000,"minimum":1},{"type":"null"}],"title":"Max Result Chars"},"max_input_tokens":{"anyOf":[{"type":"integer","maximum":2000000,"minimum":1},{"type":"null"}],"title":"Max Input Tokens"},"timeout_s":{"anyOf":[{"type":"number","maximum":900,"minimum":0.1},{"type":"null"}],"title":"Timeout S"},"thinking_effort":{"anyOf":[{"$ref":"#/components/schemas/ThinkingEffort"},{"type":"null"}]},"temperature":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Temperature","description":"Anthropic sampling temperature (0-1); see CreateSkillRequest. null/absent leaves it unchanged."},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P","description":"Anthropic nucleus sampling (0-1); see CreateSkillRequest. null/absent leaves it unchanged."},"enable_caching":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enable Caching"},"enable_citations":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enable Citations"},"use_structured_output":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Use Structured Output"},"integration_tools":{"anyOf":[{"items":{"$ref":"#/components/schemas/IntegrationToolRef-Input"},"type":"array","maxItems":50},{"type":"null"}],"title":"Integration Tools"},"static_tools":{"anyOf":[{"items":{"$ref":"#/components/schemas/StaticToolDef-Input"},"type":"array","maxItems":50},{"type":"null"}],"title":"Static Tools"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"max_agent_turns":{"anyOf":[{"type":"integer","maximum":200,"minimum":1},{"type":"null"}],"title":"Max Agent Turns"},"checkpoint_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Checkpoint Enabled"},"approval_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Approval Required"}},"type":"object","title":"UpdateSkillRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"BackgroundString":{"type":"string","maxLength":10000},"ThinkingEffort":{"type":"string","enum":["low","medium","high"]},"IntegrationToolRef-Input":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."},"StaticToolDef-Input":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}}} ``` ## The UpdateSurfaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateSurfaceRequest":{"properties":{"title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/SurfaceField"},"type":"array","maxItems":200,"minItems":1},{"type":"null"}],"title":"Fields"},"branding":{"anyOf":[{"$ref":"#/components/schemas/BrandingConfig"},{"type":"null"}]},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/SurfaceSection"},"type":"array"},{"type":"null"}],"title":"Sections"},"completion_title":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Completion Title"},"completion_message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Completion Message"},"completion_action_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Completion Action Url"},"submit_button_text":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Submit Button Text"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"resource_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Resource Type"}},"type":"object","title":"UpdateSurfaceRequest","description":"Partial update to an existing surface.\n\nAll fields are optional. Only provided fields are merged into the spec.\nOnly allowed while status is CREATED or DELIVERED."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"SurfaceField":{"properties":{"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"label":{"$ref":"#/components/schemas/NameString"},"field_type":{"$ref":"#/components/schemas/FieldType"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"placeholder":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Placeholder"},"prefill_value":{"anyOf":[{},{"type":"null"}],"title":"Prefill Value"},"validation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Validation"},"sensitive":{"type":"boolean","title":"Sensitive","default":false},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"},"consent_text":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Consent Text"}},"type":"object","required":["key","label","field_type"],"title":"SurfaceField","description":"A single data collection field in a surface spec.\n\nGenerated by agents from HSM analysis. Each field maps\nto a specific piece of data the world model needs."},"FieldType":{"type":"string","enum":["text","textarea","date","phone","email","number","select","multiselect","checkbox","photo","signature","file","heading","info"],"title":"FieldType","description":"Input field types for surface data collection."},"BrandingConfig":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Logo Url"},"primary_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Primary Color"},"background_color":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Background Color"},"font_family":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Font Family"}},"type":"object","title":"BrandingConfig","description":"Visual branding for patient-facing surfaces."},"SurfaceSection":{"properties":{"title":{"$ref":"#/components/schemas/NameString"},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"field_keys":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Field Keys"},"condition":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Condition"}},"type":"object","required":["title","field_keys"],"title":"SurfaceSection","description":"A page/step in a multi-page surface form."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}}} ``` ## The UpdateTriggerRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateTriggerRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"event_type":{"anyOf":[{"$ref":"#/components/schemas/TriggerableEvent"},{"type":"null"}]},"event_filter":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Event Filter"},"action_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Action Id"},"input_template":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Template"},"schedule":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Schedule"},"timezone":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Timezone"}},"type":"object","title":"UpdateTriggerRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"TriggerableEvent":{"type":"string","enum":["amigo.trigger.cron","appointment.booked","appointment.cancelled","appointment.confirmed","booking.requested","call.ended","call.intelligence","call.outcome","channel.message.received","conversation.channel_switched","conversation.started","conversation.turn_recorded","coverage.created","entity.enriched","entity.resolved","medication.refill_requested","outbound.initiated","outbound.scheduled","patient.created","patient.updated","relationship.established","review.approve","review.correct","review.reject","surface.created","surface.submitted","ticket.created","triage.completed","trigger.completed","trigger.failed","trigger.fired"],"title":"TriggerableEvent","description":"Closed set of world events that trigger definitions may subscribe to.\n\nThe database column intentionally remains text for compatibility with old\nrows, but API writes must choose from this list so typoed event names do\nnot silently create never-matching triggers."}}}} ``` ## The UpdateWorkspaceRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpdateWorkspaceRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"topic_modeling_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Topic Modeling Enabled"},"delta_sharing_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Delta Sharing Enabled"},"delta_sharing_mode":{"type":"string","enum":["open","databricks"],"title":"Delta Sharing Mode"},"delta_sharing_identifier":{"type":"string","maxLength":512,"minLength":1,"title":"Delta Sharing Identifier"},"region":{"anyOf":[{"type":"string","enum":["us-east-1","ap-southeast-2","eu-central-1","ca-central-1"]},{"type":"null"}],"title":"Region"},"connector_type":{"anyOf":[{"type":"string","enum":["epic","cerner","allscripts","fhir_store","athenahealth","charmhealth","eclinicalworks","meditab"]},{"type":"null"}],"title":"Connector Type"}},"type":"object","title":"UpdateWorkspaceRequest"},"StrippedNonemptyString":{"type":"string","minLength":1}}}} ``` ## The UpsertRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpsertRequest":{"properties":{"source":{"type":"string","maxLength":128,"minLength":1,"title":"Source"},"external_subject_key":{"type":"string","maxLength":512,"minLength":1,"title":"External Subject Key"},"external_subject_id":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"External Subject Id"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"display_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Display Name"},"roles":{"items":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,63}$"},"type":"array","maxItems":64,"title":"Roles"},"roles_verified":{"type":"boolean","title":"Roles Verified","default":false},"provisioned_via":{"type":"string","enum":["roster_sync","jit"],"title":"Provisioned Via"}},"additionalProperties":false,"type":"object","required":["source","external_subject_key","entity_id","provisioned_via"],"title":"UpsertRequest"}}}} ``` ## The UpsertVersionSetRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UpsertVersionSetRequest":{"properties":{"version_set":{"$ref":"#/components/schemas/VersionSet-Input"}},"type":"object","required":["version_set"],"title":"UpsertVersionSetRequest"},"VersionSet-Input":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."}}}} ``` ## The UsageAttribution object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked requests divided by all requests; null when there are no requests."},"service_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input tokens divided by all input tokens; null when there are none."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate"],"title":"UsageAttribution","description":"Coverage of conversation and service attribution."}}}} ``` ## The UsageBucket object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageBucket":{"properties":{"event_type":{"type":"string","title":"Event Type","description":"World event type"},"event_date":{"type":"string","format":"date","title":"Event Date","description":"Date of the usage bucket"},"count":{"type":"integer","title":"Count","description":"Number of events in this bucket"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average event duration in seconds"},"total_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Duration Seconds","description":"Total event duration in seconds"}},"type":"object","required":["event_type","event_date","count"],"title":"UsageBucket"}}}} ``` ## The UsageClassesResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageClassesResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"classes":{"items":{"$ref":"#/components/schemas/ClassUsage"},"type":"array","title":"Classes","description":"All recorded usage classes, including production and non-production, after any service filter."}},"type":"object","required":["workspace_id","period","calculation_run_id","classes"],"title":"UsageClassesResponse","description":"Usage grouped by usage class, returned for `group_by=class`."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"ClassUsage":{"properties":{"usage_class":{"type":"string","title":"Usage Class"},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ClassUsage","description":"Usage attributed to one usage class."}}}} ``` ## The UsageCostAppliedRate object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostAppliedRate":{"properties":{"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version","description":"Null in V0 because the published facts do not retain a reproducible rate-card identifier."},"effective_from":{"type":"string","format":"date-time","title":"Effective From","description":"Inclusive input-rate start date, represented as midnight UTC."},"effective_to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective To","description":"Exclusive input-rate end date at midnight UTC; null means no end date."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["rate_card_version","effective_from","effective_to","input_per_million","cached_input_per_million","output_per_million"],"title":"UsageCostAppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The UsageCostAttribution object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked-token share; null because the published facts do not retain linked-token totals."},"service_attribution_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input and output tokens / all tokens in the selected scope; null with no tokens."},"may_include_amigo_operated_usage":{"type":"boolean","title":"May Include Amigo Operated Usage","description":"Whether production-classified totals may include usage operated by Amigo."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate","may_include_amigo_operated_usage"],"title":"UsageCostAttribution","description":"Known coverage and limitations of usage attribution."}}}} ``` ## The UsageCostDaily object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostDaily":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens"],"title":"UsageCostDaily","description":"Uncached input-token usage for one UTC date."}}}} ``` ## The UsageCostError object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostError":{"properties":{"code":{"type":"string","enum":["invalid_usage_period","workspace_usage_forbidden","workspace_not_found","usage_data_unavailable"],"title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"UsageCostError"}}}} ``` ## The UsageCostErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/UsageCostError"}},"type":"object","required":["error"],"title":"UsageCostErrorResponse","description":"Stable error envelope for the customer usage-cost contract."},"UsageCostError":{"properties":{"code":{"type":"string","enum":["invalid_usage_period","workspace_usage_forbidden","workspace_not_found","usage_data_unavailable"],"title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"UsageCostError"}}}} ``` ## The UsageCostExcludedClass object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostExcludedClass":{"properties":{"usage_class":{"type":"string","enum":["simulation","playground_test","customer_test","amigo_internal","unknown"],"title":"Usage Class"},"exclusion_reason":{"type":"string","enum":["simulation","playground","customer_test","amigo_internal","operator_attribution_unavailable"],"title":"Exclusion Reason"},"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in this excluded class; zero when none are linked."},"request_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Count","description":"Provider requests in this class; null when the source cannot supply a request count."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Input Tokens","description":"Cached input tokens in this class; null when the source cannot supply the count."},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","exclusion_reason","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"UsageCostExcludedClass","description":"Usage totals and exclusion reason for one non-production class."}}}} ``` ## The UsageCostExcludedResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostExcludedResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"$ref":"#/components/schemas/Period"},"classes":{"items":{"$ref":"#/components/schemas/UsageCostExcludedClass"},"type":"array","title":"Classes"}},"type":"object","required":["workspace_id","period","classes"],"title":"UsageCostExcludedResponse","description":"Usage explicitly excluded from production-classified totals."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageCostExcludedClass":{"properties":{"usage_class":{"type":"string","enum":["simulation","playground_test","customer_test","amigo_internal","unknown"],"title":"Usage Class"},"exclusion_reason":{"type":"string","enum":["simulation","playground","customer_test","amigo_internal","operator_attribution_unavailable"],"title":"Exclusion Reason"},"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in this excluded class; zero when none are linked."},"request_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Count","description":"Provider requests in this class; null when the source cannot supply a request count."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Input Tokens","description":"Cached input tokens in this class; null when the source cannot supply the count."},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","exclusion_reason","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"UsageCostExcludedClass","description":"Usage totals and exclusion reason for one non-production class."}}}} ``` ## The UsageCostLatestClose object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostLatestClose":{"properties":{"close_month":{"type":"string","format":"date","title":"Close Month"},"status":{"type":"string","const":"complete","title":"Status"},"calculated_at":{"type":"string","format":"date-time","title":"Calculated At"},"calculation_run_id":{"type":"string","title":"Calculation Run Id"},"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage"},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens"}},"type":"object","required":["close_month","status","calculated_at","calculation_run_id","rate_card_version","calculated_cost_usd","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostLatestClose","description":"Latest compatible completed monthly close, when available."}}}} ``` ## The UsageCostModel object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostModel":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked provider requests / its distinct linked conversations; null if none are linked."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"cache_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cache Rate","description":"Cached input tokens / total input tokens; null when there are no input tokens."},"output_tokens":{"type":"integer","title":"Output Tokens"},"applied_rates":{"items":{"$ref":"#/components/schemas/UsageCostAppliedRate"},"type":"array","title":"Applied Rates"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model cost rounded to cents; null if any contributing usage is unpriced, including partially priced models."},"cost_share":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cost Share","description":"Model cost / fully priced model costs in the selected scope, after any service filter.\nPartially priced models are excluded from both sides; null if unpriced or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","cache_rate","output_tokens","applied_rates","calculated_cost_usd","cost_share","is_priced","unpriced_reason"],"title":"UsageCostModel","description":"Production-classified usage and calculated cost for one model."},"UsageCostAppliedRate":{"properties":{"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version","description":"Null in V0 because the published facts do not retain a reproducible rate-card identifier."},"effective_from":{"type":"string","format":"date-time","title":"Effective From","description":"Inclusive input-rate start date, represented as midnight UTC."},"effective_to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective To","description":"Exclusive input-rate end date at midnight UTC; null means no end date."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["rate_card_version","effective_from","effective_to","input_per_million","cached_input_per_million","output_per_million"],"title":"UsageCostAppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The UsageCostModelsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"$ref":"#/components/schemas/Period"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in the selected scope; conversations shared by models are counted once."},"currency":{"type":"string","const":"USD","title":"Currency"},"models":{"items":{"$ref":"#/components/schemas/UsageCostModel"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","service_id","conversation_count","currency","models"],"title":"UsageCostModelsResponse","description":"Customer usage and calculated model-provider cost grouped by model."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageCostModel":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked provider requests / its distinct linked conversations; null if none are linked."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"cache_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cache Rate","description":"Cached input tokens / total input tokens; null when there are no input tokens."},"output_tokens":{"type":"integer","title":"Output Tokens"},"applied_rates":{"items":{"$ref":"#/components/schemas/UsageCostAppliedRate"},"type":"array","title":"Applied Rates"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model cost rounded to cents; null if any contributing usage is unpriced, including partially priced models."},"cost_share":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cost Share","description":"Model cost / fully priced model costs in the selected scope, after any service filter.\nPartially priced models are excluded from both sides; null if unpriced or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","cache_rate","output_tokens","applied_rates","calculated_cost_usd","cost_share","is_priced","unpriced_reason"],"title":"UsageCostModel","description":"Production-classified usage and calculated cost for one model."},"UsageCostAppliedRate":{"properties":{"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version","description":"Null in V0 because the published facts do not retain a reproducible rate-card identifier."},"effective_from":{"type":"string","format":"date-time","title":"Effective From","description":"Inclusive input-rate start date, represented as midnight UTC."},"effective_to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective To","description":"Exclusive input-rate end date at midnight UTC; null means no end date."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["rate_card_version","effective_from","effective_to","input_per_million","cached_input_per_million","output_per_million"],"title":"UsageCostAppliedRate","description":"Rate record applied to this model during the requested period."}}}} ``` ## The UsageCostOverviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"$ref":"#/components/schemas/UsageCostPeriod"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier; null for unattributed usage."},"attribution_status":{"type":"string","const":"best_effort","title":"Attribution Status"},"attribution":{"anyOf":[{"$ref":"#/components/schemas/UsageCostAttribution"},{"type":"null"}]},"data_status":{"type":"string","enum":["complete","partial","delayed","failed"],"title":"Data Status","description":"V0 returns partial for a published calculation, or failed when no complete calculation covers the period."},"data_as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Data As Of","description":"Source-event freshness; null because the published facts do not retain it."},"calculation_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculation Run Id","description":"Opaque published-calculation identifier; null when no complete calculation covers the period."},"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version","description":"Reproducible rate-card identifier; null because the published facts do not retain it."},"currency":{"type":"string","const":"USD","title":"Currency"},"totals":{"anyOf":[{"$ref":"#/components/schemas/UsageCostOverviewTotals"},{"type":"null"}]},"daily":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageCostDaily"},"type":"array"},{"type":"null"}],"title":"Daily","description":"Ascending UTC dates, zero-filled across the requested period; null when no complete calculation is available."},"services":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageCostService"},"type":"array"},{"type":"null"}],"title":"Services"},"latest_close":{"anyOf":[{"$ref":"#/components/schemas/UsageCostLatestClose"},{"type":"null"}],"description":"Null in V0 because no monthly close uses the same production-classification policy."}},"type":"object","required":["workspace_id","period","service_id","attribution_status","attribution","data_status","data_as_of","calculation_run_id","rate_card_version","currency","totals","daily","services","latest_close"],"title":"UsageCostOverviewResponse","description":"Customer usage and calculated model-provider cost overview."},"UsageCostPeriod":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"},"timezone":{"type":"string","const":"UTC","title":"Timezone"}},"type":"object","required":["start_date","end_date","timezone"],"title":"UsageCostPeriod","description":"Inclusive UTC calendar-date range covered by the report."},"UsageCostAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked-token share; null because the published facts do not retain linked-token totals."},"service_attribution_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input and output tokens / all tokens in the selected scope; null with no tokens."},"may_include_amigo_operated_usage":{"type":"boolean","title":"May Include Amigo Operated Usage","description":"Whether production-classified totals may include usage operated by Amigo."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate","may_include_amigo_operated_usage"],"title":"UsageCostAttribution","description":"Known coverage and limitations of usage attribution."},"UsageCostOverviewTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in the selected scope, not the sum of per-model counts."},"request_count":{"type":"integer","title":"Request Count","description":"Provider requests in the selected scope, including requests without a linked conversation."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost / distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any selected usage is omitted from the priced subtotal."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Input and output tokens belonging to usage that could not be priced."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostOverviewTotals","description":"Production-classified usage and calculated cost totals."},"UsageCostDaily":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens"],"title":"UsageCostDaily","description":"Uncached input-token usage for one UTC date."},"UsageCostService":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier; null for unattributed usage."},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name","description":"Service name at the latest metadata refresh; null if unavailable. Unattributed for a null service ID."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Service priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Service priced linked cost / its distinct priced linked conversations; cents, or null without a denominator."},"cost_share":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / workspace-wide priced subtotal, even when service_id filters the response.\nNull if this service has no priced cost or the workspace denominator is zero or unavailable."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage for this service is omitted from its priced subtotal."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens"}},"type":"object","required":["service_id","service_name","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","calculated_cost_usd","cost_per_conversation_usd","cost_share","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostService","description":"Production-classified usage and calculated cost for one service."},"UsageCostLatestClose":{"properties":{"close_month":{"type":"string","format":"date","title":"Close Month"},"status":{"type":"string","const":"complete","title":"Status"},"calculated_at":{"type":"string","format":"date-time","title":"Calculated At"},"calculation_run_id":{"type":"string","title":"Calculation Run Id"},"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage"},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens"}},"type":"object","required":["close_month","status","calculated_at","calculation_run_id","rate_card_version","calculated_cost_usd","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostLatestClose","description":"Latest compatible completed monthly close, when available."}}}} ``` ## The UsageCostOverviewTotals object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostOverviewTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in the selected scope, not the sum of per-model counts."},"request_count":{"type":"integer","title":"Request Count","description":"Provider requests in the selected scope, including requests without a linked conversation."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost / distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any selected usage is omitted from the priced subtotal."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Input and output tokens belonging to usage that could not be priced."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostOverviewTotals","description":"Production-classified usage and calculated cost totals."}}}} ``` ## The UsageCostPeriod object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostPeriod":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"},"timezone":{"type":"string","const":"UTC","title":"Timezone"}},"type":"object","required":["start_date","end_date","timezone"],"title":"UsageCostPeriod","description":"Inclusive UTC calendar-date range covered by the report."}}}} ``` ## The UsageCostService object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageCostService":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier; null for unattributed usage."},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name","description":"Service name at the latest metadata refresh; null if unavailable. Unattributed for a null service ID."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Service priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Service priced linked cost / its distinct priced linked conversations; cents, or null without a denominator."},"cost_share":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / workspace-wide priced subtotal, even when service_id filters the response.\nNull if this service has no priced cost or the workspace denominator is zero or unavailable."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage for this service is omitted from its priced subtotal."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens"}},"type":"object","required":["service_id","service_name","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","calculated_cost_usd","cost_per_conversation_usd","cost_share","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostService","description":"Production-classified usage and calculated cost for one service."}}}} ``` ## The UsageModelsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"models":{"items":{"$ref":"#/components/schemas/ModelUsage"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","calculation_run_id","models"],"title":"UsageModelsResponse","description":"Usage grouped by model, returned for `group_by=model`."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"ModelUsage":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked requests / its distinct linked conversations in the selected scope; null if none."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ModelUsage","description":"Usage attributed to one model and provider."}}}} ``` ## The UsageOverviewResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"attribution":{"$ref":"#/components/schemas/UsageAttribution"},"totals":{"$ref":"#/components/schemas/UsageTotals"},"daily":{"items":{"$ref":"#/components/schemas/DailyUsage"},"type":"array","title":"Daily","description":"Daily usage ordered from oldest to newest."},"services":{"items":{"$ref":"#/components/schemas/ServiceUsage"},"type":"array","title":"Services","description":"Services ordered by descending input-token usage."}},"type":"object","required":["workspace_id","period","calculation_run_id","attribution","totals","daily","services"],"title":"UsageOverviewResponse","description":"Usage overview returned when `group_by` is omitted."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked requests divided by all requests; null when there are no requests."},"service_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input tokens divided by all input tokens; null when there are none."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate"],"title":"UsageAttribution","description":"Coverage of conversation and service attribution."},"UsageTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageTotals","description":"Workspace totals for the requested period."},"DailyUsage":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"DailyUsage","description":"Token usage for one calendar date."},"ServiceUsage":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for usage that could not be attributed."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["service_id","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ServiceUsage","description":"Usage attributed to one service."}}}} ``` ## The UsageResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageResponse":{"anyOf":[{"$ref":"#/components/schemas/UsageOverviewResponse"},{"$ref":"#/components/schemas/UsageModelsResponse"},{"$ref":"#/components/schemas/UsageClassesResponse"}]},"UsageOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"attribution":{"$ref":"#/components/schemas/UsageAttribution"},"totals":{"$ref":"#/components/schemas/UsageTotals"},"daily":{"items":{"$ref":"#/components/schemas/DailyUsage"},"type":"array","title":"Daily","description":"Daily usage ordered from oldest to newest."},"services":{"items":{"$ref":"#/components/schemas/ServiceUsage"},"type":"array","title":"Services","description":"Services ordered by descending input-token usage."}},"type":"object","required":["workspace_id","period","calculation_run_id","attribution","totals","daily","services"],"title":"UsageOverviewResponse","description":"Usage overview returned when `group_by` is omitted."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked requests divided by all requests; null when there are no requests."},"service_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input tokens divided by all input tokens; null when there are none."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate"],"title":"UsageAttribution","description":"Coverage of conversation and service attribution."},"UsageTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageTotals","description":"Workspace totals for the requested period."},"DailyUsage":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"DailyUsage","description":"Token usage for one calendar date."},"ServiceUsage":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for usage that could not be attributed."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["service_id","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ServiceUsage","description":"Usage attributed to one service."},"UsageModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"models":{"items":{"$ref":"#/components/schemas/ModelUsage"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","calculation_run_id","models"],"title":"UsageModelsResponse","description":"Usage grouped by model, returned for `group_by=model`."},"ModelUsage":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked requests / its distinct linked conversations in the selected scope; null if none."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ModelUsage","description":"Usage attributed to one model and provider."},"UsageClassesResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"classes":{"items":{"$ref":"#/components/schemas/ClassUsage"},"type":"array","title":"Classes","description":"All recorded usage classes, including production and non-production, after any service filter."}},"type":"object","required":["workspace_id","period","calculation_run_id","classes"],"title":"UsageClassesResponse","description":"Usage grouped by usage class, returned for `group_by=class`."},"ClassUsage":{"properties":{"usage_class":{"type":"string","title":"Usage Class"},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ClassUsage","description":"Usage attributed to one usage class."}}}} ``` ## The UsageSummaryResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageSummaryResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace identifier"},"period_start":{"type":"string","format":"date","title":"Period Start","description":"Start of the reporting period"},"period_end":{"type":"string","format":"date","title":"Period End","description":"End of the reporting period"},"buckets":{"items":{"$ref":"#/components/schemas/UsageBucket"},"type":"array","title":"Buckets","description":"Usage data grouped by event type and date"},"total_events":{"type":"integer","title":"Total Events","description":"Total number of events in the period"}},"type":"object","required":["workspace_id","period_start","period_end","buckets","total_events"],"title":"UsageSummaryResponse"},"UsageBucket":{"properties":{"event_type":{"type":"string","title":"Event Type","description":"World event type"},"event_date":{"type":"string","format":"date","title":"Event Date","description":"Date of the usage bucket"},"count":{"type":"integer","title":"Count","description":"Number of events in this bucket"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds","description":"Average event duration in seconds"},"total_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Duration Seconds","description":"Total event duration in seconds"}},"type":"object","required":["event_type","event_date","count"],"title":"UsageBucket"}}}} ``` ## The UsageTotals object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UsageTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageTotals","description":"Workspace totals for the requested period."}}}} ``` ## The ValidationError object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"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"}}}} ``` ## The VersionSet-Input object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VersionSet-Input":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."}}}} ``` ## The VersionSet-Output object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VersionSet-Output":{"properties":{"agent_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Version Number"},"context_graph_version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Graph Version Number"},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig"},"type":"object","title":"Llm Model Preferences"}},"type":"object","title":"VersionSet","description":"Pins agent, state machine, and LLM model versions for a service."},"LLMConfig":{"properties":{"llm_name":{"type":"string","title":"Llm Name"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"experience_controls":{"anyOf":[{"$ref":"#/components/schemas/LLMExperienceControls"},{"type":"null"}]}},"type":"object","required":["llm_name"],"title":"LLMConfig"},"LLMExperienceControls":{"properties":{"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},{"type":"null"}],"title":"Reasoning Effort"},"temperature":{"anyOf":[{"type":"number","maximum":2,"minimum":0},{"type":"null"}],"title":"Temperature"},"top_p":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Top P"}},"additionalProperties":false,"type":"object","title":"LLMExperienceControls","description":"Typed model-tuning controls for a version set's LLM preference.\n\n``params`` remains available as a provider-specific escape hatch. These three\nfields are the ones deployments actually use; the surface was trimmed from\nnineteen in V370 after a production census found the other sixteen had never\nbeen set to a non-null value by anyone. Token budgets are intentionally\nexcluded so version sets do not reintroduce accidental response truncation."}}}} ``` ## The VoiceConfig object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceConfig":{"properties":{"voice_id":{"type":"string","title":"Voice Id"},"stability":{"type":"number","title":"Stability","default":0},"similarity_boost":{"type":"number","title":"Similarity Boost","default":0},"style":{"type":"number","title":"Style","default":0},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object","maxProperties":10},{"type":"null"}],"title":"Language Providers"},"session_provider":{"anyOf":[{"type":"string","enum":["amigo","gpt_realtime"]},{"type":"null"}],"title":"Session Provider"}},"type":"object","required":["voice_id"],"title":"VoiceConfig"},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The VoiceDetail object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceDetail":{"properties":{"recording_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recording Path"},"twilio_recording_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twilio Recording Sid"},"twilio_recording_duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Twilio Recording Duration"},"has_recording":{"type":"boolean","title":"Has Recording","default":false},"emotional_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Emotional Summary"},"barge_in_events":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Barge In Events","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"participants":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Participants","default":[]},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"call_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Call Analysis"},"forwarding":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Forwarding"},"escalation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Escalation"},"safety":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety"},"quality_breakdown":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quality Breakdown"},"risk_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Risk Summary"},"latency_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latency Summary"},"conversation_metrics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conversation Metrics"},"tool_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Summary"},"safety_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety Summary"},"operator_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Operator Summary"}},"type":"object","title":"VoiceDetail"}}}} ``` ## The VoiceJudgeRecentResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceJudgeRecentResponse":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"count":{"type":"integer","minimum":0,"title":"Count"},"items":{"items":{"$ref":"#/components/schemas/VoiceJudgeResultRow"},"type":"array","title":"Items"}},"type":"object","required":["service_id","count","items"],"title":"VoiceJudgeRecentResponse"},"VoiceJudgeResultRow":{"properties":{"call_sid":{"type":"string","maxLength":64,"title":"Call Sid"},"call_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Call Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"latency_dead_air_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Dead Air Score"},"pronunciation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pronunciation Score"},"clarity_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Clarity Score"},"filler_silence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Filler Silence Score"},"interruption_handling_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interruption Handling Score"},"audio_consistency_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Consistency Score"},"pacing_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pacing Score"},"warmth_tone_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Warmth Tone Score"},"accent_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Accent Quality Score"},"voice_identity_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Voice Identity Score"},"overall_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall Score"},"critical_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Critical Count"},"flag_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Flag Count"},"warning_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Warning Count"},"judge_json":{"anyOf":[{"type":"string","maxLength":32768},{"type":"null"}],"title":"Judge Json","description":"Raw Gemini judge output (evidence quotes, per-dim severity). Intended for UI drill-in; opaque string. Capped at 32KB."},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"}},"type":"object","required":["call_sid"],"title":"VoiceJudgeResultRow","description":"One call's voice-judge scoring, as stored in the Delta output table."}}}} ``` ## The VoiceJudgeResultRow object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceJudgeResultRow":{"properties":{"call_sid":{"type":"string","maxLength":64,"title":"Call Sid"},"call_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Call Entity Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"latency_dead_air_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Dead Air Score"},"pronunciation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pronunciation Score"},"clarity_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Clarity Score"},"filler_silence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Filler Silence Score"},"interruption_handling_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interruption Handling Score"},"audio_consistency_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Audio Consistency Score"},"pacing_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pacing Score"},"warmth_tone_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Warmth Tone Score"},"accent_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Accent Quality Score"},"voice_identity_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Voice Identity Score"},"overall_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall Score"},"critical_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Critical Count"},"flag_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Flag Count"},"warning_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Warning Count"},"judge_json":{"anyOf":[{"type":"string","maxLength":32768},{"type":"null"}],"title":"Judge Json","description":"Raw Gemini judge output (evidence quotes, per-dim severity). Intended for UI drill-in; opaque string. Capped at 32KB."},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"}},"type":"object","required":["call_sid"],"title":"VoiceJudgeResultRow","description":"One call's voice-judge scoring, as stored in the Delta output table."}}}} ``` ## The VoiceMetrics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceMetrics":{"properties":{"active_calls":{"type":"integer","title":"Active Calls","default":0},"active_escalated":{"type":"integer","title":"Active Escalated","default":0},"calls_today":{"type":"integer","title":"Calls Today","default":0},"avg_quality_score_today":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality Score Today"},"escalation_rate_today":{"type":"number","title":"Escalation Rate Today","default":0}},"type":"object","title":"VoiceMetrics"}}}} ``` ## The VoiceSettingsRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceSettingsRequest":{"properties":{"voice_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Voice Id"},"tone":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Tone"},"speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Speed"},"volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Volume"},"language":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Language"},"keyterms":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1},"type":"array","maxItems":200},{"type":"null"}],"title":"Keyterms"},"pronunciation_dict_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Pronunciation Dict Id"},"sensitive_topics":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1},"type":"array","maxItems":50},{"type":"null"}],"title":"Sensitive Topics"},"post_call_analysis_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Post Call Analysis Enabled"},"stt_provider":{"anyOf":[{"type":"string","enum":["deepgram","openai","cartesia"]},{"type":"null"}],"title":"Stt Provider"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object"},{"type":"null"}],"title":"Language Providers"}},"type":"object","title":"VoiceSettingsRequest","description":"Voice experience control plane — PM-facing, high-level controls.\n\nControls the caller experience without exposing engineering internals.\nEmotion detection, filler speech, model selection, and buffer tuning\nare always-on internals managed by engineering."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The VoiceSettingsResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceSettingsResponse":{"properties":{"voice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Id"},"tone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tone"},"speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Speed"},"volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Volume"},"language":{"type":"string","title":"Language"},"keyterms":{"items":{"type":"string"},"type":"array","title":"Keyterms"},"pronunciation_dict_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pronunciation Dict Id"},"sensitive_topics":{"items":{"type":"string"},"type":"array","title":"Sensitive Topics"},"post_call_analysis_enabled":{"type":"boolean","title":"Post Call Analysis Enabled"},"stt_provider":{"anyOf":[{"type":"string","enum":["deepgram","openai","cartesia"]},{"type":"null"}],"title":"Stt Provider"},"tts_provider":{"anyOf":[{"type":"string","enum":["cartesia","elevenlabs"]},{"type":"null"}],"title":"Tts Provider"},"tts_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tts Config"},"language_providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/LanguageProviderEntry"},"type":"object"},{"type":"null"}],"title":"Language Providers"}},"type":"object","required":["voice_id","tone","speed","volume","language","keyterms","pronunciation_dict_id","sensitive_topics","post_call_analysis_enabled","stt_provider","tts_provider","tts_config"],"title":"VoiceSettingsResponse","description":"Voice experience state — what the PM configured."},"LanguageProviderEntry":{"properties":{"provider":{"type":"string","enum":["cartesia","elevenlabs"],"title":"Provider"},"config":{"additionalProperties":true,"type":"object","maxProperties":20,"title":"Config"}},"type":"object","required":["provider"],"title":"LanguageProviderEntry","description":"Per-language TTS provider configuration."}}}} ``` ## The WorkspaceBenchmarks object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceBenchmarks":{"properties":{"avg_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality Score"},"p50_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Quality Score"},"p25_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25 Quality Score"},"p75_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75 Quality Score"},"total_calls":{"type":"integer","title":"Total Calls","default":0},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds"},"escalation_rate":{"type":"number","title":"Escalation Rate","default":0},"quality_distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Quality Distribution","default":{}}},"type":"object","title":"WorkspaceBenchmarks","description":"Workspace-level call quality benchmarks for contextual comparison."}}}} ``` ## The WorkspaceConnectorConfigResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceConnectorConfigResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"connector_type":{"type":"string","title":"Connector Type"},"data_source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Data Source Id"},"connection_config":{"additionalProperties":true,"type":"object","title":"Connection Config","default":{}},"outbound_entity_types":{"items":{"type":"string"},"type":"array","title":"Outbound Entity Types","default":[]}},"type":"object","required":["workspace_id","connector_type"],"title":"WorkspaceConnectorConfigResponse","description":"Connector configuration for a workspace."}}}} ``` ## The WorkspaceDataQueryItem object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceDataQueryItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameters":{"items":{"$ref":"#/components/schemas/StoredParameter"},"type":"array","title":"Parameters"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameters","timeout_ms","deployed_at","deployed_by"],"title":"WorkspaceDataQueryItem","description":"Wire shape for the response of every read + create/update handler.\n\n``id`` (UUID) is the stable handle — every URL except list takes it.\n``name`` is the workspace-visible label (UNIQUE per workspace) and is\nstill what the LLM tool registry keys on (``wsq_``), but it is\nnot the route identifier.\n\n``input_schema`` is deliberately NOT exposed — it is fully derivable\nfrom ``parameters[]``. UI consumers can build the JSON Schema view\nlocally if they need it."},"StoredParameter":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"StoredParameter","description":"One typed input parameter to a workspace data query — trusted shape.\n\nRead-path model: the DB's CHECK constraints already enforced ``name``\nregex and ``type`` enum on write, and the deploy endpoint's strict\n:class:`Parameter` validators enforced ``description`` length and\ntypo-rejection at the inbound network edge. After that, every\nconstruction of this model (DB read projection, executor binding,\nagent-engine spec, outbound response) is trusted — no 422 surface.\n\n``default is None`` is the canonical \"required\" signal: the executor\nraises if a caller omits a required argument, otherwise substitutes\nthe stored default."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The WorkspaceListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/WorkspaceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"WorkspaceListResponse"},"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"topic_modeling_enabled":{"type":"boolean","title":"Topic Modeling Enabled"},"delta_sharing_enabled":{"type":"boolean","title":"Delta Sharing Enabled"},"delta_sharing_mode":{"type":"string","enum":["open","databricks"],"title":"Delta Sharing Mode"},"delta_sharing_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delta Sharing Identifier"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","backend_org_id","region","connector_type","topic_modeling_enabled","delta_sharing_enabled","delta_sharing_mode","delta_sharing_identifier","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}}} ``` ## The WorkspaceResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"backend_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend Org Id"},"region":{"type":"string","title":"Region"},"connector_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connector Type"},"topic_modeling_enabled":{"type":"boolean","title":"Topic Modeling Enabled"},"delta_sharing_enabled":{"type":"boolean","title":"Delta Sharing Enabled"},"delta_sharing_mode":{"type":"string","enum":["open","databricks"],"title":"Delta Sharing Mode"},"delta_sharing_identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delta Sharing Identifier"},"provisioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Provisioned At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","name","backend_org_id","region","connector_type","topic_modeling_enabled","delta_sharing_enabled","delta_sharing_mode","delta_sharing_identifier","provisioned_at","created_at","updated_at"],"title":"WorkspaceResponse"}}}} ``` ## The WorldDashboardResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorldDashboardResponse":{"properties":{"entity_counts":{"$ref":"#/components/schemas/EntityStatsSummary"},"events_24h":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Events 24H","description":"Event count from the Lakebase read model; null when the projection is empty or unavailable."},"events_7d":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Events 7D","description":"Event count from the Lakebase read model; null when the projection is empty or unavailable."},"avg_confidence":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Avg Confidence"},"event_read_model_status":{"type":"string","enum":["ready","empty","unavailable"],"title":"Event Read Model Status","description":"ready = Lakebase projection returned a row; empty = no summary row; unavailable = read failed.","default":"empty"},"event_read_model_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Event Read Model Synced At","description":"platform.event_velocity_summary synced_at for this workspace."},"sources":{"items":{"$ref":"#/components/schemas/SourceBreakdownItem"},"type":"array","maxItems":500,"title":"Sources"}},"type":"object","required":["entity_counts"],"title":"WorldDashboardResponse"},"EntityStatsSummary":{"properties":{"total_entities":{"type":"integer","title":"Total Entities"},"total_events":{"type":"integer","title":"Total Events"},"sync_pending":{"type":"integer","title":"Sync Pending"},"sync_synced":{"type":"integer","title":"Sync Synced"},"sync_failed":{"type":"integer","title":"Sync Failed"},"by_event_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Event Type"}},"type":"object","required":["total_entities","total_events","sync_pending","sync_synced","sync_failed"],"title":"EntityStatsSummary"},"SourceBreakdownItem":{"properties":{"source_system":{"type":"string","title":"Source System"},"entity_type":{"type":"string","title":"Entity Type"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["source_system","entity_type","count"],"title":"SourceBreakdownItem"}}}} ``` ## The WorldScope object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorldScope":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"scoped_entity_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Scoped Entity Ids","default":[]},"allow_create":{"type":"boolean","title":"Allow Create","default":false}},"type":"object","required":["workspace_id"],"title":"WorldScope","description":"The world slice — ids only (the leaf stays I/O-free). This is the\nread/subject scope, NOT the write bound (see ``write_floor``).\n``allow_create`` records context intent and is not an authorization grant."}}}} ``` ## The WrapUpRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WrapUpRequest":{"properties":{"call_sid":{"type":"string","maxLength":64,"minLength":1,"title":"Call Sid"},"outcome":{"type":"string","enum":["resolved","escalated","transferred"],"title":"Outcome"},"notes":{"type":"string","maxLength":2000,"title":"Notes","default":""}},"type":"object","required":["call_sid","outcome"],"title":"WrapUpRequest","description":"Request to record operator intervention wrap-up."}}}} ``` ## The WrapUpResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WrapUpResponse":{"properties":{"success":{"type":"boolean","title":"Success"}},"type":"object","required":["success"],"title":"WrapUpResponse"}}}} ``` ## The WriteFloor object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WriteFloor":{"properties":{"enforced_at":{"type":"string","title":"Enforced At","default":"mcp-world-tools-edge"},"requires_entity_anchor":{"type":"boolean","title":"Requires Entity Anchor","default":true},"clinical_write_principal":{"type":"string","title":"Clinical Write Principal","default":"provider-only"},"clinical_write_scope":{"type":"string","title":"Clinical Write Scope","default":"any-entity-in-workspace"},"enrichment_write_scope":{"type":"string","title":"Enrichment Write Scope","default":"caller-anchor-only"},"unanchored_or_api_key_writes":{"type":"string","title":"Unanchored Or Api Key Writes","default":"none"},"allow_create":{"type":"boolean","title":"Allow Create","default":false}},"type":"object","title":"WriteFloor","description":"A static summary of MCP write policy, advisory to the renderer.\n\nThe MCP edge resolves the caller's actual principal and enforces the\nresult. These fields do not grant write access; hosted runner credentials\nare currently unanchored and cannot perform provider-only clinical writes."}}}} ``` ## The \_Access object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_Access":{"type":"string","enum":["read","write"]}}}} ``` ## The \_AgentSortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_AgentSortField":{"type":"string","enum":["name","created_at","updated_at"]}}}} ``` ## The \_DatasetSlug object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_DatasetSlug":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$"}}}} ``` ## The \_DatasetUpdateStatus object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_DatasetUpdateStatus":{"type":"string","enum":["checking_drive","preparing","publishing","completed","needs_review","failed"]}}}} ``` ## The \_DayHours object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_DayHours":{"properties":{"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"Start"},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","title":"End"}},"type":"object","required":["start","end"],"title":"_DayHours","description":"Open-hours window for one weekday. Times in 24h ``HH:MM`` form,\ninterpreted in the rule set's ``timezone``."}}}} ``` ## The \_FieldName object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_FieldName":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$"}}}} ``` ## The \_FileStatus object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]}}}} ``` ## The \_FileType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_FileType":{"type":"string","maxLength":16,"minLength":1,"pattern":"^[a-z0-9]+$"}}}} ``` ## The \_ResourceType object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_ResourceType":{"type":"string","enum":["integration_endpoint","skill","kb_scope"]}}}} ``` ## The \_SourceEventSortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_SourceEventSortField":{"type":"string","enum":["ingested_at","event_type","confidence"]}}}} ``` ## The \_ToolMockKey object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_ToolMockKey":{"type":"string","maxLength":128,"minLength":1}}}} ``` ## The \_ToolMockValue object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_ToolMockValue":{"type":"string","maxLength":16384}}}} ``` ## The \_VolumePath object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"_VolumePath":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z0-9/._-]+$"}}}} ``` ## The platform\_lib\_\_platform\_functions\_\_models\_\_Parameter object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"platform_lib__platform_functions__models__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted function-test or playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Typed declaration of one input parameter.\n\nFor SQL function types, ``name`` becomes the ``:name`` placeholder\nin the SQL template. For Python function types, ``name`` becomes\nthe positional argument name in ``def main(...)`` and the input\ncolumn name on the UC UDF signature.\n\nThe ``description`` propagates into the LLM tool spec (this is\nwhat Databricks' Agent Framework reads, and what Anthropic's\ntool-use spec exposes to the model). Missing descriptions\nsilently break tool selection — the registration layer rejects\nempty strings."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The src\_\_models\_\_IntegrationToolRef object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__models__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef","description":"Reference to an integration endpoint by integration + endpoint name."}}}} ``` ## The src\_\_models\_\_StaticToolDef object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__models__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef","description":"A built-in tool available to companion agents."}}}} ``` ## The src\_\_routes\_\_api\_keys\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__api_keys___SortField":{"type":"string","const":"created_at"}}}} ``` ## The src\_\_routes\_\_audit\_\_AuditEventResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__audit__AuditEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"title":"AuditEventResponse"}}}} ``` ## The src\_\_routes\_\_context\_graphs\_\_context\_graph\_crud\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__context_graphs__context_graph_crud___SortField":{"type":"string","enum":["name","created_at","updated_at"]}}}} ``` ## The src\_\_routes\_\_external\_auth\_claim\_mappings\_\_CreateRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_auth_claim_mappings__CreateRequest":{"properties":{"claim_namespace":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_.:-]{0,63}$","title":"Claim Namespace"},"claim_key":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_.:-]{0,63}$","title":"Claim Key"},"external_value":{"type":"string","maxLength":256,"minLength":1,"title":"External Value"},"external_role_id":{"type":"string","format":"uuid","title":"External Role Id"}},"additionalProperties":false,"type":"object","required":["claim_namespace","claim_key","external_value","external_role_id"],"title":"CreateRequest"}}}} ``` ## The src\_\_routes\_\_external\_auth\_claim\_mappings\_\_ListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_auth_claim_mappings__ListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ClaimMappingItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ListResponse"},"ClaimMappingItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"claim_namespace":{"type":"string","title":"Claim Namespace"},"claim_key":{"type":"string","title":"Claim Key"},"external_value":{"type":"string","title":"External Value"},"external_role_id":{"type":"string","format":"uuid","title":"External Role Id"},"status":{"type":"string","enum":["active","superseded"],"title":"Status"},"changed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Changed By"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","claim_namespace","claim_key","external_value","external_role_id","status","created_at"],"title":"ClaimMappingItem"}}}} ``` ## The src\_\_routes\_\_external\_auth\_claim\_mappings\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_auth_claim_mappings___SortField":{"type":"string","const":"created_at"}}}} ``` ## The src\_\_routes\_\_external\_identity\_bindings\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_identity_bindings___SortField":{"type":"string","enum":["created_at","external_subject_key"]}}}} ``` ## The src\_\_routes\_\_external\_integrations\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_integrations___SortField":{"type":"string","enum":["created_at","name","updated_at"]}}}} ``` ## The src\_\_routes\_\_external\_role\_assignments\_\_ListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_role_assignments__ListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExternalRoleAssignmentItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ListResponse"},"ExternalRoleAssignmentItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"source":{"type":"string","title":"Source"},"external_subject_key":{"type":"string","title":"External Subject Key"},"external_subject_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Subject Id"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"roles":{"items":{"type":"string"},"type":"array","title":"Roles"},"roles_verified":{"type":"boolean","title":"Roles Verified"},"status":{"type":"string","enum":["active","suspended","revoked"],"title":"Status"},"provisioned_via":{"type":"string","enum":["roster_sync","jit"],"title":"Provisioned Via"},"last_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Verified At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","source","external_subject_key","entity_id","roles","roles_verified","status","provisioned_via","created_at","updated_at"],"title":"ExternalRoleAssignmentItem"}}}} ``` ## The src\_\_routes\_\_external\_role\_assignments\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_role_assignments___SortField":{"type":"string","enum":["created_at","external_subject_key"]}}}} ``` ## The src\_\_routes\_\_external\_roles\_\_CreateRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_roles__CreateRequest":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,63}$","title":"Name"},"external_name":{"type":"string","maxLength":256,"minLength":1,"title":"External Name"},"description":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","required":["name","external_name"],"title":"CreateRequest"}}}} ``` ## The src\_\_routes\_\_external\_roles\_\_ListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_roles__ListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ExternalRoleItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ListResponse"},"ExternalRoleItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"external_name":{"type":"string","title":"External Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"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","name","external_name","created_at","updated_at"],"title":"ExternalRoleItem","description":"Wire shape for read + create responses."}}}} ``` ## The src\_\_routes\_\_external\_roles\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_roles___SortField":{"type":"string","const":"created_at"}}}} ``` ## The src\_\_routes\_\_external\_write\_proposals\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__external_write_proposals___SortField":{"type":"string","const":"created_at"}}}} ``` ## The src\_\_routes\_\_integrations\_\_create\_endpoint\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__create_endpoint__Request":{"properties":{"name":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Name","description":"Slug-like identifier, immutable post-create."},"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description","description":"LLM-facing description shown in the tool definition."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method.","default":"POST"},"path":{"type":"string","maxLength":2048,"minLength":1,"pattern":"^[^/]","title":"Path","description":"URL path appended to the integration's base_url. Must NOT start with `/` — the path is\njoined onto the base URL (which already carries the leading slash). Supports `{param}` substitution."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema describing the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static headers merged into every request."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into POST/PUT/PATCH bodies. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding for write methods.","default":"json"},"response_template":{"anyOf":[{"type":"string","maxLength":16384},{"type":"null"}],"title":"Response Template","description":"Jinja template (sandboxed, StrictUndefined) rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Optional external-user-safe output contract. Uses response_template as its projection."},"max_response_length":{"type":"integer","maximum":1000000,"minimum":0,"title":"Max Response Length","description":"Truncate the rendered string to this many chars. 0 = no truncation.","default":0},"timeout_seconds":{"type":"number","maximum":600,"exclusiveMinimum":0,"title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","maximum":10,"minimum":0,"title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","maxItems":20,"uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["name","description","path"],"title":"Request","description":"Add a new endpoint to a REST integration (V186 flat shape)."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."}}}} ``` ## The src\_\_routes\_\_integrations\_\_create\_integration\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__create_integration__Request":{"properties":{"name":{"type":"string","maxLength":128,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Name","description":"Slug-like identifier, lowercase alphanumeric + hyphens/underscores. Immutable post-create."},"display_name":{"$ref":"#/components/schemas/NameString","description":"Human-readable name."},"base_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Base Url","description":"Base URL for the upstream REST API."},"auth":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/StaticHeaderAuthRequest"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthRequest"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthRequest"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthRequest"}],"discriminator":{"propertyName":"type","mapping":{"custom_token_exchange":"#/components/schemas/CustomTokenExchangeAuthRequest","oauth2_client_credentials":"#/components/schemas/OAuth2ClientCredentialsAuthRequest","oauth2_jwt_bearer":"#/components/schemas/OAuth2JwtBearerAuthRequest","static_header":"#/components/schemas/StaticHeaderAuthRequest"}}},{"type":"null"}],"title":"Auth","description":"Auth configuration. When set, ``secret_value`` is required."},"secret_value":{"anyOf":[{"type":"string","maxLength":8192,"minLength":1},{"type":"null"}],"title":"Secret Value","description":"Inline secret literal — auto-provisioned to the per-integration SSM path.\nRequired when ``auth`` is set. Bounded to fit a PEM RSA-4096 key + cert chain."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active on create.","default":true},"managed":{"type":"boolean","title":"Managed","description":"Whether this is a system-managed integration protected from workspace CRUD.","default":false},"approval_policy":{"type":"string","enum":["none","writes","all"],"title":"Approval Policy","description":"Human-in-the-loop approval gate. ``none`` (default) = no approval\nrequired; ``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"}},"type":"object","required":["name","display_name","base_url"],"title":"Request","description":"Create body — REST only."},"NameString":{"type":"string","maxLength":256,"minLength":1},"StaticHeaderAuthRequest":{"properties":{"type":{"type":"string","const":"static_header","title":"Type","default":"static_header"},"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name","description":"Outbound header name (RFC 7230 tchar)."}},"type":"object","required":["header_name"],"title":"StaticHeaderAuthRequest","description":"Static workspace-level secret used verbatim as a single header value."},"OAuth2ClientCredentialsAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type","default":"oauth2_client_credentials"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method","description":"RFC 6749 § 2.3.1: ``basic`` sends client_id+secret as HTTP Basic auth; ``body`` sends them in the form body.","default":"basic"}},"type":"object","required":["token_url","client_id"],"title":"OAuth2ClientCredentialsAuthRequest","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4.\n\nStrict RFC 6749 § 4.4.2 access token request: ``grant_type`` + optional\n``scope``. Client authentication (RFC 6749 § 2.3.1) is orthogonal —\n``client_auth_method`` picks between HTTP Basic auth and form-body\ncredentials. RFC 8707 ``resource`` and non-standard ``audience`` extensions\nare NOT supported here — add them back when a vendor needs one."},"OAuth2JwtBearerAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type","default":"oauth2_jwt_bearer"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer","description":"RFC 7523 ``iss`` claim — typically the service-account email or client_id."},"assertion_audience":{"type":"string","title":"Assertion Audience","description":"RFC 7523 ``aud`` claim — typically the token_url."},"assertion_subject":{"type":"string","title":"Assertion Subject","description":"RFC 7523 § 3 ``sub`` claim — MUST be present. For service-account flows\nwhere the client is its own subject, set to the same value as ``assertion_issuer``.\nUse a different value only for delegation / impersonation grants."},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds","default":3600},"include_iat":{"type":"boolean","title":"Include Iat","description":"RFC 7523 § 3 item 6 — ``iat`` claim set to mint time. Most IdPs (Google, Azure)\nrequire it for anti-replay; leave True unless a specific vendor rejects it.","default":true},"include_jti":{"type":"boolean","title":"Include Jti","description":"When True, generate a fresh ``jti`` (anti-replay) on every mint.","default":true},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm","default":"RS256"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage","description":"RFC 7523 flow selector — required; the caller must pick a flow.\n``authorization_grant`` (§ 2.1) sends the JWT as ``assertion`` under\n``grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer``.\n``client_authentication`` (§ 2.2, the ``private_key_jwt`` method) sends it as\n``client_assertion`` + ``client_assertion_type`` under ``grant_type=client_credentials``\n— required by Epic / SMART Backend Services."},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes","description":"RFC 7523 § 2.1 ``scope`` form-body parameter. Vendors that put scopes inside\nthe JWT instead (Google service accounts) use ``extra_claims = {\"scope\": \"...\"}``\nand leave this empty."},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims","description":"RFC 7523 § 3 item 8 — arbitrary additional JWT claims (e.g. Google's\n``scope`` claim, Azure's tenant claim). Merged BEFORE the required claims so\nIdP-specific extensions can't override ``iss`` / ``sub`` / ``aud`` / ``exp`` /\n``iat`` / ``nbf`` / ``jti``.","default":{}}},"type":"object","required":["token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_usage"],"title":"OAuth2JwtBearerAuthRequest","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` (required) selects the flow: § 2.1 (JWT as authorization\ngrant) or § 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthRequest":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type","default":"custom_token_exchange"},"exchange_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding","description":"``json`` (default) sends static_body_fields + param_body_fields as JSON; ``form`` sends as application/x-www-form-urlencoded.","default":"json"},"static_headers":{"patternProperties":{"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$":{"type":"string"}},"propertyNames":{"maxLength":256,"minLength":1},"type":"object","title":"Static Headers","description":"Workspace-level headers on the exchange request (keys are RFC 7230 tchar). Values may contain ``{secret}`` placeholder.","default":{}},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Workspace-level body fields keyed by RFC 6901 JSON Pointer (e.g. ``/meta/tool_name``\nfor nested fields, or ``/foo`` for a root-level field). Values may contain ``{secret}``\nplaceholder.","default":{}},"param_headers":{"patternProperties":{"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$":{"$ref":"#/components/schemas/ParamValueRequest"}},"propertyNames":{"maxLength":256,"minLength":1},"type":"object","title":"Param Headers","description":"Per-request params routed to headers on the exchange request, keyed by wire-name.","default":{}},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueRequest"},"type":"object","title":"Param Body Fields","description":"Per-request params routed to body fields on the exchange request, keyed by RFC 6901 JSON Pointer.","default":{}},"identity_bindings":{"additionalProperties":{"type":"string","enum":["principal.subject_key","principal.subject_id","external_user.subject_key"]},"type":"object","maxProperties":50,"title":"Identity Bindings","description":"Maps a declared ``param_name`` to the verified identity attribute that supplies it\nat dispatch. A bound param is dropped from the LLM-facing tool schema and injected from the\nverified session context (never model-supplied), closing the per-user-identity impersonation hole.\nKeys MUST reference a ``param_name`` declared on ``param_headers`` / ``param_body_fields``.","default":{}},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values","description":"Author-configured test values for identity-bound params.\n\nOnly ``external_user.subject_key`` bindings may carry test values. Runtime\ndispatch uses them only when a backend execution path explicitly opts in.","default":{}},"response_token_path":{"type":"string","title":"Response Token Path","description":"RFC 6901 JSON Pointer into the exchange response body that extracts the bearer token\n(e.g. ``/access_token`` or ``/data/bearer``). NO default — every config commits explicitly."}},"type":"object","required":["exchange_url","response_token_path"],"title":"CustomTokenExchangeAuthRequest","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nPath-shaped fields (``response_token_path``, ``static_body_fields`` keys,\n``param_body_fields`` keys) MUST be valid RFC 6901 JSON Pointer — one\nsyntax throughout."},"ParamValueRequest":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueRequest","description":"Routing target for a single per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthRequest.param_headers`` / ``param_body_fields``."}}}} ``` ## The src\_\_routes\_\_integrations\_\_list\_endpoints\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__list_endpoints__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EndpointResponse"},"type":"array","title":"Items","description":"The endpoints under this integration."},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more endpoints to retrieve."},"continuation_token":{"title":"Continuation Token","description":"Opaque token for the next page. Null when there are no more results."}},"type":"object","required":["items","has_more"],"title":"Response"},"EndpointResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs."},"name":{"type":"string","title":"Name","description":"Slug-like identifier. Unique per integration; immutable post-create."},"description":{"type":"string","title":"Description","description":"LLM-facing description."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method."},"path":{"type":"string","title":"Path","description":"URL path appended to the integration's base_url."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema for the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static request headers."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into every request. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding.","default":"json"},"response_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Template","description":"Jinja template rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Opt-in typed artifact contract for external-user conversation delivery."},"max_response_length":{"type":"integer","title":"Max Response Length","description":"Truncate the final rendered string to this many chars.","default":0},"timeout_seconds":{"type":"number","title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["id","name","description","method","path"],"title":"EndpointResponse","description":"Per-endpoint response (V186 flat shape)."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."}}}} ``` ## The src\_\_routes\_\_integrations\_\_list\_integrations\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__list_integrations__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RestIntegrationResponse"},"type":"array","title":"Items","description":"The integrations matching the request filters."},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more integrations to retrieve."},"continuation_token":{"title":"Continuation Token","description":"Opaque token for the next page. Null when there are no more results."}},"type":"object","required":["items","has_more"],"title":"Response"},"RestIntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Integration ID."},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace ID."},"name":{"type":"string","title":"Name","description":"Slug-like identifier, immutable post-create."},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active."},"managed":{"type":"boolean","title":"Managed","description":"Whether the integration is system-managed and protected from workspace CRUD.","default":false},"approval_policy":{"type":"string","enum":["none","writes","all"],"title":"Approval Policy","description":"Human-in-the-loop approval gate. ``none`` = no approval required;\n``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the integration was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the integration was last updated."},"kind":{"type":"string","const":"rest","title":"Kind","description":"Discriminator.","default":"rest"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations."},"auth":{"anyOf":[{"$ref":"#/components/schemas/StaticHeaderAuthDict"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthDict"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthDict"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthDict"},{"type":"null"}],"title":"Auth","description":"Authentication configuration (lib TypedDict union)."},"endpoint_count":{"type":"integer","title":"Endpoint Count","description":"Number of configured endpoints. Fetch the full list via GET /endpoints."}},"type":"object","required":["id","workspace_id","name","display_name","enabled","created_at","updated_at","base_url","endpoint_count"],"title":"RestIntegrationResponse","description":"REST variant — base URL, auth config, endpoint count."},"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer \"``."},"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."},"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}}} ``` ## The src\_\_routes\_\_integrations\_\_test\_endpoint\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__test_endpoint__Request":{"properties":{"params":{"additionalProperties":true,"type":"object","maxProperties":200,"title":"Params","description":"Tool arguments — the endpoint's ``input_schema``-declared inputs (path/query/body)."},"auth_params":{"additionalProperties":true,"type":"object","maxProperties":200,"title":"Auth Params","description":"Caller-supplied values for auth-routed params — the AUTH-ONLY channel.\n\nA ``custom_token_exchange`` integration declares ``param_headers`` /\n``param_body_fields`` whose ``param_name`` placeholders are NOT part of the\nendpoint's ``input_schema`` (they feed the pre-flight token exchange, not the\nendpoint call). They never reach the auth renderer through ``params`` alone, so\nthe renderer raised before any HTTP call. Supply them here to exercise the\nexchange end-to-end.\n\nPLA-980: these values resolve the token exchange but are STRIPPED before the\ndownstream endpoint request is built, so a pure-auth secret put here never\nechoes into the outbound body/query. A param that legitimately feeds BOTH the\nexchange and the endpoint call belongs in ``params`` (which keeps its existing\ndual-use behavior). ``auth_params`` is for pure-auth keys absent from ``params``;\non a key collision the ``params`` value wins (for both the exchange and the call)."}},"type":"object","title":"Request","description":"Inputs to ``POST /{integration_id}/endpoints/{endpoint_id}/test``."}}}} ``` ## The src\_\_routes\_\_integrations\_\_test\_endpoint\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__test_endpoint__Response":{"properties":{"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"HTTP status code from the upstream call."},"duration_ms":{"type":"number","title":"Duration Ms","description":"Request duration in milliseconds.","default":0},"retries":{"type":"integer","title":"Retries","description":"Number of retry attempts.","default":0},"raw_response":{"title":"Raw Response","description":"Raw response body from the upstream call."},"rendered":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rendered","description":"Response after Jinja `response_template` rendering, pre-truncation."},"final_result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Result","description":"Final processed result (rendered + truncated to max_response_length)."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the request failed."},"artifact":{"anyOf":[{"$ref":"#/components/schemas/ClientArtifact"},{"type":"null"}],"description":"Client artifact preview after JSON Schema and size validation."},"artifact_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Artifact Error","description":"Safe validation summary when client output is enabled but cannot be emitted."}},"type":"object","title":"Response","description":"Full breadcrumb returned by the test handler."},"ClientArtifact":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"payload":{"$ref":"#/components/schemas/ClientArtifactPayload"}},"type":"object","required":["type","schema_version","payload"],"title":"ClientArtifact","description":"A versioned JSON payload that a client can render as a product component."},"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]}}}} ``` ## The src\_\_routes\_\_integrations\_\_update\_endpoint\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__update_endpoint__Request":{"properties":{"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method"},"path":{"type":"string","maxLength":2048,"minLength":1,"pattern":"^[^/]","title":"Path","description":"URL path appended to the integration's base_url. Must NOT start with `/`."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format"},"response_template":{"anyOf":[{"type":"string","maxLength":16384},{"type":"null"}],"title":"Response Template","description":"Jinja template; pass `null` to clear (the only DB-nullable column on this row)."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"title":"Client Output","description":"Client output contract; pass `null` to disable external artifact delivery."},"max_response_length":{"type":"integer","maximum":1000000,"minimum":0,"title":"Max Response Length"},"timeout_seconds":{"type":"number","maximum":600,"exclusiveMinimum":0,"title":"Timeout Seconds"},"max_retries":{"type":"integer","maximum":10,"minimum":0,"title":"Max Retries"},"retry_on_status":{"items":{"type":"integer"},"type":"array","maxItems":20,"uniqueItems":true,"title":"Retry On Status"}},"type":"object","title":"Request","description":"Patch an existing endpoint (V186 flat shape). ``name`` is immutable."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."}}}} ``` ## The src\_\_routes\_\_integrations\_\_update\_integration\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__integrations__update_integration__Request":{"properties":{"display_name":{"$ref":"#/components/schemas/NameString","title":"Display Name","description":"New display name."},"base_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Base Url","description":"New base URL."},"auth":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/StaticHeaderAuthRequest"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthRequest"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthRequest"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthRequest"}],"discriminator":{"propertyName":"type","mapping":{"custom_token_exchange":"#/components/schemas/CustomTokenExchangeAuthRequest","oauth2_client_credentials":"#/components/schemas/OAuth2ClientCredentialsAuthRequest","oauth2_jwt_bearer":"#/components/schemas/OAuth2JwtBearerAuthRequest","static_header":"#/components/schemas/StaticHeaderAuthRequest"}}},{"type":"null"}],"title":"Auth","description":"New auth config. Absent ⇒ untouched; null ⇒ clear; value ⇒ replace.\nIndependent of ``secret_value`` — updating ``auth`` alone reuses the\nexisting SSM secret."},"secret_value":{"type":"string","maxLength":8192,"minLength":1,"title":"Secret Value","description":"Rotate the per-integration SSM secret. Absent ⇒ existing secret\nuntouched; value ⇒ overwrite SSM at the canonical path. Explicit\n``null`` is rejected at validation — there is no \"clear the secret\"\noperation (clearing ``auth`` makes the secret unreachable; that's the\nintended clear path)."},"enabled":{"type":"boolean","title":"Enabled","description":"Toggle the integration on/off."},"managed":{"type":"boolean","title":"Managed","description":"Mark/unmark the integration as system-managed. Requires ``platform:admin`` scope."},"approval_policy":{"type":"string","enum":["none","writes","all"],"title":"Approval Policy","description":"Change the human-in-the-loop approval gate. ``none`` = no approval\nrequired; ``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint. Absent ⇒ untouched."}},"type":"object","title":"Request","description":"PATCH body — each field is sentinel-defaulted; absent ≠ explicit-null."},"NameString":{"type":"string","maxLength":256,"minLength":1},"StaticHeaderAuthRequest":{"properties":{"type":{"type":"string","const":"static_header","title":"Type","default":"static_header"},"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name","description":"Outbound header name (RFC 7230 tchar)."}},"type":"object","required":["header_name"],"title":"StaticHeaderAuthRequest","description":"Static workspace-level secret used verbatim as a single header value."},"OAuth2ClientCredentialsAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type","default":"oauth2_client_credentials"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method","description":"RFC 6749 § 2.3.1: ``basic`` sends client_id+secret as HTTP Basic auth; ``body`` sends them in the form body.","default":"basic"}},"type":"object","required":["token_url","client_id"],"title":"OAuth2ClientCredentialsAuthRequest","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4.\n\nStrict RFC 6749 § 4.4.2 access token request: ``grant_type`` + optional\n``scope``. Client authentication (RFC 6749 § 2.3.1) is orthogonal —\n``client_auth_method`` picks between HTTP Basic auth and form-body\ncredentials. RFC 8707 ``resource`` and non-standard ``audience`` extensions\nare NOT supported here — add them back when a vendor needs one."},"OAuth2JwtBearerAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type","default":"oauth2_jwt_bearer"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer","description":"RFC 7523 ``iss`` claim — typically the service-account email or client_id."},"assertion_audience":{"type":"string","title":"Assertion Audience","description":"RFC 7523 ``aud`` claim — typically the token_url."},"assertion_subject":{"type":"string","title":"Assertion Subject","description":"RFC 7523 § 3 ``sub`` claim — MUST be present. For service-account flows\nwhere the client is its own subject, set to the same value as ``assertion_issuer``.\nUse a different value only for delegation / impersonation grants."},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds","default":3600},"include_iat":{"type":"boolean","title":"Include Iat","description":"RFC 7523 § 3 item 6 — ``iat`` claim set to mint time. Most IdPs (Google, Azure)\nrequire it for anti-replay; leave True unless a specific vendor rejects it.","default":true},"include_jti":{"type":"boolean","title":"Include Jti","description":"When True, generate a fresh ``jti`` (anti-replay) on every mint.","default":true},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm","default":"RS256"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage","description":"RFC 7523 flow selector — required; the caller must pick a flow.\n``authorization_grant`` (§ 2.1) sends the JWT as ``assertion`` under\n``grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer``.\n``client_authentication`` (§ 2.2, the ``private_key_jwt`` method) sends it as\n``client_assertion`` + ``client_assertion_type`` under ``grant_type=client_credentials``\n— required by Epic / SMART Backend Services."},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes","description":"RFC 7523 § 2.1 ``scope`` form-body parameter. Vendors that put scopes inside\nthe JWT instead (Google service accounts) use ``extra_claims = {\"scope\": \"...\"}``\nand leave this empty."},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims","description":"RFC 7523 § 3 item 8 — arbitrary additional JWT claims (e.g. Google's\n``scope`` claim, Azure's tenant claim). Merged BEFORE the required claims so\nIdP-specific extensions can't override ``iss`` / ``sub`` / ``aud`` / ``exp`` /\n``iat`` / ``nbf`` / ``jti``.","default":{}}},"type":"object","required":["token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_usage"],"title":"OAuth2JwtBearerAuthRequest","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` (required) selects the flow: § 2.1 (JWT as authorization\ngrant) or § 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthRequest":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type","default":"custom_token_exchange"},"exchange_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding","description":"``json`` (default) sends static_body_fields + param_body_fields as JSON; ``form`` sends as application/x-www-form-urlencoded.","default":"json"},"static_headers":{"patternProperties":{"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$":{"type":"string"}},"propertyNames":{"maxLength":256,"minLength":1},"type":"object","title":"Static Headers","description":"Workspace-level headers on the exchange request (keys are RFC 7230 tchar). Values may contain ``{secret}`` placeholder.","default":{}},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Workspace-level body fields keyed by RFC 6901 JSON Pointer (e.g. ``/meta/tool_name``\nfor nested fields, or ``/foo`` for a root-level field). Values may contain ``{secret}``\nplaceholder.","default":{}},"param_headers":{"patternProperties":{"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$":{"$ref":"#/components/schemas/ParamValueRequest"}},"propertyNames":{"maxLength":256,"minLength":1},"type":"object","title":"Param Headers","description":"Per-request params routed to headers on the exchange request, keyed by wire-name.","default":{}},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueRequest"},"type":"object","title":"Param Body Fields","description":"Per-request params routed to body fields on the exchange request, keyed by RFC 6901 JSON Pointer.","default":{}},"identity_bindings":{"additionalProperties":{"type":"string","enum":["principal.subject_key","principal.subject_id","external_user.subject_key"]},"type":"object","maxProperties":50,"title":"Identity Bindings","description":"Maps a declared ``param_name`` to the verified identity attribute that supplies it\nat dispatch. A bound param is dropped from the LLM-facing tool schema and injected from the\nverified session context (never model-supplied), closing the per-user-identity impersonation hole.\nKeys MUST reference a ``param_name`` declared on ``param_headers`` / ``param_body_fields``.","default":{}},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values","description":"Author-configured test values for identity-bound params.\n\nOnly ``external_user.subject_key`` bindings may carry test values. Runtime\ndispatch uses them only when a backend execution path explicitly opts in.","default":{}},"response_token_path":{"type":"string","title":"Response Token Path","description":"RFC 6901 JSON Pointer into the exchange response body that extracts the bearer token\n(e.g. ``/access_token`` or ``/data/bearer``). NO default — every config commits explicitly."}},"type":"object","required":["exchange_url","response_token_path"],"title":"CustomTokenExchangeAuthRequest","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nPath-shaped fields (``response_token_path``, ``static_body_fields`` keys,\n``param_body_fields`` keys) MUST be valid RFC 6901 JSON Pointer — one\nsyntax throughout."},"ParamValueRequest":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueRequest","description":"Routing target for a single per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthRequest.param_headers`` / ``param_body_fields``."}}}} ``` ## The src\_\_routes\_\_internal\_skills\_\_IntegrationToolRef object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__internal_skills__IntegrationToolRef":{"properties":{"integration":{"type":"string","title":"Integration"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["integration","endpoint"],"title":"IntegrationToolRef"}}}} ``` ## The src\_\_routes\_\_internal\_skills\_\_StaticToolDef object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__internal_skills__StaticToolDef":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"}},"type":"object","required":["name","description","input_schema"],"title":"StaticToolDef"}}}} ``` ## The src\_\_routes\_\_memory\_dimensions\_\_create\_memory\_dimension\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__memory_dimensions__create_memory_dimension__Request":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"key":{"type":"string","maxLength":64,"minLength":1,"title":"Key"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"}},"type":"object","required":["service_id","key","description"],"title":"Request"}}}} ``` ## The src\_\_routes\_\_operators\_models\_\_AuditEventResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__operators_models__AuditEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"event_type":{"type":"string","title":"Event Type","description":"Audit event type (e.g. operator.status_change)"},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Audit payload — shape varies by event_type"},"source":{"type":"string","title":"Source","description":"System that emitted the event"},"ingested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ingested At","description":"When the event was ingested"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the event occurred"}},"type":"object","required":["id","workspace_id","event_type","data","source"],"title":"AuditEventResponse"}}}} ``` ## The src\_\_routes\_\_production\_evals\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__production_evals___SortField":{"type":"string","const":"created_at"}}}} ``` ## The src\_\_routes\_\_role\_grants\_\_CreateRequest object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__role_grants__CreateRequest":{"properties":{"role_id":{"type":"string","format":"uuid","title":"Role Id"},"resource_type":{"$ref":"#/components/schemas/_ResourceType"},"resource_key":{"type":"string","maxLength":512,"minLength":1,"title":"Resource Key"},"access":{"$ref":"#/components/schemas/_Access"},"param_binding":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Param Binding"}},"additionalProperties":false,"type":"object","required":["role_id","resource_type","resource_key","access"],"title":"CreateRequest"},"_ResourceType":{"type":"string","enum":["integration_endpoint","skill","kb_scope"]},"_Access":{"type":"string","enum":["read","write"]}}}} ``` ## The src\_\_routes\_\_role\_grants\_\_ListResponse object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__role_grants__ListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RoleGrantItem"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"ListResponse"},"RoleGrantItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"role_id":{"type":"string","format":"uuid","title":"Role Id"},"resource_type":{"$ref":"#/components/schemas/_ResourceType"},"resource_key":{"type":"string","title":"Resource Key"},"access":{"$ref":"#/components/schemas/_Access"},"param_binding":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param Binding"},"status":{"type":"string","enum":["active","superseded"],"title":"Status"},"changed_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Changed By"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","role_id","resource_type","resource_key","access","status","created_at"],"title":"RoleGrantItem"},"_ResourceType":{"type":"string","enum":["integration_endpoint","skill","kb_scope"]},"_Access":{"type":"string","enum":["read","write"]}}}} ``` ## The src\_\_routes\_\_role\_grants\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__role_grants___SortField":{"type":"string","const":"created_at"}}}} ``` ## The src\_\_routes\_\_runs\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__runs___SortField":{"type":"string","const":"started_at"}}}} ``` ## The src\_\_routes\_\_scheduling\_rule\_sets\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__scheduling_rule_sets___SortField":{"type":"string","enum":["agent_kind","rule_kind"]}}}} ``` ## The src\_\_routes\_\_services\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__services___SortField":{"type":"string","enum":["name","created_at","updated_at"]}}}} ``` ## The src\_\_routes\_\_skills\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__skills___SortField":{"type":"string","enum":["name","created_at","updated_at","slug"]}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_create\_workspace\_data\_query\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__create_workspace_data_query__Request":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description"},"sql_template":{"type":"string","maxLength":8192,"minLength":1,"title":"Sql Template"},"parameters":{"items":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__create_workspace_data_query__Request__Parameter"},"type":"array","maxItems":32,"title":"Parameters"},"timeout_ms":{"type":"integer","maximum":30000,"minimum":100,"title":"Timeout Ms","default":5000}},"additionalProperties":false,"type":"object","required":["name","description","sql_template"],"title":"Request","description":"Create body — the authored shape of a new workspace data query.\n\nThe SQL template + parameters parity check + multi-statement /\nsession-state-command refusal runs inside :meth:`_validate_template`\nso a bad payload surfaces as a Pydantic 422 with the standard wire\nshape — no try/except in the handler."},"src__routes__workspace_data_queries__create_workspace_data_query__Request__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Strict write-side validator for one declared parameter."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_create\_workspace\_data\_query\_\_Request\_\_Parameter object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__create_workspace_data_query__Request__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Strict write-side validator for one declared parameter."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_invoke\_workspace\_data\_query\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__invoke_workspace_data_query__Request":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Caller arguments matching the declared parameters."}},"type":"object","title":"Request"}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_invoke\_workspace\_data\_query\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__invoke_workspace_data_query__Response":{"properties":{"result":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"row_count":{"type":"integer","title":"Row Count","default":0}},"type":"object","title":"Response"}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_list\_workspace\_data\_queries\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__list_workspace_data_queries__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__list_workspace_data_queries__Response__Item"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","has_more"],"title":"Response"},"src__routes__workspace_data_queries__list_workspace_data_queries__Response__Item":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameter_count":{"type":"integer","title":"Parameter Count"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameter_count","timeout_ms","deployed_at","deployed_by"],"title":"Item"}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_list\_workspace\_data\_queries\_\_Response\_\_Item object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__list_workspace_data_queries__Response__Item":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"sql_template":{"type":"string","title":"Sql Template"},"parameter_count":{"type":"integer","title":"Parameter Count"},"timeout_ms":{"type":"integer","title":"Timeout Ms"},"last_invoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoked At"},"deployed_at":{"type":"string","format":"date-time","title":"Deployed At"},"deployed_by":{"type":"string","format":"uuid","title":"Deployed By"}},"type":"object","required":["id","name","description","sql_template","parameter_count","timeout_ms","deployed_at","deployed_by"],"title":"Item"}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_list\_workspace\_data\_queries\_\_\_SortField object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__list_workspace_data_queries___SortField":{"type":"string","const":"deployed_at"}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_update\_workspace\_data\_query\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__update_workspace_data_query__Request":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"minLength":1},{"type":"null"}],"title":"Description"},"sql_template":{"anyOf":[{"type":"string","maxLength":8192,"minLength":1},{"type":"null"}],"title":"Sql Template"},"parameters":{"anyOf":[{"items":{"$ref":"#/components/schemas/src__routes__workspace_data_queries__update_workspace_data_query__Request__Parameter"},"type":"array","maxItems":32},{"type":"null"}],"title":"Parameters"},"timeout_ms":{"anyOf":[{"type":"integer","maximum":30000,"minimum":100},{"type":"null"}],"title":"Timeout Ms"}},"additionalProperties":false,"type":"object","title":"Request","description":"PATCH body — every field optional. Present ⇒ overwrite; absent ⇒ keep."},"src__routes__workspace_data_queries__update_workspace_data_query__Request__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Strict write-side validator for one declared parameter."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The src\_\_routes\_\_workspace\_data\_queries\_\_update\_workspace\_data\_query\_\_Request\_\_Parameter object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_data_queries__update_workspace_data_query__Request__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"},"authorization_binding":{"anyOf":[{"$ref":"#/components/schemas/RoleGrantKeysBinding"},{"type":"null"}]},"authorization_binding_test_value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Authorization Binding Test Value","description":"Canonical CSV resource keys used only by trusted playground execution when no live authorization block exists."}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Strict write-side validator for one declared parameter."},"RoleGrantKeysBinding":{"properties":{"source":{"type":"string","const":"role_grant_resource_keys","title":"Source"},"resource_type":{"type":"string","const":"kb_scope","title":"Resource Type"},"access":{"type":"string","const":"read","title":"Access","default":"read"},"encoding":{"type":"string","const":"csv","title":"Encoding","default":"csv"}},"additionalProperties":false,"type":"object","required":["source","resource_type"],"title":"RoleGrantKeysBinding","description":"Declares a SQL-tool parameter as *server-bound* to a turn's resolved authorization.\n\nFamily-agnostic — consumed by BOTH platform functions (``fn_*``,\n``platform.function_parameters``) and workspace data queries (``wsq_*``,\n``platform.workspace_data_query_parameters``). A parameter carrying this binding\nis NOT caller-supplied: at execution the platform discards any caller value,\nprojects the resource keys the turn's :class:`ExternalAuthorizationBlock` holds\nfor ``(resource_type, access)`` via :meth:`ExternalAuthorizationBlock.resource_keys`,\nencodes them, and injects the result into the ``:name`` SQL bind — the model /\ncaller never sees or supplies it.\n\nThis is a THIRD parameter state, distinct from required (``default is None``) and\ndefaulted (``default is not None``): the caller-required check must exempt it and\nthe executor must always inject. The literal sets are pinned to v1; widening one is\na paired migration + model change (the ``binding_*`` columns added to both param\ntables in V328). ``extra=\"forbid\"`` so an author can't smuggle an unrecognized field.\n\nLives here, next to ``ExternalAuthorizationBlock.resource_keys`` (its runtime\ncounterpart), so the two SQL-tool families share one definition and can't drift."}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_create\_workspace\_table\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__create_workspace_table__Request":{"properties":{"table_name":{"$ref":"#/components/schemas/IdentifierString"},"columns":{"items":{"$ref":"#/components/schemas/Column-Input"},"type":"array","maxItems":100,"minItems":1,"title":"Columns"},"primary_key":{"anyOf":[{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array"},{"type":"null"}],"title":"Primary Key"},"unique":{"items":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1},"type":"array","title":"Unique"},"indexes":{"items":{"$ref":"#/components/schemas/Index-Input"},"type":"array","title":"Indexes"}},"type":"object","required":["table_name","columns"],"title":"Request"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"Column-Input":{"properties":{"name":{"$ref":"#/components/schemas/IdentifierString"},"type":{"$ref":"#/components/schemas/ColumnType"},"nullable":{"type":"boolean","title":"Nullable","default":true},"default":{"anyOf":[{"$ref":"#/components/schemas/Default"},{"type":"null"}]}},"type":"object","required":["name","type"],"title":"Column"},"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]},"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"},"Index-Input":{"properties":{"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"}},"type":"object","required":["columns"],"title":"Index"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_create\_workspace\_table\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__create_workspace_table__Response":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"table_name":{"type":"string","title":"Table Name"},"physical_name":{"type":"string","title":"Physical Name"}},"type":"object","required":["id","workspace_id","table_name","physical_name"],"title":"Response"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_execute\_workspace\_query\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__execute_workspace_query__Request":{"properties":{"sql":{"type":"string","maxLength":16384,"minLength":1,"title":"Sql","description":"One SQL statement: SELECT / WITH ... SELECT / INSERT / UPDATE /\nDELETE. Multi-statement, DDL, and session-state commands (SET ROLE,\nRESET, SET SESSION AUTHORIZATION) reject with 422 at the Pydantic\nboundary. ``pg_*`` function calls reject with 400 at execute time\n(no grant)."}},"type":"object","required":["sql"],"title":"Request"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_execute\_workspace\_query\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__execute_workspace_query__Response":{"properties":{"columns":{"items":{"type":"string"},"type":"array","title":"Columns"},"rows":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rows"},"row_count":{"type":"integer","title":"Row Count"}},"type":"object","required":["columns","rows","row_count"],"title":"Response"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_get\_workspace\_table\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__get_workspace_table__Response":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"table_name":{"type":"string","title":"Table Name"},"physical_name":{"type":"string","title":"Physical Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"columns":{"items":{"$ref":"#/components/schemas/Column-Output"},"type":"array","title":"Columns"},"indexes":{"items":{"$ref":"#/components/schemas/Index-Output"},"type":"array","title":"Indexes"},"constraints":{"items":{"$ref":"#/components/schemas/Constraint"},"type":"array","title":"Constraints"}},"type":"object","required":["id","workspace_id","table_name","physical_name","created_at","columns","indexes","constraints"],"title":"Response"},"Column-Output":{"properties":{"name":{"type":"string","title":"Name"},"data_type":{"type":"string","title":"Data Type","description":"Postgres-side type as reported by ``information_schema.columns``\n(e.g. ``uuid``, ``text``, ``timestamp with time zone``)."},"is_nullable":{"type":"boolean","title":"Is Nullable"},"default":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default","description":"Postgres-side default expression text, or NULL if no DEFAULT."}},"type":"object","required":["name","data_type","is_nullable","default"],"title":"Column"},"Index-Output":{"properties":{"name":{"type":"string","title":"Name"},"definition":{"type":"string","title":"Definition","description":"``pg_indexes.indexdef`` — the full CREATE INDEX statement."}},"type":"object","required":["name","definition"],"title":"Index"},"Constraint":{"properties":{"name":{"type":"string","title":"Name"},"definition":{"type":"string","title":"Definition","description":"``pg_get_constraintdef(oid)`` — the postgres-rendered definition."}},"type":"object","required":["name","definition"],"title":"Constraint"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_list\_workspace\_tables\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__list_workspace_tables__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/src__routes__workspace_tables__list_workspace_tables__Response__Item"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"Response"},"src__routes__workspace_tables__list_workspace_tables__Response__Item":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"table_name":{"type":"string","title":"Table Name"},"physical_name":{"type":"string","title":"Physical Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","workspace_id","table_name","physical_name","created_at"],"title":"Item"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_list\_workspace\_tables\_\_Response\_\_Item object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__list_workspace_tables__Response__Item":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"table_name":{"type":"string","title":"Table Name"},"physical_name":{"type":"string","title":"Physical Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","workspace_id","table_name","physical_name","created_at"],"title":"Item"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_update\_workspace\_table\_\_Request object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__update_workspace_table__Request":{"properties":{"actions":{"items":{"oneOf":[{"$ref":"#/components/schemas/AlterAction"}],"discriminator":{"propertyName":"op","mapping":{"add_column":"#/components/schemas/AlterAction","add_index":"#/components/schemas/AlterAction","add_unique":"#/components/schemas/AlterAction","change_column_type":"#/components/schemas/AlterAction","drop_column":"#/components/schemas/AlterAction","drop_column_default":"#/components/schemas/AlterAction","drop_constraint":"#/components/schemas/AlterAction","drop_index":"#/components/schemas/AlterAction","rename_column":"#/components/schemas/AlterAction","set_column_default":"#/components/schemas/AlterAction","set_column_nullable":"#/components/schemas/AlterAction"}}},"type":"array","maxItems":50,"minItems":1,"title":"Actions"}},"type":"object","required":["actions"],"title":"Request"},"AlterAction":{"anyOf":[{"$ref":"#/components/schemas/AddColumnAction"},{"$ref":"#/components/schemas/DropColumnAction"},{"$ref":"#/components/schemas/RenameColumnAction"},{"$ref":"#/components/schemas/ChangeColumnTypeAction"},{"$ref":"#/components/schemas/SetColumnNullableAction"},{"$ref":"#/components/schemas/SetColumnDefaultAction"},{"$ref":"#/components/schemas/DropColumnDefaultAction"},{"$ref":"#/components/schemas/AddUniqueAction"},{"$ref":"#/components/schemas/DropConstraintAction"},{"$ref":"#/components/schemas/AddIndexAction"},{"$ref":"#/components/schemas/DropIndexAction"}]},"AddColumnAction":{"properties":{"op":{"type":"string","const":"add_column","title":"Op"},"column":{"$ref":"#/components/schemas/Column-Input"}},"type":"object","required":["op","column"],"title":"AddColumnAction"},"Column-Input":{"properties":{"name":{"$ref":"#/components/schemas/IdentifierString"},"type":{"$ref":"#/components/schemas/ColumnType"},"nullable":{"type":"boolean","title":"Nullable","default":true},"default":{"anyOf":[{"$ref":"#/components/schemas/Default"},{"type":"null"}]}},"type":"object","required":["name","type"],"title":"Column"},"IdentifierString":{"type":"string","maxLength":63,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,62}$"},"ColumnType":{"type":"string","enum":["text","int","bigint","numeric","boolean","uuid","timestamptz","date","time","jsonb","bytea"]},"Default":{"properties":{"kind":{"type":"string","enum":["literal","uuid_v4","now","current_date"],"title":"Kind"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Only meaningful for ``kind=\"literal\"``. Other kinds ignore it.\nA ``dict`` value is rendered as a JSONB literal — pair it with a\n``jsonb`` column."}},"type":"object","required":["kind"],"title":"Default"},"DropColumnAction":{"properties":{"op":{"type":"string","const":"drop_column","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropColumnAction"},"RenameColumnAction":{"properties":{"op":{"type":"string","const":"rename_column","title":"Op"},"from":{"$ref":"#/components/schemas/IdentifierString"},"to":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","from","to"],"title":"RenameColumnAction"},"ChangeColumnTypeAction":{"properties":{"op":{"type":"string","const":"change_column_type","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"new_type":{"$ref":"#/components/schemas/ColumnType"}},"type":"object","required":["op","name","new_type"],"title":"ChangeColumnTypeAction"},"SetColumnNullableAction":{"properties":{"op":{"type":"string","const":"set_column_nullable","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"nullable":{"type":"boolean","title":"Nullable"}},"type":"object","required":["op","name","nullable"],"title":"SetColumnNullableAction"},"SetColumnDefaultAction":{"properties":{"op":{"type":"string","const":"set_column_default","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"},"default":{"$ref":"#/components/schemas/Default"}},"type":"object","required":["op","name","default"],"title":"SetColumnDefaultAction"},"DropColumnDefaultAction":{"properties":{"op":{"type":"string","const":"drop_column_default","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropColumnDefaultAction"},"AddUniqueAction":{"properties":{"op":{"type":"string","const":"add_unique","title":"Op"},"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"},"constraint_name":{"anyOf":[{"$ref":"#/components/schemas/IdentifierString"},{"type":"null"}]}},"type":"object","required":["op","columns"],"title":"AddUniqueAction"},"DropConstraintAction":{"properties":{"op":{"type":"string","const":"drop_constraint","title":"Op"},"name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","name"],"title":"DropConstraintAction"},"AddIndexAction":{"properties":{"op":{"type":"string","const":"add_index","title":"Op"},"index_name":{"$ref":"#/components/schemas/IdentifierString"},"columns":{"items":{"$ref":"#/components/schemas/IdentifierString"},"type":"array","maxItems":32,"minItems":1,"title":"Columns"}},"type":"object","required":["op","index_name","columns"],"title":"AddIndexAction"},"DropIndexAction":{"properties":{"op":{"type":"string","const":"drop_index","title":"Op"},"index_name":{"$ref":"#/components/schemas/IdentifierString"}},"type":"object","required":["op","index_name"],"title":"DropIndexAction"}}}} ``` ## The src\_\_routes\_\_workspace\_tables\_\_update\_workspace\_table\_\_Response object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"src__routes__workspace_tables__update_workspace_table__Response":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"table_name":{"type":"string","title":"Table Name"},"physical_name":{"type":"string","title":"Physical Name"}},"type":"object","required":["id","workspace_id","table_name","physical_name"],"title":"Response"}}}} ``` ## The CallEndedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallEndedEvent":{"properties":{"event_type":{"const":"call.ended","default":"call.ended","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"direction":{"enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","type":"string"},"duration_seconds":{"title":"Duration Seconds","type":"number"},"completion_reason":{"enum":["completed","abandoned","escalated","transferred","timeout","error","voicemail","no_answer","caller_hangup","forwarded","terminal_state","warm_transfer_completed","no_inbound_audio","cancelled"],"title":"Completion Reason","type":"string"},"escalated":{"default":false,"title":"Escalated","type":"boolean"}},"required":["call_sid","direction","duration_seconds","completion_reason"],"title":"CallEndedEvent","type":"object"}}}} ``` ## The CallEscalatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallEscalatedEvent":{"properties":{"event_type":{"const":"call.escalated","default":"call.escalated","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"escalation_id":{"title":"Escalation Id","type":"string"},"trigger":{"enum":["caller","ai","operator"],"title":"Trigger","type":"string"},"reason":{"title":"Reason","type":"string"}},"required":["call_sid","escalation_id","trigger","reason"],"title":"CallEscalatedEvent","type":"object"}}}} ``` ## The CallStartedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CallStartedEvent":{"properties":{"event_type":{"const":"call.started","default":"call.started","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"direction":{"enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","type":"string"},"service_id":{"format":"uuid","title":"Service Id","type":"string"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caller Id"}},"required":["call_sid","direction","service_id"],"title":"CallStartedEvent","type":"object"}}}} ``` ## The EncounterUpdatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EncounterUpdatedEvent":{"properties":{"event_type":{"const":"encounter.updated","default":"encounter.updated","title":"Event Type","type":"string"},"encounter_entity_id":{"format":"uuid","title":"Encounter Entity Id","type":"string"},"session_id":{"title":"Session Id","type":"string"}},"required":["encounter_entity_id","session_id"],"title":"EncounterUpdatedEvent","type":"object"}}}} ``` ## The IntegrationApprovalGrantedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntegrationApprovalGrantedEvent":{"properties":{"event_type":{"const":"integration.approval_granted","default":"integration.approval_granted","title":"Event Type","type":"string"},"conversation_id":{"maxLength":256,"minLength":1,"title":"Conversation Id","type":"string"}},"required":["conversation_id"],"title":"IntegrationApprovalGrantedEvent","type":"object"}}}} ``` ## The IntegrationApprovalRejectedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"IntegrationApprovalRejectedEvent":{"properties":{"event_type":{"const":"integration.approval_rejected","default":"integration.approval_rejected","title":"Event Type","type":"string"},"conversation_id":{"maxLength":256,"minLength":1,"title":"Conversation Id","type":"string"},"reason":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["conversation_id"],"title":"IntegrationApprovalRejectedEvent","type":"object"}}}} ``` ## The NarrativeUpdatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NarrativeUpdatedEvent":{"properties":{"event_type":{"const":"self_image.brief_generated","default":"self_image.brief_generated","title":"Event Type","type":"string"},"target_entity_id":{"format":"uuid","title":"Target Entity Id","type":"string"},"target_entity_type":{"title":"Target Entity Type","type":"string"},"event_id":{"format":"uuid","title":"Event Id","type":"string"},"version":{"title":"Version","type":"string"},"confidence":{"title":"Confidence","type":"number"},"event_count":{"title":"Event Count","type":"integer"}},"required":["target_entity_id","target_entity_type","event_id","version","confidence","event_count"],"title":"NarrativeUpdatedEvent","type":"object"}}}} ``` ## The OperatorJoinedCallEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorJoinedCallEvent":{"properties":{"event_type":{"const":"operator.joined_call","default":"operator.joined_call","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"mode":{"enum":["listen","takeover"],"title":"Mode","type":"string"}},"required":["call_sid","operator_id","mode"],"title":"OperatorJoinedCallEvent","type":"object"}}}} ``` ## The OperatorLeftCallEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorLeftCallEvent":{"properties":{"event_type":{"const":"operator.left_call","default":"operator.left_call","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"human_segment_turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Human Segment Turn Count"}},"required":["call_sid","operator_id"],"title":"OperatorLeftCallEvent","type":"object"}}}} ``` ## The OperatorModeChangedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorModeChangedEvent":{"properties":{"event_type":{"const":"operator.mode_changed","default":"operator.mode_changed","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"mode":{"enum":["listen","takeover"],"title":"Mode","type":"string"}},"required":["call_sid","operator_id","mode"],"title":"OperatorModeChangedEvent","type":"object"}}}} ``` ## The OperatorProfileUpdatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorProfileUpdatedEvent":{"properties":{"event_type":{"const":"operator.profile_updated","default":"operator.profile_updated","title":"Event Type","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"changes":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"default":null,"title":"Changes"}},"required":["operator_id"],"title":"OperatorProfileUpdatedEvent","type":"object"}}}} ``` ## The OperatorRegisteredEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorRegisteredEvent":{"properties":{"event_type":{"const":"operator.registered","default":"operator.registered","title":"Event Type","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timestamp"}},"required":["operator_id"],"title":"OperatorRegisteredEvent","type":"object"}}}} ``` ## The OperatorStatusChangedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorStatusChangedEvent":{"properties":{"event_type":{"const":"operator.status_changed","default":"operator.status_changed","title":"Event Type","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"status":{"enum":["online","busy","offline"],"title":"Status","type":"string"}},"required":["operator_id","status"],"title":"OperatorStatusChangedEvent","type":"object"}}}} ``` ## The OperatorWrapUpEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"OperatorWrapUpEvent":{"properties":{"event_type":{"const":"operator.wrap_up","default":"operator.wrap_up","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"wrap_up_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Wrap Up Reason"}},"required":["call_sid"],"title":"OperatorWrapUpEvent","type":"object"}}}} ``` ## The PipelineErrorEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PipelineErrorEvent":{"properties":{"event_type":{"const":"pipeline.error","default":"pipeline.error","title":"Event Type","type":"string"},"data_source_id":{"format":"uuid","title":"Data Source Id","type":"string"},"error":{"title":"Error","type":"string"}},"required":["data_source_id","error"],"title":"PipelineErrorEvent","type":"object"}}}} ``` ## The PipelineSyncCompletedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"PipelineSyncCompletedEvent":{"properties":{"event_type":{"const":"pipeline.sync_completed","default":"pipeline.sync_completed","title":"Event Type","type":"string"},"data_source_id":{"format":"uuid","title":"Data Source Id","type":"string"},"event_count":{"title":"Event Count","type":"integer"},"duration_ms":{"title":"Duration Ms","type":"integer"}},"required":["data_source_id","event_count","duration_ms"],"title":"PipelineSyncCompletedEvent","type":"object"}}}} ``` ## The ReviewSubmittedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ReviewSubmittedEvent":{"properties":{"event_type":{"const":"review.submitted","default":"review.submitted","title":"Event Type","type":"string"},"action":{"enum":["approve","reject","correct","batch_approve","batch_reject"],"title":"Action","type":"string"},"item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Item Id"},"entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Entity Id"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Entity Type"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Count"}},"required":["action"],"title":"ReviewSubmittedEvent","type":"object"}}}} ``` ## The SimulationTurnStoredEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SimulationTurnStoredEvent":{"properties":{"event_type":{"const":"simulation.turn_stored","default":"simulation.turn_stored","title":"Event Type","type":"string"},"service_id":{"format":"uuid","title":"Service Id","type":"string"},"run_id":{"title":"Run Id","type":"string"},"session_id":{"title":"Session Id","type":"string"},"turn_index":{"title":"Turn Index","type":"integer"},"state_before":{"title":"State Before","type":"string"},"state_after":{"title":"State After","type":"string"},"is_terminal":{"title":"Is Terminal","type":"boolean"}},"required":["service_id","run_id","session_id","turn_index","state_before","state_after","is_terminal"],"title":"SimulationTurnStoredEvent","type":"object"}}}} ``` ## The SurfaceArchivedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceArchivedEvent":{"properties":{"event_type":{"const":"surface.archived","default":"surface.archived","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"}},"required":["surface_id"],"title":"SurfaceArchivedEvent","type":"object"}}}} ``` ## The SurfaceCreatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceCreatedEvent":{"properties":{"event_type":{"const":"surface.created","default":"surface.created","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Channel"},"fields_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Fields Count"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"form_template_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Form Template Id"},"review_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Review Required"}},"required":["surface_id","entity_id"],"title":"SurfaceCreatedEvent","type":"object"}}}} ``` ## The SurfaceDeliveredEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceDeliveredEvent":{"properties":{"event_type":{"const":"surface.delivered","default":"surface.delivered","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"channel":{"title":"Channel","type":"string"},"channel_address":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Channel Address"},"delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Delivery Status"},"message_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Message Id"},"short_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Short Url"}},"required":["surface_id","entity_id","channel"],"title":"SurfaceDeliveredEvent","type":"object"}}}} ``` ## The SurfaceFieldSavedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceFieldSavedEvent":{"properties":{"event_type":{"const":"surface.field_saved","default":"surface.field_saved","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"field_key":{"title":"Field Key","type":"string"}},"required":["surface_id","entity_id","field_key"],"title":"SurfaceFieldSavedEvent","type":"object"}}}} ``` ## The SurfaceOpenedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceOpenedEvent":{"properties":{"event_type":{"const":"surface.opened","default":"surface.opened","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"}},"required":["surface_id","entity_id"],"title":"SurfaceOpenedEvent","type":"object"}}}} ``` ## The SurfacePendingReviewEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfacePendingReviewEvent":{"properties":{"event_type":{"const":"surface.pending_review","default":"surface.pending_review","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"form_template_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Form Template Id"},"review_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Review Required"}},"required":["surface_id","entity_id"],"title":"SurfacePendingReviewEvent","type":"object"}}}} ``` ## The SurfaceReshapedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceReshapedEvent":{"properties":{"event_type":{"const":"surface.reshaped","default":"surface.reshaped","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"original_surface_id":{"format":"uuid","title":"Original Surface Id","type":"string"}},"required":["surface_id","original_surface_id"],"title":"SurfaceReshapedEvent","type":"object"}}}} ``` ## The SurfaceReviewApprovedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceReviewApprovedEvent":{"properties":{"event_type":{"const":"surface.review_approved","default":"surface.review_approved","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"}},"required":["surface_id"],"title":"SurfaceReviewApprovedEvent","type":"object"}}}} ``` ## The SurfaceReviewRejectedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceReviewRejectedEvent":{"properties":{"event_type":{"const":"surface.review_rejected","default":"surface.review_rejected","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["surface_id"],"title":"SurfaceReviewRejectedEvent","type":"object"}}}} ``` ## The SurfaceSubmittedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceSubmittedEvent":{"properties":{"event_type":{"const":"surface.submitted","default":"surface.submitted","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Submitted At"},"fields_submitted":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fields Submitted"}},"required":["surface_id","entity_id"],"title":"SurfaceSubmittedEvent","type":"object"}}}} ``` ## The SurfaceUpdatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SurfaceUpdatedEvent":{"properties":{"event_type":{"const":"surface.updated","default":"surface.updated","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"}},"required":["surface_id"],"title":"SurfaceUpdatedEvent","type":"object"}}}} ``` ## The TextAgentMessageEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TextAgentMessageEvent":{"description":"An agent text turn pushed live over workspace SSE — the outbox of the\ndurable text-conversation actor (text-conversation-actor Stage A).\n\nWhere ``TextBackgroundResultEvent`` surfaces the raw tool card,\nthis carries the agent's *narrated* response (the turn the actor produces after\nre-entering on a background completion or other off-request signal), so a\nsubscribed web client renders it as a normal agent message with no polling and\nno user turn. ``conversation_id`` is the durable conversation UUID (web-only).","properties":{"event_type":{"const":"text.agent_message","default":"text.agent_message","title":"Event Type","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"text":{"title":"Text","type":"string"},"delivery_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Delivery Id"}},"required":["conversation_id","text"],"title":"TextAgentMessageEvent","type":"object"}}}} ``` ## The TextBackgroundResultEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TextBackgroundResultEvent":{"description":"A background (``execution=\"background\"``) tool finished for a web text\nconversation. Pushed live the instant the completion lands so a subscribed\nclient renders the result without polling or sending another message.\n\n``call_id`` is ``bg:`` to match the card identity the next-turn drain\nsurfaces (``build_background_completion_effect``), so a client that receives\nboth the live push and the eventual drained card sees one consistent card.\nWeb-only: ``conversation_id`` is the durable conversation UUID (non-web\nchannels route by a composite key and deliver via their own transport).","properties":{"event_type":{"const":"text.background_result","default":"text.background_result","title":"Event Type","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"tool_name":{"title":"Tool Name","type":"string"},"call_id":{"title":"Call Id","type":"string"},"succeeded":{"title":"Succeeded","type":"boolean"},"result":{"title":"Result","type":"string"},"depth":{"title":"Depth","type":"integer"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Duration Ms"}},"required":["conversation_id","tool_name","call_id","succeeded","result","depth"],"title":"TextBackgroundResultEvent","type":"object"}}}} ``` ## The TextCompletedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TextCompletedEvent":{"properties":{"event_type":{"const":"text.completed","default":"text.completed","title":"Event Type","type":"string"},"session_id":{"title":"Session Id","type":"string"},"duration_seconds":{"title":"Duration Seconds","type":"number"},"turn_count":{"title":"Turn Count","type":"integer"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Completion Reason"},"final_state":{"title":"Final State","type":"string"},"channel_kind":{"title":"Channel Kind","type":"string"}},"required":["session_id","duration_seconds","turn_count","final_state","channel_kind"],"title":"TextCompletedEvent","type":"object"}}}} ``` ## The TextStartedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TextStartedEvent":{"properties":{"event_type":{"const":"text.started","default":"text.started","title":"Event Type","type":"string"},"session_id":{"title":"Session Id","type":"string"},"service_id":{"format":"uuid","title":"Service Id","type":"string"},"channel_kind":{"title":"Channel Kind","type":"string"},"entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Entity Id"}},"required":["session_id","service_id","channel_kind"],"title":"TextStartedEvent","type":"object"}}}} ``` ## The TextToolStartedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TextToolStartedEvent":{"description":"A slow text tool *began* running for a web text conversation — pushed live\nthe instant the tool is dispatched, before the 15s blocking floor elapses, so a\nsubscribed client shows progress immediately instead of waiting out the floor in\nsilence (PLA-986). Emitted for tools that route through the background/floor-promoted\ndispatch paths (companion skills and ``execution=\"background\"`` tools) — the ones\nthat can outlast the turn's synchronous response.\n\nThe start/completion pair share one card identity: ``call_id`` is ``bg:``,\nmatching the eventual ``TextBackgroundResultEvent`` (and the next-turn drained card\nfrom ``build_background_completion_effect``), so a client collapses started → result\ninto one card rather than rendering two. Web-only: ``conversation_id`` is the durable\nconversation UUID (non-web channels route by a composite key and deliver via their own\ntransport).","properties":{"event_type":{"const":"text.tool_started","default":"text.tool_started","title":"Event Type","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"tool_name":{"title":"Tool Name","type":"string"},"call_id":{"title":"Call Id","type":"string"},"depth":{"title":"Depth","type":"integer"}},"required":["conversation_id","tool_name","call_id","depth"],"title":"TextToolStartedEvent","type":"object"}}}} ``` ## The TriggerCompletedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerCompletedEvent":{"properties":{"event_type":{"const":"trigger.completed","default":"trigger.completed","title":"Event Type","type":"string"},"trigger_id":{"format":"uuid","title":"Trigger Id","type":"string"},"trigger_name":{"title":"Trigger Name","type":"string"},"status":{"title":"Status","type":"string"}},"required":["trigger_id","trigger_name","status"],"title":"TriggerCompletedEvent","type":"object"}}}} ``` ## The TriggerFailedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerFailedEvent":{"properties":{"event_type":{"const":"trigger.failed","default":"trigger.failed","title":"Event Type","type":"string"},"trigger_id":{"format":"uuid","title":"Trigger Id","type":"string"},"trigger_name":{"title":"Trigger Name","type":"string"},"status":{"title":"Status","type":"string"}},"required":["trigger_id","trigger_name","status"],"title":"TriggerFailedEvent","type":"object"}}}} ``` ## The TriggerFiredEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TriggerFiredEvent":{"properties":{"event_type":{"const":"trigger.fired","default":"trigger.fired","title":"Event Type","type":"string"},"trigger_id":{"format":"uuid","title":"Trigger Id","type":"string"},"trigger_name":{"title":"Trigger Name","type":"string"},"manual":{"default":false,"title":"Manual","type":"boolean"}},"required":["trigger_id","trigger_name"],"title":"TriggerFiredEvent","type":"object"}}}} ``` ## The WorkspaceInvitationAcceptedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceInvitationAcceptedEvent":{"properties":{"event_type":{"const":"workspace.invitation_accepted","default":"workspace.invitation_accepted","title":"Event Type","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"role":{"title":"Role","type":"string"}},"required":["entity_id","role"],"title":"WorkspaceInvitationAcceptedEvent","type":"object"}}}} ``` ## The WorkspaceInvitationSentEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceInvitationSentEvent":{"properties":{"event_type":{"const":"workspace.invitation_sent","default":"workspace.invitation_sent","title":"Event Type","type":"string"},"invitation_id":{"title":"Invitation Id","type":"string"},"role":{"title":"Role","type":"string"},"resent":{"default":false,"title":"Resent","type":"boolean"}},"required":["invitation_id","role"],"title":"WorkspaceInvitationSentEvent","type":"object"}}}} ``` ## The WorkspaceMemberAddedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceMemberAddedEvent":{"properties":{"event_type":{"const":"workspace.member_added","default":"workspace.member_added","title":"Event Type","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"role":{"title":"Role","type":"string"}},"required":["entity_id","role"],"title":"WorkspaceMemberAddedEvent","type":"object"}}}} ``` ## The WorkspaceMemberRoleUpdatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceMemberRoleUpdatedEvent":{"properties":{"event_type":{"const":"workspace.member_role_updated","default":"workspace.member_role_updated","title":"Event Type","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"role":{"title":"Role","type":"string"},"previous_role":{"title":"Previous Role","type":"string"}},"required":["entity_id","role","previous_role"],"title":"WorkspaceMemberRoleUpdatedEvent","type":"object"}}}} ``` ## The WorkspaceSSEEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"WorkspaceSSEEvent":{"discriminator":{"mapping":{"call.ended":"#/components/schemas/CallEndedEvent","call.escalated":"#/components/schemas/CallEscalatedEvent","call.started":"#/components/schemas/CallStartedEvent","encounter.updated":"#/components/schemas/EncounterUpdatedEvent","integration.approval_granted":"#/components/schemas/IntegrationApprovalGrantedEvent","integration.approval_rejected":"#/components/schemas/IntegrationApprovalRejectedEvent","operator.joined_call":"#/components/schemas/OperatorJoinedCallEvent","operator.left_call":"#/components/schemas/OperatorLeftCallEvent","operator.mode_changed":"#/components/schemas/OperatorModeChangedEvent","operator.profile_updated":"#/components/schemas/OperatorProfileUpdatedEvent","operator.registered":"#/components/schemas/OperatorRegisteredEvent","operator.status_changed":"#/components/schemas/OperatorStatusChangedEvent","operator.wrap_up":"#/components/schemas/OperatorWrapUpEvent","pipeline.error":"#/components/schemas/PipelineErrorEvent","pipeline.sync_completed":"#/components/schemas/PipelineSyncCompletedEvent","review.submitted":"#/components/schemas/ReviewSubmittedEvent","self_image.brief_generated":"#/components/schemas/NarrativeUpdatedEvent","simulation.turn_stored":"#/components/schemas/SimulationTurnStoredEvent","surface.archived":"#/components/schemas/SurfaceArchivedEvent","surface.created":"#/components/schemas/SurfaceCreatedEvent","surface.delivered":"#/components/schemas/SurfaceDeliveredEvent","surface.field_saved":"#/components/schemas/SurfaceFieldSavedEvent","surface.opened":"#/components/schemas/SurfaceOpenedEvent","surface.pending_review":"#/components/schemas/SurfacePendingReviewEvent","surface.reshaped":"#/components/schemas/SurfaceReshapedEvent","surface.review_approved":"#/components/schemas/SurfaceReviewApprovedEvent","surface.review_rejected":"#/components/schemas/SurfaceReviewRejectedEvent","surface.submitted":"#/components/schemas/SurfaceSubmittedEvent","surface.updated":"#/components/schemas/SurfaceUpdatedEvent","text.agent_message":"#/components/schemas/TextAgentMessageEvent","text.background_result":"#/components/schemas/TextBackgroundResultEvent","text.completed":"#/components/schemas/TextCompletedEvent","text.started":"#/components/schemas/TextStartedEvent","text.tool_started":"#/components/schemas/TextToolStartedEvent","trigger.completed":"#/components/schemas/TriggerCompletedEvent","trigger.failed":"#/components/schemas/TriggerFailedEvent","trigger.fired":"#/components/schemas/TriggerFiredEvent","workspace.invitation_accepted":"#/components/schemas/WorkspaceInvitationAcceptedEvent","workspace.invitation_sent":"#/components/schemas/WorkspaceInvitationSentEvent","workspace.member_added":"#/components/schemas/WorkspaceMemberAddedEvent","workspace.member_role_updated":"#/components/schemas/WorkspaceMemberRoleUpdatedEvent"},"propertyName":"event_type"},"oneOf":[{"$ref":"#/components/schemas/CallStartedEvent"},{"$ref":"#/components/schemas/CallEndedEvent"},{"$ref":"#/components/schemas/CallEscalatedEvent"},{"$ref":"#/components/schemas/EncounterUpdatedEvent"},{"$ref":"#/components/schemas/NarrativeUpdatedEvent"},{"$ref":"#/components/schemas/ReviewSubmittedEvent"},{"$ref":"#/components/schemas/SimulationTurnStoredEvent"},{"$ref":"#/components/schemas/SurfaceCreatedEvent"},{"$ref":"#/components/schemas/SurfaceDeliveredEvent"},{"$ref":"#/components/schemas/SurfaceUpdatedEvent"},{"$ref":"#/components/schemas/SurfaceArchivedEvent"},{"$ref":"#/components/schemas/SurfaceReshapedEvent"},{"$ref":"#/components/schemas/SurfaceSubmittedEvent"},{"$ref":"#/components/schemas/SurfaceFieldSavedEvent"},{"$ref":"#/components/schemas/SurfaceOpenedEvent"},{"$ref":"#/components/schemas/SurfacePendingReviewEvent"},{"$ref":"#/components/schemas/SurfaceReviewApprovedEvent"},{"$ref":"#/components/schemas/SurfaceReviewRejectedEvent"},{"$ref":"#/components/schemas/IntegrationApprovalGrantedEvent"},{"$ref":"#/components/schemas/IntegrationApprovalRejectedEvent"},{"$ref":"#/components/schemas/TextStartedEvent"},{"$ref":"#/components/schemas/TextCompletedEvent"},{"$ref":"#/components/schemas/TextToolStartedEvent"},{"$ref":"#/components/schemas/TextBackgroundResultEvent"},{"$ref":"#/components/schemas/TextAgentMessageEvent"},{"$ref":"#/components/schemas/TriggerFiredEvent"},{"$ref":"#/components/schemas/TriggerCompletedEvent"},{"$ref":"#/components/schemas/TriggerFailedEvent"},{"$ref":"#/components/schemas/PipelineSyncCompletedEvent"},{"$ref":"#/components/schemas/PipelineErrorEvent"},{"$ref":"#/components/schemas/OperatorRegisteredEvent"},{"$ref":"#/components/schemas/OperatorStatusChangedEvent"},{"$ref":"#/components/schemas/OperatorProfileUpdatedEvent"},{"$ref":"#/components/schemas/OperatorJoinedCallEvent"},{"$ref":"#/components/schemas/OperatorLeftCallEvent"},{"$ref":"#/components/schemas/OperatorModeChangedEvent"},{"$ref":"#/components/schemas/OperatorWrapUpEvent"},{"$ref":"#/components/schemas/WorkspaceMemberAddedEvent"},{"$ref":"#/components/schemas/WorkspaceMemberRoleUpdatedEvent"},{"$ref":"#/components/schemas/WorkspaceInvitationSentEvent"},{"$ref":"#/components/schemas/WorkspaceInvitationAcceptedEvent"}]},"CallStartedEvent":{"properties":{"event_type":{"const":"call.started","default":"call.started","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"direction":{"enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","type":"string"},"service_id":{"format":"uuid","title":"Service Id","type":"string"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caller Id"}},"required":["call_sid","direction","service_id"],"title":"CallStartedEvent","type":"object"},"CallEndedEvent":{"properties":{"event_type":{"const":"call.ended","default":"call.ended","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"direction":{"enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","type":"string"},"duration_seconds":{"title":"Duration Seconds","type":"number"},"completion_reason":{"enum":["completed","abandoned","escalated","transferred","timeout","error","voicemail","no_answer","caller_hangup","forwarded","terminal_state","warm_transfer_completed","no_inbound_audio","cancelled"],"title":"Completion Reason","type":"string"},"escalated":{"default":false,"title":"Escalated","type":"boolean"}},"required":["call_sid","direction","duration_seconds","completion_reason"],"title":"CallEndedEvent","type":"object"},"CallEscalatedEvent":{"properties":{"event_type":{"const":"call.escalated","default":"call.escalated","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"escalation_id":{"title":"Escalation Id","type":"string"},"trigger":{"enum":["caller","ai","operator"],"title":"Trigger","type":"string"},"reason":{"title":"Reason","type":"string"}},"required":["call_sid","escalation_id","trigger","reason"],"title":"CallEscalatedEvent","type":"object"},"EncounterUpdatedEvent":{"properties":{"event_type":{"const":"encounter.updated","default":"encounter.updated","title":"Event Type","type":"string"},"encounter_entity_id":{"format":"uuid","title":"Encounter Entity Id","type":"string"},"session_id":{"title":"Session Id","type":"string"}},"required":["encounter_entity_id","session_id"],"title":"EncounterUpdatedEvent","type":"object"},"NarrativeUpdatedEvent":{"properties":{"event_type":{"const":"self_image.brief_generated","default":"self_image.brief_generated","title":"Event Type","type":"string"},"target_entity_id":{"format":"uuid","title":"Target Entity Id","type":"string"},"target_entity_type":{"title":"Target Entity Type","type":"string"},"event_id":{"format":"uuid","title":"Event Id","type":"string"},"version":{"title":"Version","type":"string"},"confidence":{"title":"Confidence","type":"number"},"event_count":{"title":"Event Count","type":"integer"}},"required":["target_entity_id","target_entity_type","event_id","version","confidence","event_count"],"title":"NarrativeUpdatedEvent","type":"object"},"ReviewSubmittedEvent":{"properties":{"event_type":{"const":"review.submitted","default":"review.submitted","title":"Event Type","type":"string"},"action":{"enum":["approve","reject","correct","batch_approve","batch_reject"],"title":"Action","type":"string"},"item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Item Id"},"entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Entity Id"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Entity Type"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Count"}},"required":["action"],"title":"ReviewSubmittedEvent","type":"object"},"SimulationTurnStoredEvent":{"properties":{"event_type":{"const":"simulation.turn_stored","default":"simulation.turn_stored","title":"Event Type","type":"string"},"service_id":{"format":"uuid","title":"Service Id","type":"string"},"run_id":{"title":"Run Id","type":"string"},"session_id":{"title":"Session Id","type":"string"},"turn_index":{"title":"Turn Index","type":"integer"},"state_before":{"title":"State Before","type":"string"},"state_after":{"title":"State After","type":"string"},"is_terminal":{"title":"Is Terminal","type":"boolean"}},"required":["service_id","run_id","session_id","turn_index","state_before","state_after","is_terminal"],"title":"SimulationTurnStoredEvent","type":"object"},"SurfaceCreatedEvent":{"properties":{"event_type":{"const":"surface.created","default":"surface.created","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Channel"},"fields_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Fields Count"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"form_template_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Form Template Id"},"review_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Review Required"}},"required":["surface_id","entity_id"],"title":"SurfaceCreatedEvent","type":"object"},"SurfaceDeliveredEvent":{"properties":{"event_type":{"const":"surface.delivered","default":"surface.delivered","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"channel":{"title":"Channel","type":"string"},"channel_address":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Channel Address"},"delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Delivery Status"},"message_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Message Id"},"short_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Short Url"}},"required":["surface_id","entity_id","channel"],"title":"SurfaceDeliveredEvent","type":"object"},"SurfaceUpdatedEvent":{"properties":{"event_type":{"const":"surface.updated","default":"surface.updated","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"}},"required":["surface_id"],"title":"SurfaceUpdatedEvent","type":"object"},"SurfaceArchivedEvent":{"properties":{"event_type":{"const":"surface.archived","default":"surface.archived","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"}},"required":["surface_id"],"title":"SurfaceArchivedEvent","type":"object"},"SurfaceReshapedEvent":{"properties":{"event_type":{"const":"surface.reshaped","default":"surface.reshaped","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"original_surface_id":{"format":"uuid","title":"Original Surface Id","type":"string"}},"required":["surface_id","original_surface_id"],"title":"SurfaceReshapedEvent","type":"object"},"SurfaceSubmittedEvent":{"properties":{"event_type":{"const":"surface.submitted","default":"surface.submitted","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Submitted At"},"fields_submitted":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fields Submitted"}},"required":["surface_id","entity_id"],"title":"SurfaceSubmittedEvent","type":"object"},"SurfaceFieldSavedEvent":{"properties":{"event_type":{"const":"surface.field_saved","default":"surface.field_saved","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"field_key":{"title":"Field Key","type":"string"}},"required":["surface_id","entity_id","field_key"],"title":"SurfaceFieldSavedEvent","type":"object"},"SurfaceOpenedEvent":{"properties":{"event_type":{"const":"surface.opened","default":"surface.opened","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"}},"required":["surface_id","entity_id"],"title":"SurfaceOpenedEvent","type":"object"},"SurfacePendingReviewEvent":{"properties":{"event_type":{"const":"surface.pending_review","default":"surface.pending_review","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"form_template_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Form Template Id"},"review_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Review Required"}},"required":["surface_id","entity_id"],"title":"SurfacePendingReviewEvent","type":"object"},"SurfaceReviewApprovedEvent":{"properties":{"event_type":{"const":"surface.review_approved","default":"surface.review_approved","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"}},"required":["surface_id"],"title":"SurfaceReviewApprovedEvent","type":"object"},"SurfaceReviewRejectedEvent":{"properties":{"event_type":{"const":"surface.review_rejected","default":"surface.review_rejected","title":"Event Type","type":"string"},"surface_id":{"format":"uuid","title":"Surface Id","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["surface_id"],"title":"SurfaceReviewRejectedEvent","type":"object"},"IntegrationApprovalGrantedEvent":{"properties":{"event_type":{"const":"integration.approval_granted","default":"integration.approval_granted","title":"Event Type","type":"string"},"conversation_id":{"maxLength":256,"minLength":1,"title":"Conversation Id","type":"string"}},"required":["conversation_id"],"title":"IntegrationApprovalGrantedEvent","type":"object"},"IntegrationApprovalRejectedEvent":{"properties":{"event_type":{"const":"integration.approval_rejected","default":"integration.approval_rejected","title":"Event Type","type":"string"},"conversation_id":{"maxLength":256,"minLength":1,"title":"Conversation Id","type":"string"},"reason":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["conversation_id"],"title":"IntegrationApprovalRejectedEvent","type":"object"},"TextStartedEvent":{"properties":{"event_type":{"const":"text.started","default":"text.started","title":"Event Type","type":"string"},"session_id":{"title":"Session Id","type":"string"},"service_id":{"format":"uuid","title":"Service Id","type":"string"},"channel_kind":{"title":"Channel Kind","type":"string"},"entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Entity Id"}},"required":["session_id","service_id","channel_kind"],"title":"TextStartedEvent","type":"object"},"TextCompletedEvent":{"properties":{"event_type":{"const":"text.completed","default":"text.completed","title":"Event Type","type":"string"},"session_id":{"title":"Session Id","type":"string"},"duration_seconds":{"title":"Duration Seconds","type":"number"},"turn_count":{"title":"Turn Count","type":"integer"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Completion Reason"},"final_state":{"title":"Final State","type":"string"},"channel_kind":{"title":"Channel Kind","type":"string"}},"required":["session_id","duration_seconds","turn_count","final_state","channel_kind"],"title":"TextCompletedEvent","type":"object"},"TextToolStartedEvent":{"description":"A slow text tool *began* running for a web text conversation — pushed live\nthe instant the tool is dispatched, before the 15s blocking floor elapses, so a\nsubscribed client shows progress immediately instead of waiting out the floor in\nsilence (PLA-986). Emitted for tools that route through the background/floor-promoted\ndispatch paths (companion skills and ``execution=\"background\"`` tools) — the ones\nthat can outlast the turn's synchronous response.\n\nThe start/completion pair share one card identity: ``call_id`` is ``bg:``,\nmatching the eventual ``TextBackgroundResultEvent`` (and the next-turn drained card\nfrom ``build_background_completion_effect``), so a client collapses started → result\ninto one card rather than rendering two. Web-only: ``conversation_id`` is the durable\nconversation UUID (non-web channels route by a composite key and deliver via their own\ntransport).","properties":{"event_type":{"const":"text.tool_started","default":"text.tool_started","title":"Event Type","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"tool_name":{"title":"Tool Name","type":"string"},"call_id":{"title":"Call Id","type":"string"},"depth":{"title":"Depth","type":"integer"}},"required":["conversation_id","tool_name","call_id","depth"],"title":"TextToolStartedEvent","type":"object"},"TextBackgroundResultEvent":{"description":"A background (``execution=\"background\"``) tool finished for a web text\nconversation. Pushed live the instant the completion lands so a subscribed\nclient renders the result without polling or sending another message.\n\n``call_id`` is ``bg:`` to match the card identity the next-turn drain\nsurfaces (``build_background_completion_effect``), so a client that receives\nboth the live push and the eventual drained card sees one consistent card.\nWeb-only: ``conversation_id`` is the durable conversation UUID (non-web\nchannels route by a composite key and deliver via their own transport).","properties":{"event_type":{"const":"text.background_result","default":"text.background_result","title":"Event Type","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"tool_name":{"title":"Tool Name","type":"string"},"call_id":{"title":"Call Id","type":"string"},"succeeded":{"title":"Succeeded","type":"boolean"},"result":{"title":"Result","type":"string"},"depth":{"title":"Depth","type":"integer"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Duration Ms"}},"required":["conversation_id","tool_name","call_id","succeeded","result","depth"],"title":"TextBackgroundResultEvent","type":"object"},"TextAgentMessageEvent":{"description":"An agent text turn pushed live over workspace SSE — the outbox of the\ndurable text-conversation actor (text-conversation-actor Stage A).\n\nWhere ``TextBackgroundResultEvent`` surfaces the raw tool card,\nthis carries the agent's *narrated* response (the turn the actor produces after\nre-entering on a background completion or other off-request signal), so a\nsubscribed web client renders it as a normal agent message with no polling and\nno user turn. ``conversation_id`` is the durable conversation UUID (web-only).","properties":{"event_type":{"const":"text.agent_message","default":"text.agent_message","title":"Event Type","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"text":{"title":"Text","type":"string"},"delivery_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Delivery Id"}},"required":["conversation_id","text"],"title":"TextAgentMessageEvent","type":"object"},"TriggerFiredEvent":{"properties":{"event_type":{"const":"trigger.fired","default":"trigger.fired","title":"Event Type","type":"string"},"trigger_id":{"format":"uuid","title":"Trigger Id","type":"string"},"trigger_name":{"title":"Trigger Name","type":"string"},"manual":{"default":false,"title":"Manual","type":"boolean"}},"required":["trigger_id","trigger_name"],"title":"TriggerFiredEvent","type":"object"},"TriggerCompletedEvent":{"properties":{"event_type":{"const":"trigger.completed","default":"trigger.completed","title":"Event Type","type":"string"},"trigger_id":{"format":"uuid","title":"Trigger Id","type":"string"},"trigger_name":{"title":"Trigger Name","type":"string"},"status":{"title":"Status","type":"string"}},"required":["trigger_id","trigger_name","status"],"title":"TriggerCompletedEvent","type":"object"},"TriggerFailedEvent":{"properties":{"event_type":{"const":"trigger.failed","default":"trigger.failed","title":"Event Type","type":"string"},"trigger_id":{"format":"uuid","title":"Trigger Id","type":"string"},"trigger_name":{"title":"Trigger Name","type":"string"},"status":{"title":"Status","type":"string"}},"required":["trigger_id","trigger_name","status"],"title":"TriggerFailedEvent","type":"object"},"PipelineSyncCompletedEvent":{"properties":{"event_type":{"const":"pipeline.sync_completed","default":"pipeline.sync_completed","title":"Event Type","type":"string"},"data_source_id":{"format":"uuid","title":"Data Source Id","type":"string"},"event_count":{"title":"Event Count","type":"integer"},"duration_ms":{"title":"Duration Ms","type":"integer"}},"required":["data_source_id","event_count","duration_ms"],"title":"PipelineSyncCompletedEvent","type":"object"},"PipelineErrorEvent":{"properties":{"event_type":{"const":"pipeline.error","default":"pipeline.error","title":"Event Type","type":"string"},"data_source_id":{"format":"uuid","title":"Data Source Id","type":"string"},"error":{"title":"Error","type":"string"}},"required":["data_source_id","error"],"title":"PipelineErrorEvent","type":"object"},"OperatorRegisteredEvent":{"properties":{"event_type":{"const":"operator.registered","default":"operator.registered","title":"Event Type","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timestamp"}},"required":["operator_id"],"title":"OperatorRegisteredEvent","type":"object"},"OperatorStatusChangedEvent":{"properties":{"event_type":{"const":"operator.status_changed","default":"operator.status_changed","title":"Event Type","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"status":{"enum":["online","busy","offline"],"title":"Status","type":"string"}},"required":["operator_id","status"],"title":"OperatorStatusChangedEvent","type":"object"},"OperatorProfileUpdatedEvent":{"properties":{"event_type":{"const":"operator.profile_updated","default":"operator.profile_updated","title":"Event Type","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"changes":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"default":null,"title":"Changes"}},"required":["operator_id"],"title":"OperatorProfileUpdatedEvent","type":"object"},"OperatorJoinedCallEvent":{"properties":{"event_type":{"const":"operator.joined_call","default":"operator.joined_call","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"mode":{"enum":["listen","takeover"],"title":"Mode","type":"string"}},"required":["call_sid","operator_id","mode"],"title":"OperatorJoinedCallEvent","type":"object"},"OperatorLeftCallEvent":{"properties":{"event_type":{"const":"operator.left_call","default":"operator.left_call","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"human_segment_turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Human Segment Turn Count"}},"required":["call_sid","operator_id"],"title":"OperatorLeftCallEvent","type":"object"},"OperatorModeChangedEvent":{"properties":{"event_type":{"const":"operator.mode_changed","default":"operator.mode_changed","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"operator_id":{"format":"uuid","title":"Operator Id","type":"string"},"mode":{"enum":["listen","takeover"],"title":"Mode","type":"string"}},"required":["call_sid","operator_id","mode"],"title":"OperatorModeChangedEvent","type":"object"},"OperatorWrapUpEvent":{"properties":{"event_type":{"const":"operator.wrap_up","default":"operator.wrap_up","title":"Event Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"wrap_up_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Wrap Up Reason"}},"required":["call_sid"],"title":"OperatorWrapUpEvent","type":"object"},"WorkspaceMemberAddedEvent":{"properties":{"event_type":{"const":"workspace.member_added","default":"workspace.member_added","title":"Event Type","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"role":{"title":"Role","type":"string"}},"required":["entity_id","role"],"title":"WorkspaceMemberAddedEvent","type":"object"},"WorkspaceMemberRoleUpdatedEvent":{"properties":{"event_type":{"const":"workspace.member_role_updated","default":"workspace.member_role_updated","title":"Event Type","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"role":{"title":"Role","type":"string"},"previous_role":{"title":"Previous Role","type":"string"}},"required":["entity_id","role","previous_role"],"title":"WorkspaceMemberRoleUpdatedEvent","type":"object"},"WorkspaceInvitationSentEvent":{"properties":{"event_type":{"const":"workspace.invitation_sent","default":"workspace.invitation_sent","title":"Event Type","type":"string"},"invitation_id":{"title":"Invitation Id","type":"string"},"role":{"title":"Role","type":"string"},"resent":{"default":false,"title":"Resent","type":"boolean"}},"required":["invitation_id","role"],"title":"WorkspaceInvitationSentEvent","type":"object"},"WorkspaceInvitationAcceptedEvent":{"properties":{"event_type":{"const":"workspace.invitation_accepted","default":"workspace.invitation_accepted","title":"Event Type","type":"string"},"entity_id":{"format":"uuid","title":"Entity Id","type":"string"},"role":{"title":"Role","type":"string"}},"required":["entity_id","role"],"title":"WorkspaceInvitationAcceptedEvent","type":"object"}}}} ``` ## The ActorAllocatedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ActorAllocatedEvent":{"description":"The call was bound to its isolated runtime — one call = one Agones GameServer.\n\nEmitted by the dispatcher the moment it allocates a warm GameServer for the call,\nso an observer can see WHICH pod/node powers this call and how long allocation took.","properties":{"type":{"const":"actor_allocated","default":"actor_allocated","title":"Type","type":"string"},"gameserver":{"maxLength":256,"title":"Gameserver","type":"string"},"node":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Node"},"alloc_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Alloc Latency Ms"}},"required":["gameserver"],"title":"ActorAllocatedEvent","type":"object"}}}} ``` ## The ActorShutdownEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ActorShutdownEvent":{"description":"The call's GameServer was reaped (Allocated GameServers are deploy-immune).\n\nToday only ``reason=call_ended`` is produced (normal call-end teardown).\n``orphan_no_media`` is reserved in the contract for the orphan reaper — a pod that\nwent Allocated but never received media — but that emit is not yet wired: at reap\ntime the reaper pod has no call identity (allocation is cross-pod), so plumbing the\ncall_sid to it is a follow-up. The value is pre-declared so adding it later is a\nnon-breaking widening for SDK consumers, not a breaking enum change.","properties":{"type":{"const":"actor_shutdown","default":"actor_shutdown","title":"Type","type":"string"},"reason":{"default":"call_ended","enum":["call_ended","orphan_no_media"],"title":"Reason","type":"string"},"lifetime_s":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Lifetime S"}},"title":"ActorShutdownEvent","type":"object"}}}} ``` ## The AgentTranscriptDeltaEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentTranscriptDeltaEvent":{"properties":{"type":{"const":"agent_transcript_delta","default":"agent_transcript_delta","title":"Type","type":"string"},"delta":{"title":"Delta","type":"string"}},"required":["delta"],"title":"AgentTranscriptDeltaEvent","type":"object"}}}} ``` ## The AgentTranscriptEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"AgentTranscriptEvent":{"properties":{"type":{"const":"agent_transcript","default":"agent_transcript","title":"Type","type":"string"},"transcript":{"title":"Transcript","type":"string"},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Action"},"interrupted":{"default":false,"title":"Interrupted","type":"boolean"},"filler_type":{"anyOf":[{"enum":["empathy","receipt","working"],"type":"string"},{"type":"null"}],"default":null,"title":"Filler Type"},"speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Id"},"speaker_role":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Role"},"streaming":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Streaming"}},"required":["transcript"],"title":"AgentTranscriptEvent","type":"object"}}}} ``` ## The CompoundEmotionEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"CompoundEmotionEvent":{"properties":{"type":{"const":"compound_emotion","default":"compound_emotion","title":"Type","type":"string"},"compounds":{"items":{"$ref":"#/components/schemas/EmotionScore"},"title":"Compounds","type":"array"},"turn_index":{"title":"Turn Index","type":"integer"}},"required":["compounds","turn_index"],"title":"CompoundEmotionEvent","type":"object"},"EmotionScore":{"properties":{"name":{"title":"Name","type":"string"},"score":{"title":"Score","type":"number"}},"required":["name","score"],"title":"EmotionScore","type":"object"}}}} ``` ## The EmotionEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EmotionEvent":{"properties":{"type":{"const":"emotion","default":"emotion","title":"Type","type":"string"},"dominant":{"title":"Dominant","type":"string"},"valence":{"title":"Valence","type":"number"},"arousal":{"title":"Arousal","type":"number"},"barge_in_count":{"default":0,"title":"Barge In Count","type":"integer"},"trend":{"anyOf":[{"enum":["improving","stable","deteriorating"],"type":"string"},{"type":"null"}],"default":null,"title":"Trend"},"coherence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Coherence"},"segment_dominant":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Segment Dominant"},"segment_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Segment Valence"},"segment_arousal":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Segment Arousal"},"dominance":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Dominance"},"scores":{"anyOf":[{"items":{"$ref":"#/components/schemas/EmotionScore"},"type":"array"},{"type":"null"}],"default":null,"title":"Scores"},"language_sentiment":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Language Sentiment"},"language_toxicity":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"title":"Language Toxicity"},"speaker":{"anyOf":[{"$ref":"#/components/schemas/SpeakerAcoustics"},{"type":"null"}],"default":null},"total_segments":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Segments"},"emotional_shifts":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Emotional Shifts"},"call_duration_s":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Call Duration S"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Turn Count"},"verified_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Verified Speaker Id"},"speaker_similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Speaker Similarity"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider"}},"required":["dominant","valence","arousal"],"title":"EmotionEvent","type":"object"},"EmotionScore":{"properties":{"name":{"title":"Name","type":"string"},"score":{"title":"Score","type":"number"}},"required":["name","score"],"title":"EmotionScore","type":"object"},"SpeakerAcoustics":{"properties":{"energy_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Energy Delta"},"pitch_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Pitch Delta"},"zcr_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Zcr Delta"},"energy_trend":{"anyOf":[{"enum":["rising","falling","stable"],"type":"string"},{"type":"null"}],"default":null,"title":"Energy Trend"},"normalized":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Normalized"}},"title":"SpeakerAcoustics","type":"object"}}}} ``` ## The EmotionScore object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EmotionScore":{"properties":{"name":{"title":"Name","type":"string"},"score":{"title":"Score","type":"number"}},"required":["name","score"],"title":"EmotionScore","type":"object"}}}} ``` ## The EmpathyClassifiedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"EmpathyClassifiedEvent":{"properties":{"type":{"const":"empathy_classified","default":"empathy_classified","title":"Type","type":"string"},"tier":{"title":"Tier","type":"integer"},"tier_name":{"enum":["FUNCTIONAL","LIGHT_TOUCH","FULL_EMPATHY","HOLD_SPACE"],"title":"Tier Name","type":"string"},"should_pause":{"title":"Should Pause","type":"boolean"},"suppress_filler":{"title":"Suppress Filler","type":"boolean"},"filler_type":{"enum":["empathy","receipt","working"],"title":"Filler Type","type":"string"},"empathy_baseline":{"title":"Empathy Baseline","type":"number"}},"required":["tier","tier_name","should_pause","suppress_filler","filler_type","empathy_baseline"],"title":"EmpathyClassifiedEvent","type":"object"}}}} ``` ## The ForwardCallResolvedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ForwardCallResolvedEvent":{"properties":{"type":{"const":"forward_call_resolved","default":"forward_call_resolved","title":"Type","type":"string"},"target_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Target Number"},"location_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Location Name"},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"}},"title":"ForwardCallResolvedEvent","type":"object"}}}} ``` ## The LatencyEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"LatencyEvent":{"properties":{"type":{"const":"latency","default":"latency","title":"Type","type":"string"},"e2e_ttfb_ms":{"title":"E2E Ttfb Ms","type":"number"},"engine_ms":{"title":"Engine Ms","type":"number"},"nav_ms":{"title":"Nav Ms","type":"number"},"render_ms":{"title":"Render Ms","type":"number"},"audio_ttfb_ms":{"title":"Audio Ttfb Ms","type":"number"},"continuation":{"title":"Continuation","type":"boolean"},"is_greeting":{"default":false,"title":"Is Greeting","type":"boolean"}},"required":["e2e_ttfb_ms","engine_ms","nav_ms","render_ms","audio_ttfb_ms","continuation"],"title":"LatencyEvent","type":"object"}}}} ``` ## The MediaAttachedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"MediaAttachedEvent":{"description":"A media WebSocket actually reached the call's GameServer — the audio-path signal.\n\nFires once per leg (caller / agent). Its ABSENCE for a leg is the no-audio failure\nmode (media never landed on the pod). The per-call cold-start / time-to-first-speech\nmetric is deliberately NOT carried here yet: TTFS is measured against the first\nsynthesized-audio frame, a signal not available at attach time, so it is wired in a\nfocused follow-up (Front 3) rather than shipped as a permanently-null field that would\nlock a misleading shape into the SDK contract.","properties":{"type":{"const":"media_attached","default":"media_attached","title":"Type","type":"string"},"leg":{"enum":["caller","agent","operator"],"title":"Leg","type":"string"}},"required":["leg"],"title":"MediaAttachedEvent","type":"object"}}}} ``` ## The NavTimingEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"NavTimingEvent":{"properties":{"type":{"const":"nav_timing","default":"nav_timing","title":"Type","type":"string"},"nav_ms":{"title":"Nav Ms","type":"number"},"render_ms":{"title":"Render Ms","type":"number"},"total_ms":{"title":"Total Ms","type":"number"},"input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Input Tokens"},"output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Output Tokens"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Model"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"retry_attempts":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Retry Attempts"},"used_fallback":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Used Fallback"},"selected_action":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Selected Action"}},"required":["nav_ms","render_ms","total_ms"],"title":"NavTimingEvent","type":"object"}}}} ``` ## The ParticipantJoinedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ParticipantJoinedEvent":{"properties":{"type":{"const":"participant_joined","default":"participant_joined","title":"Type","type":"string"},"participant_id":{"title":"Participant Id","type":"string"},"participant_role":{"enum":["caller","agent","operator"],"title":"Participant Role","type":"string"},"conference_sid":{"title":"Conference Sid","type":"string"},"participant_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Participant Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"operator_entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Operator Entity Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"}},"required":["participant_id","participant_role","conference_sid"],"title":"ParticipantJoinedEvent","type":"object"}}}} ``` ## The ParticipantLeftEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ParticipantLeftEvent":{"properties":{"type":{"const":"participant_left","default":"participant_left","title":"Type","type":"string"},"participant_id":{"title":"Participant Id","type":"string"},"participant_role":{"enum":["caller","agent","operator"],"title":"Participant Role","type":"string"},"conference_sid":{"title":"Conference Sid","type":"string"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"operator_entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Operator Entity Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"}},"required":["participant_id","participant_role","conference_sid"],"title":"ParticipantLeftEvent","type":"object"}}}} ``` ## The SessionEndEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SessionEndEvent":{"properties":{"type":{"const":"session_end","default":"session_end","title":"Type","type":"string"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Call Sid"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Session Id"},"duration_s":{"default":0,"title":"Duration S","type":"number"},"turns":{"default":0,"title":"Turns","type":"integer"},"completion_reason":{"default":"","title":"Completion Reason","type":"string"},"final_state":{"default":"","title":"Final State","type":"string"},"trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Trace Id"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Has Recording"},"emotional_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Emotional Summary"}},"title":"SessionEndEvent","type":"object"}}}} ``` ## The SessionInfoEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SessionInfoEvent":{"properties":{"type":{"const":"session_info","default":"session_info","title":"Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"service_id":{"default":"","title":"Service Id","type":"string"},"workspace_id":{"default":"","title":"Workspace Id","type":"string"},"caller_id":{"default":"","title":"Caller Id","type":"string"},"start_time":{"default":0,"title":"Start Time","type":"number"},"current_state":{"default":"","title":"Current State","type":"string"},"direction":{"default":"inbound","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","type":"string"},"duration_seconds":{"default":0,"title":"Duration Seconds","type":"number"}},"required":["call_sid"],"title":"SessionInfoEvent","type":"object"}}}} ``` ## The SessionStartEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SessionStartEvent":{"properties":{"type":{"const":"session_start","default":"session_start","title":"Type","type":"string"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Call Sid"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Session Id"},"service_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Service Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Workspace Id"},"initial_state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Initial State"},"trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Trace Id"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mode"}},"title":"SessionStartEvent","type":"object"}}}} ``` ## The SpeakerAcoustics object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SpeakerAcoustics":{"properties":{"energy_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Energy Delta"},"pitch_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Pitch Delta"},"zcr_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Zcr Delta"},"energy_trend":{"anyOf":[{"enum":["rising","falling","stable"],"type":"string"},{"type":"null"}],"default":null,"title":"Energy Trend"},"normalized":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Normalized"}},"title":"SpeakerAcoustics","type":"object"}}}} ``` ## The SpeakerMutedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"SpeakerMutedEvent":{"properties":{"type":{"const":"speaker_muted","default":"speaker_muted","title":"Type","type":"string"},"muted":{"title":"Muted","type":"boolean"}},"required":["muted"],"title":"SpeakerMutedEvent","type":"object"}}}} ``` ## The StateTransitionEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"StateTransitionEvent":{"properties":{"type":{"const":"state_transition","default":"state_transition","title":"Type","type":"string"},"previous_state":{"title":"Previous State","type":"string"},"next_state":{"title":"Next State","type":"string"},"transition_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transition Type"},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Annotation"}},"required":["previous_state","next_state"],"title":"StateTransitionEvent","type":"object"}}}} ``` ## The ToolCallCompletedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolCallCompletedEvent":{"properties":{"type":{"const":"tool_call_completed","default":"tool_call_completed","title":"Type","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Output"},"succeeded":{"default":true,"title":"Succeeded","type":"boolean"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Duration Ms"},"error_message":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"default":null,"title":"Error Message"},"parent_call_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Parent Call Id"},"integration_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Integration Name"},"endpoint_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Endpoint Name"},"protocol":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Protocol"}},"required":["tool_name","call_id"],"title":"ToolCallCompletedEvent","type":"object"}}}} ``` ## The ToolCallStartedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ToolCallStartedEvent":{"properties":{"type":{"const":"tool_call_started","default":"tool_call_started","title":"Type","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"default":null,"title":"Input"},"parent_call_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Parent Call Id"},"integration_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Integration Name"},"endpoint_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Endpoint Name"},"protocol":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Protocol"}},"required":["tool_name","call_id"],"title":"ToolCallStartedEvent","type":"object"}}}} ``` ## The UserTranscriptEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"UserTranscriptEvent":{"properties":{"type":{"const":"user_transcript","default":"user_transcript","title":"Type","type":"string"},"transcript":{"title":"Transcript","type":"string"},"state":{"default":"","title":"State","type":"string"},"speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Id"},"speaker_role":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Role"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Eot Confidence"},"is_barge_in":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Is Barge In"}},"required":["transcript"],"title":"UserTranscriptEvent","type":"object"}}}} ``` ## The VoiceContextAppliedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"VoiceContextAppliedEvent":{"properties":{"type":{"const":"voice_context_applied","default":"voice_context_applied","title":"Type","type":"string"},"tts_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tts Emotion"},"tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Tts Speed"},"tts_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Tts Volume"},"filler_enabled":{"title":"Filler Enabled","type":"boolean"},"emotion_detection_enabled":{"title":"Emotion Detection Enabled","type":"boolean"},"reasoning":{"title":"Reasoning","type":"string"}},"required":["filler_enabled","emotion_detection_enabled","reasoning"],"title":"VoiceContextAppliedEvent","type":"object"}}}} ``` ## The ObserverSSEEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"ObserverSSEEvent":{"discriminator":{"mapping":{"actor_allocated":"#/components/schemas/ActorAllocatedEvent","actor_shutdown":"#/components/schemas/ActorShutdownEvent","agent_transcript":"#/components/schemas/AgentTranscriptEvent","agent_transcript_delta":"#/components/schemas/AgentTranscriptDeltaEvent","barge_in":"#/components/schemas/BargeInEvent","compound_emotion":"#/components/schemas/CompoundEmotionEvent","emotion":"#/components/schemas/EmotionEvent","empathy_classified":"#/components/schemas/EmpathyClassifiedEvent","forward_call_resolved":"#/components/schemas/ForwardCallResolvedEvent","latency":"#/components/schemas/LatencyEvent","media_attached":"#/components/schemas/MediaAttachedEvent","nav_timing":"#/components/schemas/NavTimingEvent","participant_joined":"#/components/schemas/ParticipantJoinedEvent","participant_left":"#/components/schemas/ParticipantLeftEvent","session_end":"#/components/schemas/SessionEndEvent","session_info":"#/components/schemas/SessionInfoEvent","session_start":"#/components/schemas/SessionStartEvent","speaker_muted":"#/components/schemas/SpeakerMutedEvent","state_transition":"#/components/schemas/StateTransitionEvent","tool_call_completed":"#/components/schemas/ToolCallCompletedEvent","tool_call_started":"#/components/schemas/ToolCallStartedEvent","user_transcript":"#/components/schemas/UserTranscriptEvent","voice_context_applied":"#/components/schemas/VoiceContextAppliedEvent"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/ActorAllocatedEvent"},{"$ref":"#/components/schemas/ActorShutdownEvent"},{"$ref":"#/components/schemas/AgentTranscriptDeltaEvent"},{"$ref":"#/components/schemas/AgentTranscriptEvent"},{"$ref":"#/components/schemas/BargeInEvent"},{"$ref":"#/components/schemas/CompoundEmotionEvent"},{"$ref":"#/components/schemas/EmotionEvent"},{"$ref":"#/components/schemas/EmpathyClassifiedEvent"},{"$ref":"#/components/schemas/ForwardCallResolvedEvent"},{"$ref":"#/components/schemas/LatencyEvent"},{"$ref":"#/components/schemas/MediaAttachedEvent"},{"$ref":"#/components/schemas/NavTimingEvent"},{"$ref":"#/components/schemas/ParticipantJoinedEvent"},{"$ref":"#/components/schemas/ParticipantLeftEvent"},{"$ref":"#/components/schemas/SessionEndEvent"},{"$ref":"#/components/schemas/SessionInfoEvent"},{"$ref":"#/components/schemas/SessionStartEvent"},{"$ref":"#/components/schemas/SpeakerMutedEvent"},{"$ref":"#/components/schemas/StateTransitionEvent"},{"$ref":"#/components/schemas/ToolCallCompletedEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/UserTranscriptEvent"},{"$ref":"#/components/schemas/VoiceContextAppliedEvent"}]},"ActorAllocatedEvent":{"description":"The call was bound to its isolated runtime — one call = one Agones GameServer.\n\nEmitted by the dispatcher the moment it allocates a warm GameServer for the call,\nso an observer can see WHICH pod/node powers this call and how long allocation took.","properties":{"type":{"const":"actor_allocated","default":"actor_allocated","title":"Type","type":"string"},"gameserver":{"maxLength":256,"title":"Gameserver","type":"string"},"node":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Node"},"alloc_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Alloc Latency Ms"}},"required":["gameserver"],"title":"ActorAllocatedEvent","type":"object"},"ActorShutdownEvent":{"description":"The call's GameServer was reaped (Allocated GameServers are deploy-immune).\n\nToday only ``reason=call_ended`` is produced (normal call-end teardown).\n``orphan_no_media`` is reserved in the contract for the orphan reaper — a pod that\nwent Allocated but never received media — but that emit is not yet wired: at reap\ntime the reaper pod has no call identity (allocation is cross-pod), so plumbing the\ncall_sid to it is a follow-up. The value is pre-declared so adding it later is a\nnon-breaking widening for SDK consumers, not a breaking enum change.","properties":{"type":{"const":"actor_shutdown","default":"actor_shutdown","title":"Type","type":"string"},"reason":{"default":"call_ended","enum":["call_ended","orphan_no_media"],"title":"Reason","type":"string"},"lifetime_s":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Lifetime S"}},"title":"ActorShutdownEvent","type":"object"},"AgentTranscriptDeltaEvent":{"properties":{"type":{"const":"agent_transcript_delta","default":"agent_transcript_delta","title":"Type","type":"string"},"delta":{"title":"Delta","type":"string"}},"required":["delta"],"title":"AgentTranscriptDeltaEvent","type":"object"},"AgentTranscriptEvent":{"properties":{"type":{"const":"agent_transcript","default":"agent_transcript","title":"Type","type":"string"},"transcript":{"title":"Transcript","type":"string"},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Action"},"interrupted":{"default":false,"title":"Interrupted","type":"boolean"},"filler_type":{"anyOf":[{"enum":["empathy","receipt","working"],"type":"string"},{"type":"null"}],"default":null,"title":"Filler Type"},"speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Id"},"speaker_role":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Role"},"streaming":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Streaming"}},"required":["transcript"],"title":"AgentTranscriptEvent","type":"object"},"BargeInEvent":{"properties":{"type":{"const":"barge_in","default":"barge_in","title":"Type","type":"string"},"interrupted_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupted Text"},"discarded_texts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Discarded Texts"},"interrupted_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupted Speaker Id"},"interrupting_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Interrupting Speaker Id"},"total_barge_ins":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Barge Ins"}},"title":"BargeInEvent","type":"object"},"CompoundEmotionEvent":{"properties":{"type":{"const":"compound_emotion","default":"compound_emotion","title":"Type","type":"string"},"compounds":{"items":{"$ref":"#/components/schemas/EmotionScore"},"title":"Compounds","type":"array"},"turn_index":{"title":"Turn Index","type":"integer"}},"required":["compounds","turn_index"],"title":"CompoundEmotionEvent","type":"object"},"EmotionScore":{"properties":{"name":{"title":"Name","type":"string"},"score":{"title":"Score","type":"number"}},"required":["name","score"],"title":"EmotionScore","type":"object"},"EmotionEvent":{"properties":{"type":{"const":"emotion","default":"emotion","title":"Type","type":"string"},"dominant":{"title":"Dominant","type":"string"},"valence":{"title":"Valence","type":"number"},"arousal":{"title":"Arousal","type":"number"},"barge_in_count":{"default":0,"title":"Barge In Count","type":"integer"},"trend":{"anyOf":[{"enum":["improving","stable","deteriorating"],"type":"string"},{"type":"null"}],"default":null,"title":"Trend"},"coherence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Coherence"},"segment_dominant":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Segment Dominant"},"segment_valence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Segment Valence"},"segment_arousal":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Segment Arousal"},"dominance":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Dominance"},"scores":{"anyOf":[{"items":{"$ref":"#/components/schemas/EmotionScore"},"type":"array"},{"type":"null"}],"default":null,"title":"Scores"},"language_sentiment":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Language Sentiment"},"language_toxicity":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"title":"Language Toxicity"},"speaker":{"anyOf":[{"$ref":"#/components/schemas/SpeakerAcoustics"},{"type":"null"}],"default":null},"total_segments":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Segments"},"emotional_shifts":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Emotional Shifts"},"call_duration_s":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Call Duration S"},"turn_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Turn Count"},"verified_speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Verified Speaker Id"},"speaker_similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Speaker Similarity"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider"}},"required":["dominant","valence","arousal"],"title":"EmotionEvent","type":"object"},"SpeakerAcoustics":{"properties":{"energy_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Energy Delta"},"pitch_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Pitch Delta"},"zcr_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Zcr Delta"},"energy_trend":{"anyOf":[{"enum":["rising","falling","stable"],"type":"string"},{"type":"null"}],"default":null,"title":"Energy Trend"},"normalized":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Normalized"}},"title":"SpeakerAcoustics","type":"object"},"EmpathyClassifiedEvent":{"properties":{"type":{"const":"empathy_classified","default":"empathy_classified","title":"Type","type":"string"},"tier":{"title":"Tier","type":"integer"},"tier_name":{"enum":["FUNCTIONAL","LIGHT_TOUCH","FULL_EMPATHY","HOLD_SPACE"],"title":"Tier Name","type":"string"},"should_pause":{"title":"Should Pause","type":"boolean"},"suppress_filler":{"title":"Suppress Filler","type":"boolean"},"filler_type":{"enum":["empathy","receipt","working"],"title":"Filler Type","type":"string"},"empathy_baseline":{"title":"Empathy Baseline","type":"number"}},"required":["tier","tier_name","should_pause","suppress_filler","filler_type","empathy_baseline"],"title":"EmpathyClassifiedEvent","type":"object"},"ForwardCallResolvedEvent":{"properties":{"type":{"const":"forward_call_resolved","default":"forward_call_resolved","title":"Type","type":"string"},"target_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Target Number"},"location_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Location Name"},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"}},"title":"ForwardCallResolvedEvent","type":"object"},"LatencyEvent":{"properties":{"type":{"const":"latency","default":"latency","title":"Type","type":"string"},"e2e_ttfb_ms":{"title":"E2E Ttfb Ms","type":"number"},"engine_ms":{"title":"Engine Ms","type":"number"},"nav_ms":{"title":"Nav Ms","type":"number"},"render_ms":{"title":"Render Ms","type":"number"},"audio_ttfb_ms":{"title":"Audio Ttfb Ms","type":"number"},"continuation":{"title":"Continuation","type":"boolean"},"is_greeting":{"default":false,"title":"Is Greeting","type":"boolean"}},"required":["e2e_ttfb_ms","engine_ms","nav_ms","render_ms","audio_ttfb_ms","continuation"],"title":"LatencyEvent","type":"object"},"MediaAttachedEvent":{"description":"A media WebSocket actually reached the call's GameServer — the audio-path signal.\n\nFires once per leg (caller / agent). Its ABSENCE for a leg is the no-audio failure\nmode (media never landed on the pod). The per-call cold-start / time-to-first-speech\nmetric is deliberately NOT carried here yet: TTFS is measured against the first\nsynthesized-audio frame, a signal not available at attach time, so it is wired in a\nfocused follow-up (Front 3) rather than shipped as a permanently-null field that would\nlock a misleading shape into the SDK contract.","properties":{"type":{"const":"media_attached","default":"media_attached","title":"Type","type":"string"},"leg":{"enum":["caller","agent","operator"],"title":"Leg","type":"string"}},"required":["leg"],"title":"MediaAttachedEvent","type":"object"},"NavTimingEvent":{"properties":{"type":{"const":"nav_timing","default":"nav_timing","title":"Type","type":"string"},"nav_ms":{"title":"Nav Ms","type":"number"},"render_ms":{"title":"Render Ms","type":"number"},"total_ms":{"title":"Total Ms","type":"number"},"input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Input Tokens"},"output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Output Tokens"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Model"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"retry_attempts":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Retry Attempts"},"used_fallback":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Used Fallback"},"selected_action":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Selected Action"}},"required":["nav_ms","render_ms","total_ms"],"title":"NavTimingEvent","type":"object"},"ParticipantJoinedEvent":{"properties":{"type":{"const":"participant_joined","default":"participant_joined","title":"Type","type":"string"},"participant_id":{"title":"Participant Id","type":"string"},"participant_role":{"enum":["caller","agent","operator"],"title":"Participant Role","type":"string"},"conference_sid":{"title":"Conference Sid","type":"string"},"participant_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Participant Name"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"operator_entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Operator Entity Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"}},"required":["participant_id","participant_role","conference_sid"],"title":"ParticipantJoinedEvent","type":"object"},"ParticipantLeftEvent":{"properties":{"type":{"const":"participant_left","default":"participant_left","title":"Type","type":"string"},"participant_id":{"title":"Participant Id","type":"string"},"participant_role":{"enum":["caller","agent","operator"],"title":"Participant Role","type":"string"},"conference_sid":{"title":"Conference Sid","type":"string"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"operator_entity_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Operator Entity Id"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"}},"required":["participant_id","participant_role","conference_sid"],"title":"ParticipantLeftEvent","type":"object"},"SessionEndEvent":{"properties":{"type":{"const":"session_end","default":"session_end","title":"Type","type":"string"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Call Sid"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Session Id"},"duration_s":{"default":0,"title":"Duration S","type":"number"},"turns":{"default":0,"title":"Turns","type":"integer"},"completion_reason":{"default":"","title":"Completion Reason","type":"string"},"final_state":{"default":"","title":"Final State","type":"string"},"trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Trace Id"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Has Recording"},"emotional_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Emotional Summary"}},"title":"SessionEndEvent","type":"object"},"SessionInfoEvent":{"properties":{"type":{"const":"session_info","default":"session_info","title":"Type","type":"string"},"call_sid":{"title":"Call Sid","type":"string"},"service_id":{"default":"","title":"Service Id","type":"string"},"workspace_id":{"default":"","title":"Workspace Id","type":"string"},"caller_id":{"default":"","title":"Caller Id","type":"string"},"start_time":{"default":0,"title":"Start Time","type":"number"},"current_state":{"default":"","title":"Current State","type":"string"},"direction":{"default":"inbound","enum":["inbound","outbound","playground","simulated","test"],"title":"Direction","type":"string"},"duration_seconds":{"default":0,"title":"Duration Seconds","type":"number"}},"required":["call_sid"],"title":"SessionInfoEvent","type":"object"},"SessionStartEvent":{"properties":{"type":{"const":"session_start","default":"session_start","title":"Type","type":"string"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Call Sid"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Session Id"},"service_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Service Id"},"workspace_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Workspace Id"},"initial_state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Initial State"},"trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Trace Id"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mode"}},"title":"SessionStartEvent","type":"object"},"SpeakerMutedEvent":{"properties":{"type":{"const":"speaker_muted","default":"speaker_muted","title":"Type","type":"string"},"muted":{"title":"Muted","type":"boolean"}},"required":["muted"],"title":"SpeakerMutedEvent","type":"object"},"StateTransitionEvent":{"properties":{"type":{"const":"state_transition","default":"state_transition","title":"Type","type":"string"},"previous_state":{"title":"Previous State","type":"string"},"next_state":{"title":"Next State","type":"string"},"transition_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Transition Type"},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Annotation"}},"required":["previous_state","next_state"],"title":"StateTransitionEvent","type":"object"},"ToolCallCompletedEvent":{"properties":{"type":{"const":"tool_call_completed","default":"tool_call_completed","title":"Type","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Output"},"succeeded":{"default":true,"title":"Succeeded","type":"boolean"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Duration Ms"},"error_message":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"default":null,"title":"Error Message"},"parent_call_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Parent Call Id"},"integration_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Integration Name"},"endpoint_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Endpoint Name"},"protocol":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Protocol"}},"required":["tool_name","call_id"],"title":"ToolCallCompletedEvent","type":"object"},"ToolCallStartedEvent":{"properties":{"type":{"const":"tool_call_started","default":"tool_call_started","title":"Type","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"default":null,"title":"Input"},"parent_call_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Parent Call Id"},"integration_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Integration Name"},"endpoint_name":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Endpoint Name"},"protocol":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Protocol"}},"required":["tool_name","call_id"],"title":"ToolCallStartedEvent","type":"object"},"UserTranscriptEvent":{"properties":{"type":{"const":"user_transcript","default":"user_transcript","title":"Type","type":"string"},"transcript":{"title":"Transcript","type":"string"},"state":{"default":"","title":"State","type":"string"},"speaker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Id"},"speaker_role":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Speaker Role"},"stt_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Stt Confidence"},"eot_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Eot Confidence"},"is_barge_in":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Is Barge In"}},"required":["transcript"],"title":"UserTranscriptEvent","type":"object"},"VoiceContextAppliedEvent":{"properties":{"type":{"const":"voice_context_applied","default":"voice_context_applied","title":"Type","type":"string"},"tts_emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tts Emotion"},"tts_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Tts Speed"},"tts_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Tts Volume"},"filler_enabled":{"title":"Filler Enabled","type":"boolean"},"emotion_detection_enabled":{"title":"Emotion Detection Enabled","type":"boolean"},"reasoning":{"title":"Reasoning","type":"string"}},"required":["filler_enabled","emotion_detection_enabled","reasoning"],"title":"VoiceContextAppliedEvent","type":"object"}}}} ``` ## The TurnArtifactEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnArtifactEvent":{"properties":{"event":{"const":"artifact","default":"artifact","title":"Event","type":"string"},"type":{"maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type","type":"string"},"schema_version":{"maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version","type":"string"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Payload"}},"required":["type","schema_version","payload"],"title":"TurnArtifactEvent","type":"object"}}}} ``` ## The TurnDoneEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnDoneEvent":{"properties":{"event":{"const":"done","default":"done","title":"Event","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"status":{"title":"Status","type":"string"},"turn_count":{"title":"Turn Count","type":"integer"},"background_pending":{"default":false,"description":"True when the streamed response is only an acknowledgement and the final assistant answer must be collected with the durable background-delivery protocol.","title":"Background Pending","type":"boolean"},"delivery_protocol_version":{"anyOf":[{"const":2,"type":"integer"},{"type":"null"}],"default":null,"description":"Version of the durable background-delivery protocol supported by the serving agent. Clients may retry receipt-backed polls only after observing version 2.","title":"Delivery Protocol Version"},"turn_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"description":"Identifier of the user exchange this turn belongs to — identical to the ``turn_id`` on the non-streaming ``POST /turns`` response and on this conversation's history turns, so a streaming client can anchor durable per-turn artifacts (e.g. feedback) without a follow-up read. Stamped by platform-api at the proxy boundary (agent-engine frames do not carry it). Null when the conversation has no user exchange yet (a greeting kickoff stream on a fresh conversation).","title":"Turn Id"},"turn_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based ordinal of the user exchange (0 = first user turn). Derived server-side; null exactly when ``turn_id`` is null.","title":"Turn Index"}},"required":["conversation_id","status","turn_count"],"title":"TurnDoneEvent","type":"object"}}}} ``` ## The TurnErrorEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnErrorEvent":{"description":"Terminal error frame on the turn stream.\n\nCarries a stable ``code`` so SDK consumers can branch deterministically\nwithout parsing free-form ``message`` text. ``retryable`` tells the\nconsumer whether issuing the same turn again is likely to succeed.\n``status_code`` is the upstream HTTP status when the error originated\nfrom a downstream service (agent-engine), and is otherwise omitted.","properties":{"event":{"const":"error","default":"error","title":"Event","type":"string"},"message":{"title":"Message","type":"string"},"code":{"default":"unknown","enum":["upstream_error","stream_interrupted","client_error","unknown"],"title":"Code","type":"string"},"retryable":{"default":false,"title":"Retryable","type":"boolean"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Status Code"}},"required":["message"],"title":"TurnErrorEvent","type":"object"}}}} ``` ## The TurnMessageEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnMessageEvent":{"properties":{"event":{"const":"message","default":"message","title":"Event","type":"string"},"role":{"title":"Role","type":"string"},"text":{"title":"Text","type":"string"}},"required":["role","text"],"title":"TurnMessageEvent","type":"object"}}}} ``` ## The TurnThinkingEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnThinkingEvent":{"properties":{"event":{"const":"thinking","default":"thinking","title":"Event","type":"string"},"tier":{"title":"Tier","type":"integer"},"tier_name":{"title":"Tier Name","type":"string"}},"required":["tier","tier_name"],"title":"TurnThinkingEvent","type":"object"}}}} ``` ## The TurnTokenEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnTokenEvent":{"properties":{"event":{"const":"token","default":"token","title":"Event","type":"string"},"text":{"title":"Text","type":"string"}},"required":["text"],"title":"TurnTokenEvent","type":"object"}}}} ``` ## The TurnToolCallCompletedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnToolCallCompletedEvent":{"properties":{"event":{"const":"tool_call_completed","default":"tool_call_completed","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"result":{"title":"Result","type":"string"},"succeeded":{"title":"Succeeded","type":"boolean"},"duration_ms":{"anyOf":[{"maximum":3600000,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Null when the upstream did not report timing (legacy/test paths).","title":"Duration Ms"}},"required":["tool_name","call_id","result","succeeded"],"title":"TurnToolCallCompletedEvent","type":"object"}}}} ``` ## The TurnToolCallStartedEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnToolCallStartedEvent":{"properties":{"event":{"const":"tool_call_started","default":"tool_call_started","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"input":{"title":"Input","type":"string"}},"required":["tool_name","call_id","input"],"title":"TurnToolCallStartedEvent","type":"object"}}}} ``` ## The TurnStreamEvent object ```json {"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"components":{"schemas":{"TurnStreamEvent":{"discriminator":{"mapping":{"artifact":"#/components/schemas/TurnArtifactEvent","done":"#/components/schemas/TurnDoneEvent","error":"#/components/schemas/TurnErrorEvent","message":"#/components/schemas/TurnMessageEvent","thinking":"#/components/schemas/TurnThinkingEvent","token":"#/components/schemas/TurnTokenEvent","tool_call_completed":"#/components/schemas/TurnToolCallCompletedEvent","tool_call_started":"#/components/schemas/TurnToolCallStartedEvent"},"propertyName":"event"},"oneOf":[{"$ref":"#/components/schemas/TurnTokenEvent"},{"$ref":"#/components/schemas/TurnArtifactEvent"},{"$ref":"#/components/schemas/TurnToolCallStartedEvent"},{"$ref":"#/components/schemas/TurnToolCallCompletedEvent"},{"$ref":"#/components/schemas/TurnThinkingEvent"},{"$ref":"#/components/schemas/TurnMessageEvent"},{"$ref":"#/components/schemas/TurnDoneEvent"},{"$ref":"#/components/schemas/TurnErrorEvent"}]},"TurnTokenEvent":{"properties":{"event":{"const":"token","default":"token","title":"Event","type":"string"},"text":{"title":"Text","type":"string"}},"required":["text"],"title":"TurnTokenEvent","type":"object"},"TurnArtifactEvent":{"properties":{"event":{"const":"artifact","default":"artifact","title":"Event","type":"string"},"type":{"maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type","type":"string"},"schema_version":{"maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version","type":"string"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Payload"}},"required":["type","schema_version","payload"],"title":"TurnArtifactEvent","type":"object"},"TurnToolCallStartedEvent":{"properties":{"event":{"const":"tool_call_started","default":"tool_call_started","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"input":{"title":"Input","type":"string"}},"required":["tool_name","call_id","input"],"title":"TurnToolCallStartedEvent","type":"object"},"TurnToolCallCompletedEvent":{"properties":{"event":{"const":"tool_call_completed","default":"tool_call_completed","title":"Event","type":"string"},"tool_name":{"maxLength":256,"title":"Tool Name","type":"string"},"call_id":{"maxLength":256,"title":"Call Id","type":"string"},"result":{"title":"Result","type":"string"},"succeeded":{"title":"Succeeded","type":"boolean"},"duration_ms":{"anyOf":[{"maximum":3600000,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Wall-clock tool execution time in milliseconds, measured at the engage_step call site. Null when the upstream did not report timing (legacy/test paths).","title":"Duration Ms"}},"required":["tool_name","call_id","result","succeeded"],"title":"TurnToolCallCompletedEvent","type":"object"},"TurnThinkingEvent":{"properties":{"event":{"const":"thinking","default":"thinking","title":"Event","type":"string"},"tier":{"title":"Tier","type":"integer"},"tier_name":{"title":"Tier Name","type":"string"}},"required":["tier","tier_name"],"title":"TurnThinkingEvent","type":"object"},"TurnMessageEvent":{"properties":{"event":{"const":"message","default":"message","title":"Event","type":"string"},"role":{"title":"Role","type":"string"},"text":{"title":"Text","type":"string"}},"required":["role","text"],"title":"TurnMessageEvent","type":"object"},"TurnDoneEvent":{"properties":{"event":{"const":"done","default":"done","title":"Event","type":"string"},"conversation_id":{"format":"uuid","title":"Conversation Id","type":"string"},"status":{"title":"Status","type":"string"},"turn_count":{"title":"Turn Count","type":"integer"},"background_pending":{"default":false,"description":"True when the streamed response is only an acknowledgement and the final assistant answer must be collected with the durable background-delivery protocol.","title":"Background Pending","type":"boolean"},"delivery_protocol_version":{"anyOf":[{"const":2,"type":"integer"},{"type":"null"}],"default":null,"description":"Version of the durable background-delivery protocol supported by the serving agent. Clients may retry receipt-backed polls only after observing version 2.","title":"Delivery Protocol Version"},"turn_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"description":"Identifier of the user exchange this turn belongs to — identical to the ``turn_id`` on the non-streaming ``POST /turns`` response and on this conversation's history turns, so a streaming client can anchor durable per-turn artifacts (e.g. feedback) without a follow-up read. Stamped by platform-api at the proxy boundary (agent-engine frames do not carry it). Null when the conversation has no user exchange yet (a greeting kickoff stream on a fresh conversation).","title":"Turn Id"},"turn_index":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based ordinal of the user exchange (0 = first user turn). Derived server-side; null exactly when ``turn_id`` is null.","title":"Turn Index"}},"required":["conversation_id","status","turn_count"],"title":"TurnDoneEvent","type":"object"},"TurnErrorEvent":{"description":"Terminal error frame on the turn stream.\n\nCarries a stable ``code`` so SDK consumers can branch deterministically\nwithout parsing free-form ``message`` text. ``retryable`` tells the\nconsumer whether issuing the same turn again is likely to succeed.\n``status_code`` is the upstream HTTP status when the error originated\nfrom a downstream service (agent-engine), and is otherwise omitted.","properties":{"event":{"const":"error","default":"error","title":"Event","type":"string"},"message":{"title":"Message","type":"string"},"code":{"default":"unknown","enum":["upstream_error","stream_interrupted","client_error","unknown"],"title":"Code","type":"string"},"retryable":{"default":false,"title":"Retryable","type":"boolean"},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Status Code"}},"required":["message"],"title":"TurnErrorEvent","type":"object"}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.concurrence.com/api-reference/readme/platform/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.