# Get Chat Detail `GET /v1/chats/{chat_id}/detail` One chat with its health snapshot, cost lines, vars, what it ran and event trace. Authenticate with `Authorization: Bearer $TALQING_API_KEY`. Errors use the shared envelope: https://docs.talqing.com/api-reference/errors.md ## OpenAPI ```json { "openapi":"3.1.0", "servers":[ { "description":"Talqing API", "url":"https://api.talqing.com" } ], "paths":{ "/v1/chats/{chat_id}/detail":{ "get":{ "description":"One chat with its health snapshot, cost lines, vars, what it ran and event trace.", "operationId":"chats.detail", "parameters":[ { "in":"path", "name":"chat_id", "required":true, "schema":{ "format":"uuid", "title":"Chat Id", "type":"string" } } ], "responses":{ "200":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ChatDetailResponse" } } }, "description":"Successful Response" }, "401":{ "$ref":"#/components/responses/Unauthorized" }, "404":{ "$ref":"#/components/responses/NotFound" }, "422":{ "$ref":"#/components/responses/ValidationFailed" }, "default":{ "$ref":"#/components/responses/Error" } }, "security":[ { "BearerAuth":[] }, { "SessionCookie":[] } ], "summary":"Get Chat Detail", "tags":[ "chats" ] } } }, "components":{ "responses":{ "Error":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" } } }, "description":"Unexpected error. Every error this API returns carries this body." }, "NotFound":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" } } }, "description":"No such resource in this organization." }, "Unauthorized":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" } } }, "description":"Missing credential, or one that is revoked or no longer a member of this organization." }, "ValidationFailed":{ "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" } } }, "description":"The request did not match this operation's schema; `detail.errors` lists each field." } }, "schemas":{ "AddMessageConfig":{ "additionalProperties":false, "properties":{ "scope":{ "default":"conversation", "enum":[ "conversation", "turn" ], "title":"Scope", "type":"string" }, "text":{ "title":"Text", "type":"string" } }, "required":[ "text" ], "title":"AddMessageConfig", "type":"object" }, "AddMessageOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/AddMessageConfig" }, "kind":{ "const":"add_message", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"AddMessageOperation", "type":"object" }, "AgentConfig":{ "additionalProperties":false, "description":"The whole agent: what it says, which models run it, and what it can do.\n\n``AgentBase`` plus the session this agent owns and the media stack that\nsession runs \u2014 which is what a task, running inside someone else's session,\nhas none of.\n\nA complete definition, not a patch \u2014 whatever it omits takes that field's\ndefault.", "properties":{ "analysis":{ "$ref":"#/components/schemas/AnalysisSpec" }, "avatar":{ "anyOf":[ { "$ref":"#/components/schemas/AvatarSpec" }, { "type":"null" } ] }, "background_audio":{ "$ref":"#/components/schemas/BackgroundAudioSpec" }, "channel":{ "default":"voice", "enum":[ "voice", "video", "text" ], "title":"Channel", "type":"string" }, "conversation":{ "$ref":"#/components/schemas/ConversationSpec" }, "elapsed_time":{ "default":false, "description":"Start every user message the model reads with the time since the session began, e.g. [12:34]. Not available on realtime models.", "title":"Elapsed Time", "type":"boolean" }, "faqs":{ "description":"FAQs the agent answers from: questions go in the prompt, answers are fetched on demand.", "items":{ "$ref":"#/components/schemas/FaqSelection" }, "maxItems":10, "title":"Faqs", "type":"array" }, "greeting":{ "anyOf":[ { "$ref":"#/components/schemas/GreetingSpec" }, { "type":"null" } ], "default":{ "message":"Hello! How can I help you today?" }, "description":"How the agent opens, on connect and on the way in from a handoff; null makes it wait for the caller to speak first. Voice and video only." }, "greeting_interruptible":{ "default":true, "description":"Whether the caller can cut the greeting off. A greeting speaking the recording notice never can. Cannot be false on a realtime model.", "title":"Greeting Interruptible", "type":"boolean" }, "handoffs":{ "description":"Where this agent may hand the conversation next. Each entry becomes one tool the model can call, so routing quality lives in its `description`. A target is a stored agent (`agent_id`) or a member of the team defined on the call.", "items":{ "$ref":"#/components/schemas/HandoffTarget" }, "title":"Handoffs", "type":"array" }, "inbound_webhook":{ "default":false, "description":"Before an inbound call or channel chat starts, ask the workspace's inbound webhook for its vars, secrets, overrides, metadata and userdata. Refused if it does not answer.", "title":"Inbound Webhook", "type":"boolean" }, "keypad_input":{ "$ref":"#/components/schemas/KeypadInputSpec" }, "language":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"The one language the caller and the agent speak, shared by every model in the pipeline. Use a code from the provider catalog's language lists; null means Auto. On a text agent, only with `stt` set.", "title":"Language" }, "llm":{ "anyOf":[ { "$ref":"#/components/schemas/LLMSpec" }, { "type":"null" } ] }, "max_duration_seconds":{ "anyOf":[ { "maximum":10800.0, "minimum":30.0, "type":"integer" }, { "type":"null" } ], "default":1800, "description":"The longest a call may last; the agent then says goodbye and hangs up. Null means the platform's 3-hour cap. Voice and video only; a handoff keeps the starting agent's limit.", "title":"Max Duration Seconds" }, "max_steps":{ "anyOf":[ { "maximum":50.0, "minimum":1.0, "type":"integer" }, { "type":"null" } ], "description":"How many LLM -> tools -> LLM rounds one turn may take before the agent must answer without tools. Null means 4 on voice and video, 25 on text. Not enforced on realtime models; a handoff keeps the starting agent's limit.", "title":"Max Steps" }, "mcps":{ "description":"MCP servers whose tools may be called \u2014 each named by the integration that holds its credential, or defined inline. Which of a named server's tools may be called is the integration's own `allowed_tools`, not this list.", "items":{ "$ref":"#/components/schemas/McpSelection" }, "title":"Mcps", "type":"array" }, "name":{ "description":"Unique in the workspace.", "minLength":1, "title":"Name", "type":"string" }, "noise_cancellation":{ "$ref":"#/components/schemas/NoiseCancellationSpec" }, "on_enter":{ "anyOf":[ { "$ref":"#/components/schemas/ToolSelection" }, { "type":"null" } ] }, "on_exit":{ "anyOf":[ { "$ref":"#/components/schemas/ToolSelection" }, { "type":"null" } ] }, "on_user_turn_completed":{ "anyOf":[ { "$ref":"#/components/schemas/ToolSelection" }, { "type":"null" } ] }, "prompt":{ "default":"You are a helpful, concise voice assistant.", "description":"The system prompt. `{{userdata.field}}` is substituted from the session's userdata when the agent starts, so one definition can address the person it reached.", "title":"Prompt", "type":"string" }, "realtime":{ "anyOf":[ { "$ref":"#/components/schemas/RealtimeSpec" }, { "type":"null" } ] }, "recording":{ "$ref":"#/components/schemas/RecordingSpec" }, "silence":{ "$ref":"#/components/schemas/SilenceSpec" }, "stt":{ "anyOf":[ { "$ref":"#/components/schemas/STTSpec" }, { "type":"null" } ], "description":"Text agents: transcribes voice notes; null = the agent can't listen to them." }, "tasks":{ "description":"Jobs this agent can enter and come back from. Each becomes one tool the model can call; the task runs inside this call, on its voice and its ears, and returns its typed output as the tool's result.", "items":{ "$ref":"#/components/schemas/TaskSelection" }, "title":"Tasks", "type":"array" }, "timezone":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"The IANA timezone this clock runs on, e.g. 'Asia/Kolkata'. Set it and the prompt and tools can read {{system_vars.now}}, {{system_vars.date}} and {{system_vars.time}}. Required only if one of those is used.", "title":"Timezone" }, "tools":{ "description":"Tools the model may call. Publishing pins each one to the tool version live at that moment, so republishing a tool does not change this until it is published again.", "items":{ "$ref":"#/components/schemas/ToolSelection" }, "title":"Tools", "type":"array" }, "tts":{ "anyOf":[ { "$ref":"#/components/schemas/TTSSpec" }, { "type":"null" } ] }, "turn_handling":{ "$ref":"#/components/schemas/TurnHandlingSpec" }, "vars":{ "description":"The variables read as {{vars.name}} in the prompt, the greeting and the tools. Values from the request that starts a session override the defaults. They are visible to the model - keep credentials in a workspace secret.", "items":{ "$ref":"#/components/schemas/VarDeclaration" }, "title":"Vars", "type":"array" }, "vision_input":{ "$ref":"#/components/schemas/VisionInputSpec" }, "voicemail_detection":{ "$ref":"#/components/schemas/VoicemailDetectionSpec" } }, "required":[ "name" ], "title":"AgentConfig", "type":"object" }, "AgentMetadata":{ "properties":{ "agent_id":{ "anyOf":[ { "format":"uuid", "type":"string" }, { "type":"null" } ], "title":"Agent Id" }, "channel":{ "title":"Channel", "type":"string" }, "name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Name" } }, "required":[ "channel" ], "title":"AgentMetadata", "type":"object" }, "AnalysisField":{ "additionalProperties":false, "description":"One value to pull out of the finished transcript.", "properties":{ "description":{ "description":"How to find this value in the transcript. Be explicit about the format you want and about what to do when the call never mentions it.", "minLength":1, "title":"Description", "type":"string" }, "name":{ "description":"Identifier for the extracted value, as it appears in the API and webhook. Lower-case letters, digits and underscores.", "pattern":"^[a-z][a-z0-9_]{0,39}$", "title":"Name", "type":"string" }, "type":{ "default":"string", "description":"The shape of the value. Anything that is not a number or a yes/no is a string.", "enum":[ "string", "boolean", "integer", "number" ], "title":"Type", "type":"string" } }, "required":[ "name", "description" ], "title":"AnalysisField", "type":"object" }, "AnalysisResponse":{ "description":"The analysis of one call, as every reader sees it.\n\nShared verbatim by the calls API and the `session.completed` webhook so an\nintegration that reads one can read the other.", "properties":{ "fields":{ "additionalProperties":true, "title":"Fields", "type":"object" }, "outcome":{ "anyOf":[ { "enum":[ "success", "failure", "unknown" ], "type":"string" }, { "type":"null" } ], "title":"Outcome" }, "outcome_rationale":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Outcome Rationale" }, "skip_reason":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Skip Reason" }, "status":{ "default":"none", "enum":[ "none", "pending", "completed", "failed", "skipped" ], "title":"Status", "type":"string" }, "summary":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Summary" } }, "required":[ "status", "skip_reason", "summary", "outcome", "outcome_rationale", "fields" ], "title":"AnalysisResponse", "type":"object" }, "AnalysisSpec":{ "additionalProperties":false, "description":"What to work out about a call or a chat once it has ended.\n\nOne LLM call per session reads the finished transcript.", "properties":{ "enabled":{ "default":true, "description":"Analyse calls after they end. This runs one extra LLM call per call, billed like any other, and adds roughly 5% to the cost of a call.", "title":"Enabled", "type":"boolean" }, "fields":{ "description":"Values to extract from the transcript. These are what a reader inferred afterwards, and are kept apart from the data the agent itself collected during the call.", "items":{ "$ref":"#/components/schemas/AnalysisField" }, "maxItems":25, "title":"Fields", "type":"array" }, "model":{ "anyOf":[ { "$ref":"#/components/schemas/LLMModelSpec" }, { "type":"null" } ], "description":"The model that reads the transcript. Leave unset to use the platform default, which is picked for accuracy rather than the low latency a live call needs." }, "outcome":{ "anyOf":[ { "$ref":"#/components/schemas/OutcomeSpec" }, { "type":"null" } ], "description":"Judge whether each call achieved its purpose. Unset means calls are not judged and the outcome is left empty." }, "summary":{ "default":true, "description":"Write a short summary of each call, shown on the calls list.", "title":"Summary", "type":"boolean" } }, "title":"AnalysisSpec", "type":"object" }, "AvatarPriceLine":{ "properties":{ "cost":{ "title":"Cost", "type":"number" }, "kind":{ "const":"avatar", "default":"avatar", "title":"Kind", "type":"string" }, "model":{ "title":"Model", "type":"string" }, "provider":{ "title":"Provider", "type":"string" }, "rates":{ "anyOf":[ { "$ref":"#/components/schemas/AvatarPricing" }, { "type":"null" } ] }, "seconds":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Seconds" } }, "required":[ "provider", "model", "cost", "rates", "kind", "seconds" ], "title":"AvatarPriceLine", "type":"object" }, "AvatarPricing":{ "properties":{ "per_minute":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Per Minute" } }, "title":"AvatarPricing", "type":"object" }, "AvatarSpec":{ "additionalProperties":false, "description":"The Anam video layer, active when `channel == \"video\"`.\n\n`avatar_id` is a face from GET /catalog/avatars.", "properties":{ "avatar_id":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "default":"edf6fdcb-acab-44b8-b974-ded72665ee26", "title":"Avatar Id" }, "model":{ "default":"anam", "title":"Model", "type":"string" }, "name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "default":"Mia", "title":"Name" }, "provider":{ "default":"anam", "title":"Provider", "type":"string" } }, "title":"AvatarSpec", "type":"object" }, "BackgroundAudioSpec":{ "additionalProperties":false, "description":"Ambient + thinking sounds mixed into the agent's output (voice realism).", "properties":{ "ambient":{ "anyOf":[ { "enum":[ "office", "city", "forest", "crowd", "hold_music" ], "type":"string" }, { "type":"null" } ], "default":"office", "title":"Ambient" }, "ambient_volume":{ "default":0.4, "title":"Ambient Volume", "type":"number" }, "enabled":{ "default":false, "title":"Enabled", "type":"boolean" }, "thinking":{ "anyOf":[ { "enum":[ "keyboard", "keyboard2" ], "type":"string" }, { "type":"null" } ], "default":"keyboard", "title":"Thinking" }, "thinking_volume":{ "default":0.6, "title":"Thinking Volume", "type":"number" } }, "title":"BackgroundAudioSpec", "type":"object" }, "BuiltinToolSpec":{ "additionalProperties":false, "description":"A capability of the model itself, switched on for that model.\n\n`config` takes only the options that model's catalog entry declares.", "properties":{ "config":{ "additionalProperties":true, "title":"Config", "type":"object" }, "type":{ "title":"Type", "type":"string" } }, "required":[ "type" ], "title":"BuiltinToolSpec", "type":"object" }, "ChatDetailResponse":{ "description":"One chat with what explains it: health, priced lines, what it ran, and trace.", "properties":{ "agent_config":{ "anyOf":[ { "$ref":"#/components/schemas/AgentConfig" }, { "type":"null" } ] }, "agent_plan":{ "anyOf":[ { "$ref":"#/components/schemas/StoredAgentPlan" }, { "type":"null" } ] }, "agent_version":{ "anyOf":[ { "type":"integer" }, { "const":"draft", "type":"string" }, { "type":"null" } ], "title":"Agent Version" }, "billed_at":{ "anyOf":[ { "format":"date-time", "type":"string" }, { "type":"null" } ], "title":"Billed At" }, "billing_status":{ "title":"Billing Status", "type":"string" }, "chat":{ "$ref":"#/components/schemas/ChatResponse" }, "contact_userdata":{ "additionalProperties":true, "title":"Contact Userdata", "type":"object" }, "cost":{ "anyOf":[ { "$ref":"#/components/schemas/CostDetailResponse" }, { "type":"null" } ] }, "events":{ "items":{ "$ref":"#/components/schemas/SessionEventResponse" }, "title":"Events", "type":"array" }, "snapshot":{ "$ref":"#/components/schemas/HealthSnapshotResponse" }, "starting_prompt":{ "default":"", "title":"Starting Prompt", "type":"string" }, "team":{ "items":{ "$ref":"#/components/schemas/TeamMemberResponse" }, "title":"Team", "type":"array" }, "tools":{ "items":{ "$ref":"#/components/schemas/SessionToolResponse" }, "title":"Tools", "type":"array" }, "vars":{ "additionalProperties":{ "type":"string" }, "title":"Vars", "type":"object" } }, "required":[ "chat", "snapshot", "cost", "vars", "events", "agent_version", "agent_config", "agent_plan", "team", "tools", "starting_prompt", "contact_userdata", "billing_status", "billed_at" ], "title":"ChatDetailResponse", "type":"object" }, "ChatResponse":{ "description":"One chat: a text session from its first message to its end.", "properties":{ "agent":{ "$ref":"#/components/schemas/AgentMetadata" }, "analysis":{ "anyOf":[ { "$ref":"#/components/schemas/AnalysisResponse" }, { "type":"null" } ] }, "close_reason":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Close Reason" }, "contact_key":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Contact Key" }, "conversation_id":{ "anyOf":[ { "format":"uuid", "type":"string" }, { "type":"null" } ], "title":"Conversation Id" }, "cost":{ "anyOf":[ { "$ref":"#/components/schemas/CostResponse" }, { "type":"null" } ] }, "created_at":{ "format":"date-time", "title":"Created At", "type":"string" }, "ended_at":{ "anyOf":[ { "format":"date-time", "type":"string" }, { "type":"null" } ], "title":"Ended At" }, "id":{ "format":"uuid", "title":"Id", "type":"string" }, "metadata":{ "additionalProperties":{ "type":"string" }, "description":"Your own labels for this session, set by your inbound webhook.", "title":"Metadata", "type":"object" }, "started_at":{ "anyOf":[ { "format":"date-time", "type":"string" }, { "type":"null" } ], "title":"Started At" }, "status":{ "enum":[ "open", "ended" ], "title":"Status", "type":"string" }, "userdata":{ "additionalProperties":true, "title":"Userdata", "type":"object" } }, "required":[ "id", "conversation_id", "contact_key", "agent", "status", "close_reason", "created_at", "started_at", "ended_at", "cost", "analysis", "userdata", "metadata" ], "title":"ChatResponse", "type":"object" }, "CodeConfig":{ "additionalProperties":false, "description":"TypeScript run on the code-exec service.", "properties":{ "compiled_js":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"Server-written build output. Do not send it; publishing compiles `source_ts`.", "title":"Compiled Js" }, "source_ts":{ "description":"Must `export default async function handler(input)` and return an object.", "title":"Source Ts", "type":"string" }, "timeout":{ "anyOf":[ { "exclusiveMinimum":0.0, "maximum":30.0, "type":"number" }, { "type":"null" } ], "description":"Seconds, not milliseconds. Defaults to 10.", "title":"Timeout" } }, "required":[ "source_ts" ], "title":"CodeConfig", "type":"object" }, "CodeOperation":{ "additionalProperties":false, "description":"Run TypeScript to transform or shape data an `http` operation cannot.\n\nIts sandbox has `fetch`, but reaching an API with it instead of an `http`\noperation costs a V8 isolate per call and hides the request from the editor.", "properties":{ "background_execution":{ "default":false, "title":"Background Execution", "type":"boolean" }, "config":{ "$ref":"#/components/schemas/CodeConfig" }, "kind":{ "const":"code", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" }, "publish_fields":{ "items":{ "$ref":"#/components/schemas/PublishFieldRequest" }, "title":"Publish Fields", "type":"array" }, "silent":{ "default":false, "title":"Silent", "type":"boolean" } }, "required":[ "kind", "config" ], "title":"CodeOperation", "type":"object" }, "ConnectionQuality":{ "description":"The worst reading on each side of the call, kept apart on purpose.\n\nA collapsed \"the connection was poor\" reads as a platform fault even when\nthe poor leg was the caller's own network, which is the difference between\na support ticket and a shrug. `overall` stays for readers that only want one\nword; `agent` and `caller` are `unknown` on calls whose trace predates the\n`side` field.", "properties":{ "agent":{ "default":"unknown", "title":"Agent", "type":"string" }, "caller":{ "default":"unknown", "title":"Caller", "type":"string" }, "overall":{ "default":"unknown", "title":"Overall", "type":"string" } }, "required":[ "overall", "agent", "caller" ], "title":"ConnectionQuality", "type":"object" }, "ConversationSpec":{ "additionalProperties":false, "description":"What a new call knows about earlier ones with the same person.", "properties":{ "context":{ "default":"none", "description":"What a new session starts with from earlier ones with this person: 'none' starts clean, 'summary' adds background on recent conversations, 'transcript' carries the same conversation on. Read only from the agent that answers. A WhatsApp call always carries the chat on, whatever this says.", "enum":[ "none", "summary", "transcript" ], "title":"Context", "type":"string" }, "initialize_userdata":{ "default":true, "description":"Start the call already knowing what the agent learned about this person on earlier ones. Used by 'summary' and 'transcript' only; a 'none' call always starts empty.", "title":"Initialize Userdata", "type":"boolean" }, "summary_limit":{ "anyOf":[ { "minimum":1.0, "type":"integer" }, { "type":"null" } ], "description":"How many recent calls to summarize. Leave empty for all of them. Used by 'summary' only.", "title":"Summary Limit" } }, "title":"ConversationSpec", "type":"object" }, "CostDetailResponse":{ "description":"The three totals, plus the priced lines they were summed from.\n\n``pricing_snapshot`` is the exact ``PriceBreakdown`` the biller wrote at\nseal, rates and all \u2014 declared as one rather than as a bag so every reader\ngets the real shape instead of re-deriving it. Only the ``computed`` branch\nof the biller writes a breakdown here, and this whole model is ``None``\nunless ``billing_status = 'computed'``, so the ``{\"error\": \u2026}`` shape the\nunpriceable path writes to the same column is unreachable from here.", "properties":{ "duration_s":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Duration S" }, "platform_fee":{ "title":"Platform Fee", "type":"number" }, "pricing_snapshot":{ "anyOf":[ { "$ref":"#/components/schemas/PriceBreakdown" }, { "type":"null" } ] }, "provider_cost":{ "title":"Provider Cost", "type":"number" }, "total_charge":{ "title":"Total Charge", "type":"number" } }, "required":[ "provider_cost", "platform_fee", "total_charge", "duration_s", "pricing_snapshot" ], "title":"CostDetailResponse", "type":"object" }, "CostResponse":{ "properties":{ "duration_s":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Duration S" }, "platform_fee":{ "title":"Platform Fee", "type":"number" }, "provider_cost":{ "title":"Provider Cost", "type":"number" }, "total_charge":{ "title":"Total Charge", "type":"number" } }, "required":[ "provider_cost", "platform_fee", "total_charge" ], "title":"CostResponse", "type":"object" }, "EndCallConfig":{ "additionalProperties":false, "description":"No settings: an `end_call` ends the call.", "properties":{}, "title":"EndCallConfig", "type":"object" }, "EndCallOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/EndCallConfig" }, "kind":{ "const":"end_call", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind" ], "title":"EndCallOperation", "type":"object" }, "EndpointingSpec":{ "additionalProperties":false, "description":"How long a caller's silence must last before the agent takes the turn.", "properties":{ "max_silence_duration":{ "default":2.5, "description":"How long to wait instead when the turn detector judges the caller is mid-thought. Only a batch speech-to-text model in one of the turn detector's 14 languages gets that judgement; every other pipeline ends turns on silence and ignores this.", "minimum":0.0, "title":"Max Silence Duration", "type":"number" }, "min_silence_duration":{ "default":0.5, "description":"How long the caller must stay silent, in seconds, before the agent takes the turn. A streaming speech-to-text model may wait longer when it hears the caller is not finished.", "minimum":0.25, "title":"Min Silence Duration", "type":"number" } }, "title":"EndpointingSpec", "type":"object" }, "ErrorBody":{ "description":"The structured half of our error contract: a human `message` plus a list\nof individual `errors` (used wherever we surface many problems at once,\nincluding tool publish, op-tree checks, and request validation). The global\nexception handlers normalize every API error to\n`{detail: {message, errors, code}}`, so SDKs can parse one shape consistently.", "properties":{ "code":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "default":null, "description":"A stable identifier for this error, when it has one.", "title":"Code" }, "errors":{ "items":{ "type":"string" }, "title":"Errors", "type":"array" }, "message":{ "title":"Message", "type":"string" } }, "required":[ "message", "errors" ], "title":"ErrorBody", "type":"object" }, "ErrorResponse":{ "description":"The body of every error response, at every status code.", "properties":{ "detail":{ "$ref":"#/components/schemas/ErrorBody" } }, "required":[ "detail" ], "title":"ErrorResponse", "type":"object" }, "FaqEntryInput":{ "additionalProperties":false, "properties":{ "answer":{ "maxLength":2000, "minLength":1, "title":"Answer", "type":"string" }, "question":{ "maxLength":300, "minLength":1, "title":"Question", "type":"string" } }, "required":[ "question", "answer" ], "title":"FaqEntryInput", "type":"object" }, "FaqSelection":{ "additionalProperties":false, "description":"An FAQ the agent answers from: name one with `faq_id`, or define one inline.", "properties":{ "faq":{ "anyOf":[ { "$ref":"#/components/schemas/InlineFaq" }, { "type":"null" } ] }, "faq_id":{ "anyOf":[ { "format":"uuid", "type":"string" }, { "type":"null" } ], "title":"Faq Id" } }, "title":"FaqSelection", "type":"object" }, "FrontendRpcConfig":{ "additionalProperties":false, "properties":{ "method":{ "pattern":"^[A-Za-z_][A-Za-z0-9_.-]*$", "title":"Method", "type":"string" }, "payload":{ "title":"Payload" }, "timeout":{ "anyOf":[ { "exclusiveMinimum":0.0, "maximum":60.0, "type":"number" }, { "type":"null" } ], "description":"Seconds, not milliseconds. Defaults to 5.", "title":"Timeout" } }, "required":[ "method" ], "title":"FrontendRpcConfig", "type":"object" }, "FrontendRpcOperation":{ "additionalProperties":false, "properties":{ "background_execution":{ "default":false, "title":"Background Execution", "type":"boolean" }, "config":{ "$ref":"#/components/schemas/FrontendRpcConfig" }, "kind":{ "const":"frontend_rpc", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" }, "publish_fields":{ "items":{ "$ref":"#/components/schemas/PublishFieldRequest" }, "title":"Publish Fields", "type":"array" }, "silent":{ "default":false, "title":"Silent", "type":"boolean" } }, "required":[ "kind", "config" ], "title":"FrontendRpcOperation", "type":"object" }, "GenerateReplyConfig":{ "additionalProperties":false, "properties":{ "instructions":{ "title":"Instructions", "type":"string" }, "wait_for_playback":{ "default":false, "title":"Wait For Playback", "type":"boolean" } }, "required":[ "instructions" ], "title":"GenerateReplyConfig", "type":"object" }, "GenerateReplyOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/GenerateReplyConfig" }, "kind":{ "const":"generate_reply", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"GenerateReplyOperation", "type":"object" }, "GreetingSpec":{ "additionalProperties":false, "description":"How the agent opens: a fixed `message`, or `instructions` for the model to write one.", "properties":{ "instructions":{ "anyOf":[ { "minLength":1, "type":"string" }, { "type":"null" } ], "description":"What the model is told to open with; it writes the line. Supports the prompt's substitutions. Adds a model reply's latency before the first word.", "title":"Instructions" }, "message":{ "anyOf":[ { "minLength":1, "type":"string" }, { "type":"null" } ], "description":"Spoken word for word. Supports the prompt's substitutions, plus `{{recording.notice}}`, the recording notice's place in the line.", "title":"Message" } }, "title":"GreetingSpec", "type":"object" }, "HandoffConfig":{ "additionalProperties":false, "properties":{ "agent_name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"A member of the team this call runs, by name.", "title":"Agent Name" }, "context":{ "default":"transcript", "enum":[ "none", "summary", "transcript" ], "title":"Context", "type":"string" }, "instructions":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"What the target is told as it opens, when it has no greeting.", "title":"Instructions" }, "message":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"Spoken while connecting, before the target takes over.", "title":"Message" }, "recent_turns":{ "anyOf":[ { "maximum":10.0, "minimum":1.0, "type":"integer" }, { "type":"null" } ], "description":"Context 'summary' only: turns of this call that cross verbatim beside the summary. Defaults to 2.", "title":"Recent Turns" }, "summary":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"Required under context 'summary'. A template, not a request for one.", "title":"Summary" }, "target_agent_id":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"A published agent in this workspace.", "title":"Target Agent Id" } }, "title":"HandoffConfig", "type":"object" }, "HandoffOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/HandoffConfig" }, "kind":{ "const":"handoff", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"HandoffOperation", "type":"object" }, "HandoffTarget":{ "additionalProperties":false, "description":"One destination this agent may hand the conversation to.\n\nEach becomes a `handoff_to_` tool, so `description` is what the model\nroutes on.", "properties":{ "agent_id":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Agent Id" }, "context":{ "default":"transcript", "enum":[ "none", "summary", "transcript" ], "title":"Context", "type":"string" }, "description":{ "minLength":1, "title":"Description", "type":"string" }, "instructions":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Instructions" }, "message":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Message" }, "name":{ "minLength":1, "title":"Name", "type":"string" }, "recent_turns":{ "anyOf":[ { "maximum":10.0, "minimum":1.0, "type":"integer" }, { "type":"null" } ], "title":"Recent Turns" }, "summary_prompt":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Summary Prompt" } }, "required":[ "name", "description" ], "title":"HandoffTarget", "type":"object" }, "HealthIssue":{ "description":"One problem found, and what kind it is.", "properties":{ "kind":{ "enum":[ "failed", "never_ready", "provider_errors", "provider_failover", "tool_failures", "tools_unfinished", "slow_tools", "slow_responses", "slow_after_filler", "connection", "noise_cancellation", "unpriceable" ], "title":"Kind", "type":"string" }, "message":{ "title":"Message", "type":"string" } }, "required":[ "kind", "message" ], "title":"HealthIssue", "type":"object" }, "HealthSnapshotResponse":{ "description":"The band at the top of the call and conversation views.", "properties":{ "agent_became_ready":{ "default":false, "title":"Agent Became Ready", "type":"boolean" }, "agent_messages":{ "default":0, "title":"Agent Messages", "type":"integer" }, "billing_status":{ "default":"pending", "title":"Billing Status", "type":"string" }, "cached_input_tokens":{ "default":0, "title":"Cached Input Tokens", "type":"integer" }, "connection":{ "$ref":"#/components/schemas/ConnectionQuality", "default":{ "agent":"unknown", "caller":"unknown", "overall":"unknown" } }, "connection_quality":{ "default":"unknown", "title":"Connection Quality", "type":"string" }, "duration_seconds":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Duration Seconds" }, "errors":{ "default":0, "title":"Errors", "type":"integer" }, "false_interruptions":{ "default":0, "title":"False Interruptions", "type":"integer" }, "false_interruptions_resumed":{ "default":0, "title":"False Interruptions Resumed", "type":"integer" }, "input_tokens":{ "default":0, "title":"Input Tokens", "type":"integer" }, "interruptions":{ "default":0, "title":"Interruptions", "type":"integer" }, "issues":{ "default":[], "items":{ "$ref":"#/components/schemas/HealthIssue" }, "title":"Issues", "type":"array" }, "noise_cancellation_failed":{ "default":false, "title":"Noise Cancellation Failed", "type":"boolean" }, "ok":{ "default":true, "title":"Ok", "type":"boolean" }, "output_tokens":{ "default":0, "title":"Output Tokens", "type":"integer" }, "pace":{ "$ref":"#/components/schemas/PaceStats", "default":{ "talk_over_turns":0 } }, "provider_failures":{ "default":0, "title":"Provider Failures", "type":"integer" }, "provider_recoveries":{ "default":0, "title":"Provider Recoveries", "type":"integer" }, "providers":{ "default":[], "items":{ "type":"string" }, "title":"Providers", "type":"array" }, "response_latency":{ "$ref":"#/components/schemas/LatencyStats", "default":{ "samples":0 } }, "response_stages":{ "default":[], "items":{ "$ref":"#/components/schemas/LatencyStage" }, "title":"Response Stages", "type":"array" }, "slow_replies_after_filler":{ "default":0, "title":"Slow Replies After Filler", "type":"integer" }, "slow_response_threshold_ms":{ "default":3500.0, "title":"Slow Response Threshold Ms", "type":"number" }, "slow_tool_calls":{ "default":0, "title":"Slow Tool Calls", "type":"integer" }, "slow_tool_calls_in_silence":{ "default":0, "title":"Slow Tool Calls In Silence", "type":"integer" }, "slow_tool_threshold_ms":{ "default":8000.0, "title":"Slow Tool Threshold Ms", "type":"number" }, "stt_audio_ms":{ "default":0, "title":"Stt Audio Ms", "type":"integer" }, "tool_call_failures":{ "default":0, "title":"Tool Call Failures", "type":"integer" }, "tool_calls":{ "default":0, "title":"Tool Calls", "type":"integer" }, "total_audio_ms":{ "default":0, "title":"Total Audio Ms", "type":"integer" }, "total_cost_usd":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Total Cost Usd" }, "tts_audio_ms":{ "default":0, "title":"Tts Audio Ms", "type":"integer" }, "tts_characters":{ "default":0, "title":"Tts Characters", "type":"integer" }, "turns":{ "default":0, "title":"Turns", "type":"integer" }, "unfinished_tool_calls":{ "default":0, "title":"Unfinished Tool Calls", "type":"integer" }, "uninterrupted_responses":{ "default":0, "title":"Uninterrupted Responses", "type":"integer" }, "user_messages":{ "default":0, "title":"User Messages", "type":"integer" } }, "required":[ "duration_seconds", "slow_response_threshold_ms", "slow_tool_threshold_ms", "turns", "user_messages", "agent_messages", "interruptions", "uninterrupted_responses", "pace", "response_latency", "response_stages", "total_cost_usd", "billing_status", "input_tokens", "cached_input_tokens", "output_tokens", "stt_audio_ms", "tts_audio_ms", "total_audio_ms", "tts_characters", "providers", "tool_calls", "tool_call_failures", "unfinished_tool_calls", "slow_tool_calls", "slow_tool_calls_in_silence", "slow_replies_after_filler", "errors", "provider_failures", "provider_recoveries", "agent_became_ready", "connection_quality", "connection", "false_interruptions", "false_interruptions_resumed", "noise_cancellation_failed", "ok", "issues" ], "title":"HealthSnapshotResponse", "type":"object" }, "HttpConfig":{ "additionalProperties":false, "properties":{ "body":{ "title":"Body" }, "headers":{ "additionalProperties":{ "type":"string" }, "title":"Headers", "type":"object" }, "method":{ "enum":[ "GET", "POST", "PUT", "PATCH", "DELETE" ], "title":"Method", "type":"string" }, "query":{ "additionalProperties":{ "type":"string" }, "title":"Query", "type":"object" }, "timeout":{ "anyOf":[ { "exclusiveMinimum":0.0, "maximum":120.0, "type":"number" }, { "type":"null" } ], "description":"Seconds, not milliseconds. Defaults to 20.", "title":"Timeout" }, "url":{ "title":"Url", "type":"string" } }, "required":[ "method", "url" ], "title":"HttpConfig", "type":"object" }, "HttpOperation":{ "additionalProperties":false, "description":"Call a REST API. The right operation for any plain request/response call.", "properties":{ "background_execution":{ "default":false, "title":"Background Execution", "type":"boolean" }, "config":{ "$ref":"#/components/schemas/HttpConfig" }, "kind":{ "const":"http", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" }, "publish_fields":{ "items":{ "$ref":"#/components/schemas/PublishFieldRequest" }, "title":"Publish Fields", "type":"array" }, "silent":{ "default":false, "title":"Silent", "type":"boolean" } }, "required":[ "kind", "config" ], "title":"HttpOperation", "type":"object" }, "IfConfig":{ "additionalProperties":false, "properties":{ "left":{ "title":"Left" }, "op":{ "enum":[ "eq", "neq", "gt", "lt", "exists", "in" ], "title":"Op", "type":"string" }, "right":{ "title":"Right" } }, "required":[ "left", "op" ], "title":"IfConfig", "type":"object" }, "IfOperation":{ "additionalProperties":false, "description":"The one branching operation, and the only one with children.\n\nBranches do not rejoin: an `if` is terminal in its chain, so work needed on\nboth paths is written once per path.", "properties":{ "config":{ "$ref":"#/components/schemas/IfConfig" }, "else":{ "anyOf":[ { "items":{ "discriminator":{ "mapping":{ "add_message":"#/components/schemas/AddMessageOperation", "code":"#/components/schemas/CodeOperation", "end_call":"#/components/schemas/EndCallOperation", "frontend_rpc":"#/components/schemas/FrontendRpcOperation", "generate_reply":"#/components/schemas/GenerateReplyOperation", "handoff":"#/components/schemas/HandoffOperation", "http":"#/components/schemas/HttpOperation", "if":"#/components/schemas/IfOperation", "say":"#/components/schemas/SayOperation", "send_dtmf":"#/components/schemas/SendDtmfOperation", "set_variable":"#/components/schemas/SetVariableOperation", "transfer":"#/components/schemas/TransferOperation" }, "propertyName":"kind" }, "oneOf":[ { "$ref":"#/components/schemas/HttpOperation" }, { "$ref":"#/components/schemas/CodeOperation" }, { "$ref":"#/components/schemas/FrontendRpcOperation" }, { "$ref":"#/components/schemas/IfOperation" }, { "$ref":"#/components/schemas/SetVariableOperation" }, { "$ref":"#/components/schemas/SayOperation" }, { "$ref":"#/components/schemas/GenerateReplyOperation" }, { "$ref":"#/components/schemas/AddMessageOperation" }, { "$ref":"#/components/schemas/EndCallOperation" }, { "$ref":"#/components/schemas/HandoffOperation" }, { "$ref":"#/components/schemas/TransferOperation" }, { "$ref":"#/components/schemas/SendDtmfOperation" } ] }, "type":"array" }, { "type":"null" } ], "title":"Else" }, "kind":{ "const":"if", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" }, "then":{ "anyOf":[ { "items":{ "discriminator":{ "mapping":{ "add_message":"#/components/schemas/AddMessageOperation", "code":"#/components/schemas/CodeOperation", "end_call":"#/components/schemas/EndCallOperation", "frontend_rpc":"#/components/schemas/FrontendRpcOperation", "generate_reply":"#/components/schemas/GenerateReplyOperation", "handoff":"#/components/schemas/HandoffOperation", "http":"#/components/schemas/HttpOperation", "if":"#/components/schemas/IfOperation", "say":"#/components/schemas/SayOperation", "send_dtmf":"#/components/schemas/SendDtmfOperation", "set_variable":"#/components/schemas/SetVariableOperation", "transfer":"#/components/schemas/TransferOperation" }, "propertyName":"kind" }, "oneOf":[ { "$ref":"#/components/schemas/HttpOperation" }, { "$ref":"#/components/schemas/CodeOperation" }, { "$ref":"#/components/schemas/FrontendRpcOperation" }, { "$ref":"#/components/schemas/IfOperation" }, { "$ref":"#/components/schemas/SetVariableOperation" }, { "$ref":"#/components/schemas/SayOperation" }, { "$ref":"#/components/schemas/GenerateReplyOperation" }, { "$ref":"#/components/schemas/AddMessageOperation" }, { "$ref":"#/components/schemas/EndCallOperation" }, { "$ref":"#/components/schemas/HandoffOperation" }, { "$ref":"#/components/schemas/TransferOperation" }, { "$ref":"#/components/schemas/SendDtmfOperation" } ] }, "type":"array" }, { "type":"null" } ], "title":"Then" } }, "required":[ "kind", "config" ], "title":"IfOperation", "type":"object" }, "InlineFaq":{ "additionalProperties":false, "description":"An FAQ defined here rather than named.\n\nOn the call endpoints it is used for that call only; on the agent and task\nendpoints it is created as a real FAQ.", "properties":{ "entries":{ "items":{ "$ref":"#/components/schemas/FaqEntryInput" }, "maxItems":500, "minItems":1, "title":"Entries", "type":"array" }, "name":{ "maxLength":80, "minLength":1, "title":"Name", "type":"string" } }, "required":[ "name", "entries" ], "title":"InlineFaq", "type":"object" }, "InlineMcpServer":{ "additionalProperties":false, "description":"A remote MCP server defined here rather than named.\n\nAPI-key-shaped only \u2014 an OAuth server has to be an integration.\n`tools_namespace` prefixes every tool the model is shown: `crm` -> `crm_search`.", "properties":{ "allowed_tools":{ "anyOf":[ { "items":{ "type":"string" }, "type":"array" }, { "type":"null" } ], "title":"Allowed Tools" }, "headers":{ "additionalProperties":{ "type":"string" }, "title":"Headers", "type":"object" }, "name":{ "minLength":1, "title":"Name", "type":"string" }, "tools_namespace":{ "default":"", "pattern":"^$|^[a-z][a-z0-9_]{0,23}$", "title":"Tools Namespace", "type":"string" }, "url":{ "title":"Url", "type":"string" } }, "required":[ "name", "url" ], "title":"InlineMcpServer", "type":"object" }, "InlineTool":{ "additionalProperties":false, "description":"A tool defined here rather than named \u2014 the shape `create_tool` takes, with\nno id and no versions.\n\nOn the call endpoints it runs for that call only; on the agent endpoints it\nis created and published as a real tool.", "properties":{ "description":{ "default":"", "title":"Description", "type":"string" }, "disable_interruptions":{ "default":false, "title":"Disable Interruptions", "type":"boolean" }, "json_schema":{ "additionalProperties":true, "title":"Json Schema", "type":"object" }, "long_running_task":{ "default":false, "title":"Long Running Task", "type":"boolean" }, "name":{ "pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$", "title":"Name", "type":"string" }, "operations":{ "items":{ "discriminator":{ "mapping":{ "add_message":"#/components/schemas/AddMessageOperation", "code":"#/components/schemas/CodeOperation", "end_call":"#/components/schemas/EndCallOperation", "frontend_rpc":"#/components/schemas/FrontendRpcOperation", "generate_reply":"#/components/schemas/GenerateReplyOperation", "handoff":"#/components/schemas/HandoffOperation", "http":"#/components/schemas/HttpOperation", "if":"#/components/schemas/IfOperation", "say":"#/components/schemas/SayOperation", "send_dtmf":"#/components/schemas/SendDtmfOperation", "set_variable":"#/components/schemas/SetVariableOperation", "transfer":"#/components/schemas/TransferOperation" }, "propertyName":"kind" }, "oneOf":[ { "$ref":"#/components/schemas/HttpOperation" }, { "$ref":"#/components/schemas/CodeOperation" }, { "$ref":"#/components/schemas/FrontendRpcOperation" }, { "$ref":"#/components/schemas/IfOperation" }, { "$ref":"#/components/schemas/SetVariableOperation" }, { "$ref":"#/components/schemas/SayOperation" }, { "$ref":"#/components/schemas/GenerateReplyOperation" }, { "$ref":"#/components/schemas/AddMessageOperation" }, { "$ref":"#/components/schemas/EndCallOperation" }, { "$ref":"#/components/schemas/HandoffOperation" }, { "$ref":"#/components/schemas/TransferOperation" }, { "$ref":"#/components/schemas/SendDtmfOperation" } ] }, "title":"Operations", "type":"array" }, "silent":{ "default":false, "title":"Silent", "type":"boolean" } }, "required":[ "name" ], "title":"InlineTool", "type":"object" }, "InterruptionSpec":{ "additionalProperties":false, "description":"Whether the caller can cut the agent off mid-sentence, and how easily.", "properties":{ "discard_audio_if_uninterruptible":{ "default":true, "description":"Drop buffered audio while the agent speaks and cannot be interrupted.", "title":"Discard Audio If Uninterruptible", "type":"boolean" }, "enabled":{ "default":true, "description":"Whether interruptions are enabled.", "title":"Enabled", "type":"boolean" }, "false_interruption_timeout":{ "anyOf":[ { "minimum":0.0, "type":"number" }, { "type":"null" } ], "default":2.0, "description":"Seconds of silence after an interruption before it is classified as false. None disables false-interruption classification.", "title":"False Interruption Timeout" }, "min_speech_duration":{ "default":0.5, "description":"Minimum speech length in seconds to register as an interruption.", "minimum":0.0, "title":"Min Speech Duration", "type":"number" }, "min_words":{ "default":0, "description":"Minimum word count to consider an interruption. Applies to STT.", "minimum":0.0, "title":"Min Words", "type":"integer" }, "resume_false_interruption":{ "default":true, "description":"Resume the agent's speech after a false interruption.", "title":"Resume False Interruption", "type":"boolean" } }, "title":"InterruptionSpec", "type":"object" }, "KeypadInputSpec":{ "additionalProperties":false, "description":"Digits the caller types, delivered as a turn the agent can answer.\n\nPhone and stream calls only, and only where the platform sends DTMF as an\nevent \u2014 tones inside the audio are not detected. `voice` agents only:\nenabling it on `video` or `text` is refused.", "properties":{ "enabled":{ "default":false, "description":"Let the caller answer with the keypad. Each entry arrives as one labelled user turn, and the first keypress interrupts whatever the agent is saying.", "title":"Enabled", "type":"boolean" }, "terminator":{ "default":"#", "description":"The key that ends an entry. It is not part of the entry, and pressing it on nothing is ignored. Empty means only the quiet timer ends one.", "enum":[ "#", "*", "" ], "title":"Terminator", "type":"string" }, "timeout":{ "default":2.0, "description":"Seconds of quiet before an entry is taken as finished. 0 waits for the terminator however long it takes.", "maximum":10.0, "minimum":0.0, "title":"Timeout", "type":"number" } }, "title":"KeypadInputSpec", "type":"object" }, "LLMModelSpec":{ "additionalProperties":false, "properties":{ "builtin_tools":{ "items":{ "$ref":"#/components/schemas/BuiltinToolSpec" }, "title":"Builtin Tools", "type":"array" }, "hosts":{ "anyOf":[ { "items":{ "type":"string" }, "type":"array" }, { "type":"null" } ], "description":"OpenRouter only: the hosts allowed to serve this model, from list_model_hosts; the fastest of them answers. Unset lets OpenRouter use any host.", "title":"Hosts" }, "model":{ "default":"gpt-5.6-luna", "title":"Model", "type":"string" }, "priority":{ "default":false, "description":"Run this model in its provider's priority (low-latency) lane, where its catalog entry declares one; on OpenRouter, any model (standard where no host sells one). Steadies the worst case rather than the average, and costs more per token.", "title":"Priority", "type":"boolean" }, "provider":{ "default":"openai", "title":"Provider", "type":"string" }, "reasoning_effort":{ "anyOf":[ { "enum":[ "none", "minimal", "low", "medium", "high" ], "type":"string" }, { "type":"null" } ], "description":"How long this model may think before it answers. Must be one of the values the model's catalog entry offers; unset means its fastest. On a voice call the caller hears every second of thinking as silence.", "title":"Reasoning Effort" } }, "title":"LLMModelSpec", "type":"object" }, "LLMPriceLine":{ "properties":{ "cost":{ "title":"Cost", "type":"number" }, "input_cache_write_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Input Cache Write Tokens" }, "input_cached_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Input Cached Tokens" }, "kind":{ "const":"llm", "default":"llm", "title":"Kind", "type":"string" }, "model":{ "title":"Model", "type":"string" }, "output_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Output Tokens" }, "priority":{ "default":false, "title":"Priority", "type":"boolean" }, "provider":{ "title":"Provider", "type":"string" }, "provider_reported":{ "default":false, "title":"Provider Reported", "type":"boolean" }, "purpose":{ "default":"conversation", "title":"Purpose", "type":"string" }, "rates":{ "anyOf":[ { "$ref":"#/components/schemas/LLMPricing" }, { "type":"null" } ] }, "uncached_input_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Uncached Input Tokens" } }, "required":[ "provider", "model", "cost", "rates", "kind", "uncached_input_tokens", "input_cached_tokens", "input_cache_write_tokens", "output_tokens", "provider_reported", "purpose", "priority" ], "title":"LLMPriceLine", "type":"object" }, "LLMPricing":{ "properties":{ "cache_write_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Cache Write Per 1M" }, "cached_input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Cached Input Per 1M" }, "input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Input Per 1M" }, "output_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Output Per 1M" } }, "title":"LLMPricing", "type":"object" }, "LLMSpec":{ "additionalProperties":false, "properties":{ "builtin_tools":{ "items":{ "$ref":"#/components/schemas/BuiltinToolSpec" }, "title":"Builtin Tools", "type":"array" }, "fallback":{ "anyOf":[ { "$ref":"#/components/schemas/LLMModelSpec" }, { "type":"null" } ] }, "hosts":{ "anyOf":[ { "items":{ "type":"string" }, "type":"array" }, { "type":"null" } ], "description":"OpenRouter only: the hosts allowed to serve this model, from list_model_hosts; the fastest of them answers. Unset lets OpenRouter use any host.", "title":"Hosts" }, "model":{ "default":"gpt-5.6-luna", "title":"Model", "type":"string" }, "priority":{ "default":false, "description":"Run this model in its provider's priority (low-latency) lane, where its catalog entry declares one; on OpenRouter, any model (standard where no host sells one). Steadies the worst case rather than the average, and costs more per token.", "title":"Priority", "type":"boolean" }, "provider":{ "default":"openai", "title":"Provider", "type":"string" }, "reasoning_effort":{ "anyOf":[ { "enum":[ "none", "minimal", "low", "medium", "high" ], "type":"string" }, { "type":"null" } ], "description":"How long this model may think before it answers. Must be one of the values the model's catalog entry offers; unset means its fastest. On a voice call the caller hears every second of thinking as silence.", "title":"Reasoning Effort" } }, "title":"LLMSpec", "type":"object" }, "LatencyStage":{ "description":"One leg of a wait: what the time went on.", "properties":{ "kind":{ "enum":[ "stt", "endpoint", "hook", "llm_step", "tool", "llm", "first_sentence", "tts", "other" ], "title":"Kind", "type":"string" }, "label":{ "title":"Label", "type":"string" }, "ms":{ "title":"Ms", "type":"number" } }, "required":[ "kind", "ms", "label" ], "title":"LatencyStage", "type":"object" }, "LatencyStats":{ "properties":{ "avg_ms":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Avg Ms" }, "max_ms":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Max Ms" }, "p95_ms":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"P95 Ms" }, "samples":{ "default":0, "title":"Samples", "type":"integer" } }, "required":[ "avg_ms", "p95_ms", "max_ms", "samples" ], "title":"LatencyStats", "type":"object" }, "McpSelection":{ "additionalProperties":false, "description":"An MCP server this agent may call tools on: name an integration, or define\none inline.", "properties":{ "integration_id":{ "anyOf":[ { "format":"uuid", "type":"string" }, { "type":"null" } ], "title":"Integration Id" }, "mcp":{ "anyOf":[ { "$ref":"#/components/schemas/InlineMcpServer" }, { "type":"null" } ] } }, "title":"McpSelection", "type":"object" }, "NoiseCancellationSpec":{ "additionalProperties":false, "description":"Speech enhancement on the caller's inbound audio (voice and video).\n\nOff by default. `provider`/`model` name a `noise_cancellation` catalog entry.", "properties":{ "enabled":{ "default":false, "description":"Clean up the caller's audio before the agent hears it. Voice and video only.", "title":"Enabled", "type":"boolean" }, "enhancement_level":{ "default":0.8, "description":"How hard to suppress everything that is not the caller. 0.5 is conservative and always preserves the foreground speech, 0.8 gives the best word error rate on difficult audio, 1.0 suppresses interfering speech most aggressively.", "maximum":1.0, "minimum":0.0, "title":"Enhancement Level", "type":"number" }, "model":{ "default":"quail_vf_s", "title":"Model", "type":"string" }, "provider":{ "default":"aicoustics", "title":"Provider", "type":"string" } }, "title":"NoiseCancellationSpec", "type":"object" }, "OutcomeSpec":{ "additionalProperties":false, "description":"What counts as this call having achieved its purpose.", "properties":{ "prompt":{ "description":"What a successful call looks like for this agent. Each call is judged against this and comes back as success, failure, or unknown, with the reasoning.", "minLength":1, "title":"Prompt", "type":"string" } }, "required":[ "prompt" ], "title":"OutcomeSpec", "type":"object" }, "PaceStats":{ "description":"How the call *sounded*, as opposed to how fast the stack was.\n\nDerived from `started_speaking_at` / `stopped_speaking_at`, which LiveKit\nputs on every message and nothing has ever read. None of it is a platform\ndefect \u2014 a long reply is the prompt's doing and a long silence is often the\ncaller thinking \u2014 which is why it lands here as numbers rather than in\n`issues`.", "properties":{ "hold_ms":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Hold Ms" }, "longest_agent_turn_ms":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Longest Agent Turn Ms" }, "talk_over_turns":{ "default":0, "title":"Talk Over Turns", "type":"integer" } }, "required":[ "longest_agent_turn_ms", "talk_over_turns", "hold_ms" ], "title":"PaceStats", "type":"object" }, "PreemptiveGenerationSpec":{ "additionalProperties":false, "description":"Start drafting a reply before the caller has certainly finished, to cut\nthe pause before the agent speaks.", "properties":{ "enabled":{ "default":true, "description":"Whether preemptive generation is enabled.", "title":"Enabled", "type":"boolean" }, "max_retries":{ "default":3, "description":"Maximum number of preemptive generation attempts per user turn.", "minimum":0.0, "title":"Max Retries", "type":"integer" }, "max_speech_duration":{ "default":10.0, "description":"Maximum user speech duration in seconds for which preemptive generation is attempted.", "minimum":0.0, "title":"Max Speech Duration", "type":"number" }, "preemptive_tts":{ "default":false, "description":"Whether to also run TTS preemptively before the turn is confirmed.", "title":"Preemptive Tts", "type":"boolean" } }, "title":"PreemptiveGenerationSpec", "type":"object" }, "PriceBreakdown":{ "properties":{ "answered_messages":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Answered Messages" }, "avatar":{ "items":{ "$ref":"#/components/schemas/AvatarPriceLine" }, "title":"Avatar", "type":"array" }, "duration_s":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Duration S" }, "llm":{ "items":{ "$ref":"#/components/schemas/LLMPriceLine" }, "title":"Llm", "type":"array" }, "platform_fee":{ "title":"Platform Fee", "type":"number" }, "platform_fee_per_message":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Platform Fee Per Message" }, "platform_fee_per_minute":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Platform Fee Per Minute" }, "provider_cost":{ "title":"Provider Cost", "type":"number" }, "realtime":{ "items":{ "$ref":"#/components/schemas/RealtimePriceLine" }, "title":"Realtime", "type":"array" }, "stt":{ "items":{ "$ref":"#/components/schemas/STTPriceLine" }, "title":"Stt", "type":"array" }, "total_charge":{ "title":"Total Charge", "type":"number" }, "tts":{ "items":{ "$ref":"#/components/schemas/TTSPriceLine" }, "title":"Tts", "type":"array" } }, "required":[ "provider_cost", "platform_fee", "total_charge", "duration_s", "platform_fee_per_minute", "platform_fee_per_message", "answered_messages", "llm", "stt", "tts", "realtime", "avatar" ], "title":"PriceBreakdown", "type":"object" }, "PublishFieldRequest":{ "additionalProperties":false, "properties":{ "key":{ "anyOf":[ { "pattern":"^[A-Za-z_][A-Za-z0-9_]*$", "type":"string" }, { "type":"null" } ], "title":"Key" }, "path":{ "minLength":1, "title":"Path", "type":"string" }, "store":{ "enum":[ "tooldata", "userdata" ], "title":"Store", "type":"string" } }, "required":[ "path", "store" ], "title":"PublishFieldRequest", "type":"object" }, "RealtimePriceLine":{ "properties":{ "cost":{ "title":"Cost", "type":"number" }, "input_cached_audio_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Input Cached Audio Tokens" }, "input_cached_text_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Input Cached Text Tokens" }, "kind":{ "const":"realtime", "default":"realtime", "title":"Kind", "type":"string" }, "model":{ "title":"Model", "type":"string" }, "output_audio_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Output Audio Tokens" }, "output_text_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Output Text Tokens" }, "provider":{ "title":"Provider", "type":"string" }, "rates":{ "anyOf":[ { "$ref":"#/components/schemas/RealtimePricing" }, { "type":"null" } ] }, "session_seconds":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Session Seconds" }, "uncached_input_audio_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Uncached Input Audio Tokens" }, "uncached_input_text_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Uncached Input Text Tokens" } }, "required":[ "provider", "model", "cost", "rates", "kind", "uncached_input_text_tokens", "input_cached_text_tokens", "uncached_input_audio_tokens", "input_cached_audio_tokens", "output_text_tokens", "output_audio_tokens", "session_seconds" ], "title":"RealtimePriceLine", "type":"object" }, "RealtimePricing":{ "description":"Speech-to-speech rates. Two billing shapes exist and an entry uses one.\n\nOpenAI and Gemini price every modality separately per 1M tokens \u2014 audio\ninput costs ~10x text input, so the modality split is the whole point and\na single `input_per_1m` would be off by an order of magnitude.\n\nxAI prices the audio stream by the minute and does not bill tokens at all;\nits token rates are a real 0.00, not a missing rate.", "properties":{ "audio_input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Audio Input Per 1M" }, "audio_output_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Audio Output Per 1M" }, "cached_audio_input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Cached Audio Input Per 1M" }, "cached_text_input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Cached Text Input Per 1M" }, "per_session_minute":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Per Session Minute" }, "text_input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Text Input Per 1M" }, "text_output_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Text Output Per 1M" } }, "title":"RealtimePricing", "type":"object" }, "RealtimeSpec":{ "additionalProperties":false, "description":"A speech-to-speech model, which replaces stt + llm + tts together.", "properties":{ "model":{ "default":"gpt-realtime-2.1", "title":"Model", "type":"string" }, "provider":{ "default":"openai", "title":"Provider", "type":"string" }, "speed":{ "default":1.0, "maximum":2.0, "minimum":0.5, "title":"Speed", "type":"number" }, "voice":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Voice" }, "voice_name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Voice Name" } }, "title":"RealtimeSpec", "type":"object" }, "RecordingSpec":{ "additionalProperties":false, "description":"Whether calls with this agent are recorded, and whether the caller is told.\n\nOn by default: one stereo file per call, kept until the workspace's\nretention policy deletes it.", "properties":{ "enabled":{ "default":true, "description":"Record the call audio. Voice and video agents only.", "title":"Enabled", "type":"boolean" }, "notice":{ "anyOf":[ { "minLength":1, "type":"string" }, { "type":"null" } ], "description":"Spoken where the greeting places {{recording.notice}}, uninterruptibly. Null: no notice.", "title":"Notice" } }, "title":"RecordingSpec", "type":"object" }, "STTModelSpec":{ "additionalProperties":false, "properties":{ "model":{ "default":"saaras:v4", "title":"Model", "type":"string" }, "provider":{ "default":"sarvam", "title":"Provider", "type":"string" } }, "title":"STTModelSpec", "type":"object" }, "STTPriceLine":{ "properties":{ "audio_duration":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Audio Duration" }, "cost":{ "title":"Cost", "type":"number" }, "input_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Input Tokens" }, "kind":{ "const":"stt", "default":"stt", "title":"Kind", "type":"string" }, "model":{ "title":"Model", "type":"string" }, "output_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Output Tokens" }, "provider":{ "title":"Provider", "type":"string" }, "provider_reported":{ "default":false, "title":"Provider Reported", "type":"boolean" }, "rates":{ "anyOf":[ { "$ref":"#/components/schemas/STTPricing" }, { "type":"null" } ] } }, "required":[ "provider", "model", "cost", "rates", "kind", "audio_duration", "input_tokens", "output_tokens", "provider_reported" ], "title":"STTPriceLine", "type":"object" }, "STTPricing":{ "properties":{ "input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Input Per 1M" }, "output_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Output Per 1M" }, "per_audio_second":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Per Audio Second" } }, "title":"STTPricing", "type":"object" }, "STTSpec":{ "additionalProperties":false, "properties":{ "fallback":{ "anyOf":[ { "$ref":"#/components/schemas/STTModelSpec" }, { "type":"null" } ] }, "model":{ "default":"saaras:v4", "title":"Model", "type":"string" }, "provider":{ "default":"sarvam", "title":"Provider", "type":"string" } }, "title":"STTSpec", "type":"object" }, "SayConfig":{ "additionalProperties":false, "properties":{ "text":{ "title":"Text", "type":"string" }, "wait_for_playback":{ "default":false, "title":"Wait For Playback", "type":"boolean" } }, "required":[ "text" ], "title":"SayConfig", "type":"object" }, "SayOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/SayConfig" }, "kind":{ "const":"say", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"SayOperation", "type":"object" }, "SendDtmfConfig":{ "additionalProperties":false, "properties":{ "digits":{ "description":"Keys to press: 0-9, *, #, A-D. 'w' waits half a second and 'W' one second, for menus that need a pause. Supports {{args.*}} and {{userdata.*}}.", "maxLength":64, "minLength":1, "title":"Digits", "type":"string" } }, "required":[ "digits" ], "title":"SendDtmfConfig", "type":"object" }, "SendDtmfOperation":{ "additionalProperties":false, "description":"Press keys on the call's keypad, for an IVR on the other end.\n\nNot terminal, unlike `end_call` and `transfer`: sending digits and then\nsaying something is the normal case, so a chain carries on afterwards.", "properties":{ "config":{ "$ref":"#/components/schemas/SendDtmfConfig" }, "kind":{ "const":"send_dtmf", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"SendDtmfOperation", "type":"object" }, "SessionEventResponse":{ "description":"One row of the durable runtime trace (`services.session_events`).", "properties":{ "created_at":{ "format":"date-time", "title":"Created At", "type":"string" }, "payload":{ "additionalProperties":true, "title":"Payload", "type":"object" }, "seq":{ "title":"Seq", "type":"integer" }, "type":{ "title":"Type", "type":"string" } }, "required":[ "seq", "type", "payload", "created_at" ], "title":"SessionEventResponse", "type":"object" }, "SessionToolResponse":{ "description":"A tool the agent could call, as it stood on this session.\n\n``id`` is null for a tool defined inline in the request that started the\nsession: it has no `tools` row, and inventing an id would offer a link to a\npage that does not exist.", "properties":{ "description":{ "title":"Description", "type":"string" }, "disable_interruptions":{ "default":false, "title":"Disable Interruptions", "type":"boolean" }, "id":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Id" }, "json_schema":{ "additionalProperties":true, "title":"Json Schema", "type":"object" }, "long_running_task":{ "default":false, "title":"Long Running Task", "type":"boolean" }, "name":{ "title":"Name", "type":"string" }, "silent":{ "default":false, "title":"Silent", "type":"boolean" } }, "required":[ "name", "description" ], "title":"SessionToolResponse", "type":"object" }, "SetVariableConfig":{ "additionalProperties":false, "properties":{ "key":{ "title":"Key", "type":"string" }, "store":{ "enum":[ "tooldata", "userdata" ], "title":"Store", "type":"string" }, "value":{ "title":"Value" } }, "required":[ "key", "value", "store" ], "title":"SetVariableConfig", "type":"object" }, "SetVariableOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/SetVariableConfig" }, "kind":{ "const":"set_variable", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"SetVariableOperation", "type":"object" }, "SilenceSpec":{ "additionalProperties":false, "description":"What the agent does when the caller goes quiet (voice and video).", "properties":{ "enabled":{ "default":true, "description":"Check in on a caller who goes quiet, and hang up if they never answer. Voice and video only.", "title":"Enabled", "type":"boolean" }, "max_check_ins":{ "default":2, "description":"Check-ins before the agent says goodbye and hangs up. 0 hangs up at the first silence.", "maximum":5.0, "minimum":0.0, "title":"Max Check Ins", "type":"integer" }, "timeout":{ "default":10.0, "description":"Seconds of silence after the agent stops talking before it checks in.", "maximum":600.0, "minimum":5.0, "title":"Timeout", "type":"number" } }, "title":"SilenceSpec", "type":"object" }, "StoredAgentPlan":{ "description":"What a call ran, frozen at the moment it started.\n\nWritten only when the call differs from \"the published agent, as-is\" \u2014 so a\nnull `agent_plan` means exactly that. `members[0]` is the agent that\nanswered.", "properties":{ "members":{ "items":{ "$ref":"#/components/schemas/StoredPlanMember" }, "title":"Members", "type":"array" } }, "required":[ "members" ], "title":"StoredAgentPlan", "type":"object" }, "StoredPlanMember":{ "description":"One member of a frozen plan, as `sessions.agent_plan` stores it.", "properties":{ "agent_id":{ "anyOf":[ { "format":"uuid", "type":"string" }, { "type":"null" } ], "title":"Agent Id" }, "name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Name" }, "override":{ "additionalProperties":true, "title":"Override", "type":"object" }, "version":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Version" } }, "required":[ "name", "agent_id", "version", "override" ], "title":"StoredPlanMember", "type":"object" }, "TTSModelSpec":{ "additionalProperties":false, "properties":{ "expressive":{ "default":false, "description":"Let the model write delivery tags - a laugh, a whisper, a pause before the key detail - into what this voice speaks. Only for models whose catalog entry declares an `expressive` dialect; GET /catalog reports it per model.", "title":"Expressive", "type":"boolean" }, "model":{ "default":"bulbul:v3", "title":"Model", "type":"string" }, "provider":{ "default":"sarvam", "title":"Provider", "type":"string" }, "similarity_boost":{ "anyOf":[ { "maximum":1.0, "minimum":0.0, "type":"number" }, { "type":"null" } ], "title":"Similarity Boost" }, "speed":{ "default":1.0, "maximum":2.0, "minimum":0.5, "title":"Speed", "type":"number" }, "stability":{ "anyOf":[ { "maximum":1.0, "minimum":0.0, "type":"number" }, { "type":"null" } ], "title":"Stability" }, "voice":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Voice" }, "voice_name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Voice Name" } }, "title":"TTSModelSpec", "type":"object" }, "TTSPriceLine":{ "properties":{ "audio_duration":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Audio Duration" }, "cached_characters":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Cached Characters" }, "characters_count":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Characters Count" }, "cost":{ "title":"Cost", "type":"number" }, "input_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Input Tokens" }, "kind":{ "const":"tts", "default":"tts", "title":"Kind", "type":"string" }, "model":{ "title":"Model", "type":"string" }, "output_tokens":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Output Tokens" }, "provider":{ "title":"Provider", "type":"string" }, "rates":{ "anyOf":[ { "$ref":"#/components/schemas/TTSPricing" }, { "type":"null" } ] } }, "required":[ "provider", "model", "cost", "rates", "kind", "characters_count", "cached_characters", "audio_duration", "input_tokens", "output_tokens" ], "title":"TTSPriceLine", "type":"object" }, "TTSPricing":{ "properties":{ "cached_per_character":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Cached Per Character" }, "input_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Input Per 1M" }, "output_per_1m":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Output Per 1M" }, "per_audio_second":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Per Audio Second" }, "per_character":{ "anyOf":[ { "type":"number" }, { "type":"null" } ], "title":"Per Character" } }, "title":"TTSPricing", "type":"object" }, "TTSSpec":{ "additionalProperties":false, "properties":{ "expressive":{ "default":false, "description":"Let the model write delivery tags - a laugh, a whisper, a pause before the key detail - into what this voice speaks. Only for models whose catalog entry declares an `expressive` dialect; GET /catalog reports it per model.", "title":"Expressive", "type":"boolean" }, "fallback":{ "anyOf":[ { "$ref":"#/components/schemas/TTSModelSpec" }, { "type":"null" } ] }, "model":{ "default":"bulbul:v3", "title":"Model", "type":"string" }, "provider":{ "default":"sarvam", "title":"Provider", "type":"string" }, "similarity_boost":{ "anyOf":[ { "maximum":1.0, "minimum":0.0, "type":"number" }, { "type":"null" } ], "title":"Similarity Boost" }, "speed":{ "default":1.0, "maximum":2.0, "minimum":0.5, "title":"Speed", "type":"number" }, "stability":{ "anyOf":[ { "maximum":1.0, "minimum":0.0, "type":"number" }, { "type":"null" } ], "title":"Stability" }, "voice":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Voice" }, "voice_name":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Voice Name" } }, "title":"TTSSpec", "type":"object" }, "TaskConfig":{ "additionalProperties":false, "description":"LiveKit's `AgentTask`: an agent with a typed result, on someone else's stack.\n\nIt declares no channel, no media and no greeting. Entered by an agent it\nspeaks with that call's voice and hears with its ears; run on its own from\n`POST /task-runs` it is an LLM with tools and nobody to talk to. Which\nof the two happens is the caller's, never the task's.", "properties":{ "faqs":{ "description":"FAQs the agent answers from: questions go in the prompt, answers are fetched on demand.", "items":{ "$ref":"#/components/schemas/FaqSelection" }, "maxItems":10, "title":"Faqs", "type":"array" }, "finish_without_result_description":{ "default":"Finish without result only if you have failed to achieve the goal of this task and would like to give up rather than continue.", "description":"Description of `finish_without_result`, the tool that abandons a task an agent entered. Narrow it if the task gives up too readily. Unused by a standalone run.", "minLength":1, "title":"Finish Without Result Description", "type":"string" }, "llm":{ "$ref":"#/components/schemas/LLMSpec" }, "max_steps":{ "default":25, "description":"How many LLM -> tools -> LLM rounds a standalone run may take. A round, not a tool call: four tools in one reply cost one step. Entered by an agent, the calling call's own limit applies instead.", "maximum":50.0, "minimum":1.0, "title":"Max Steps", "type":"integer" }, "mcps":{ "description":"MCP servers whose tools may be called \u2014 each named by the integration that holds its credential, or defined inline. Which of a named server's tools may be called is the integration's own `allowed_tools`, not this list.", "items":{ "$ref":"#/components/schemas/McpSelection" }, "title":"Mcps", "type":"array" }, "name":{ "description":"Unique in the workspace.", "minLength":1, "title":"Name", "type":"string" }, "on_enter":{ "anyOf":[ { "$ref":"#/components/schemas/ToolSelection" }, { "type":"null" } ] }, "on_exit":{ "anyOf":[ { "$ref":"#/components/schemas/ToolSelection" }, { "type":"null" } ] }, "on_user_turn_completed":{ "anyOf":[ { "$ref":"#/components/schemas/ToolSelection" }, { "type":"null" } ] }, "output":{ "description":"The typed value this task produces: up to 25 top-level fields, nesting up to 4 levels and 100 fields in all. The model finishes by calling a `submit_result` tool built from them. Publishing needs at least one.", "items":{ "$ref":"#/components/schemas/TaskOutputField" }, "maxItems":25, "title":"Output", "type":"array" }, "prompt":{ "default":"", "description":"The system prompt. `{{vars.name}}` is substituted from the values the run was started with \u2014 or, entered by an agent, from the call's own values and the arguments the model supplied.", "title":"Prompt", "type":"string" }, "submit_result_description":{ "default":"Submit results if you are sure that you have achieved the goal of this task", "description":"Description of the generated `submit_result` tool - what the call is, where the output fields describe the values.", "minLength":1, "title":"Submit Result Description", "type":"string" }, "timeout_seconds":{ "default":300, "description":"How long this may take before it is abandoned. Entered by an agent it is the only bound on how long the caller is held, so keep it short on a voice agent.", "maximum":600.0, "minimum":10.0, "title":"Timeout Seconds", "type":"integer" }, "timezone":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "description":"The IANA timezone this clock runs on, e.g. 'Asia/Kolkata'. Set it and the prompt and tools can read {{system_vars.now}}, {{system_vars.date}} and {{system_vars.time}}. Required only if one of those is used.", "title":"Timezone" }, "tools":{ "description":"Tools the model may call. Publishing pins each one to the tool version live at that moment, so republishing a tool does not change this until it is published again.", "items":{ "$ref":"#/components/schemas/ToolSelection" }, "title":"Tools", "type":"array" }, "vars":{ "description":"The inputs this task takes, read as {{vars.name}} in the prompt and in its tools. Declare only what the caller or the model must supply: anything the task can read for itself ({{userdata.*}}, {{system_vars.*}}) it should read in its prompt instead.", "items":{ "$ref":"#/components/schemas/VarDeclaration" }, "title":"Vars", "type":"array" } }, "required":[ "name" ], "title":"TaskConfig", "type":"object" }, "TaskOutputField":{ "additionalProperties":false, "description":"One value the model must produce: a scalar, an object of named fields, or an array.", "properties":{ "description":{ "description":"What the model should put here, and what to send when it cannot find out. This is the field's description in the tool schema, so it is literally the prompt for this value.", "minLength":1, "title":"Description", "type":"string" }, "enum":{ "anyOf":[ { "items":{ "type":"string" }, "type":"array" }, { "type":"null" } ], "description":"Allowed values. Strings only.", "title":"Enum" }, "fields":{ "anyOf":[ { "items":{ "$ref":"#/components/schemas/TaskOutputField" }, "type":"array" }, { "type":"null" } ], "description":"An object's fields.", "title":"Fields" }, "items":{ "anyOf":[ { "$ref":"#/components/schemas/TaskOutputItem" }, { "type":"null" } ], "description":"An array's element." }, "name":{ "description":"Identifier for this value, as it appears in the run's `output` and anywhere the run is consumed. Lower-case letters, digits and underscores.", "pattern":"^[a-z][a-z0-9_]{0,39}$", "title":"Name", "type":"string" }, "required":{ "default":true, "description":"Refuse a null for this field. Turn it off for a value the model may legitimately fail to find, and say in the description when to send null.", "title":"Required", "type":"boolean" }, "type":{ "default":"string", "description":"The shape of the value. `object` takes `fields`; `array` takes `items`.", "enum":[ "string", "boolean", "integer", "number", "object", "array" ], "title":"Type", "type":"string" } }, "required":[ "name", "description" ], "title":"TaskOutputField", "type":"object" }, "TaskOutputItem":{ "additionalProperties":false, "description":"What an array holds: one element's shape. Unnamed, and never null.", "properties":{ "description":{ "default":"", "description":"What one element is.", "title":"Description", "type":"string" }, "enum":{ "anyOf":[ { "items":{ "type":"string" }, "type":"array" }, { "type":"null" } ], "description":"Allowed values. Strings only.", "title":"Enum" }, "fields":{ "anyOf":[ { "items":{ "$ref":"#/components/schemas/TaskOutputField" }, "type":"array" }, { "type":"null" } ], "description":"An object element's fields.", "title":"Fields" }, "items":{ "anyOf":[ { "$ref":"#/components/schemas/TaskOutputItem" }, { "type":"null" } ], "description":"A nested array's element." }, "type":{ "default":"string", "enum":[ "string", "boolean", "integer", "number", "object", "array" ], "title":"Type", "type":"string" } }, "title":"TaskOutputItem", "type":"object" }, "TaskSelection":{ "additionalProperties":false, "description":"One job this agent can enter and come back from: name a stored task, or\ndefine one inline.", "properties":{ "description":{ "description":"Start with \"Handoff to an agent task responsible for ...\", then say when to enter it and when to skip it.", "minLength":1, "title":"Description", "type":"string" }, "message":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Message" }, "name":{ "pattern":"^[a-zA-Z_][a-zA-Z0-9_]*$", "title":"Name", "type":"string" }, "task":{ "anyOf":[ { "$ref":"#/components/schemas/TaskConfig" }, { "type":"null" } ] }, "task_id":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Task Id" }, "task_version":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Task Version" } }, "required":[ "name", "description" ], "title":"TaskSelection", "type":"object" }, "TeamMemberResponse":{ "description":"One agent on the session's roster. `[0]` is the one that answered.", "properties":{ "agent_id":{ "anyOf":[ { "format":"uuid", "type":"string" }, { "type":"null" } ], "title":"Agent Id" }, "name":{ "title":"Name", "type":"string" }, "version":{ "anyOf":[ { "type":"integer" }, { "const":"draft", "type":"string" }, { "type":"null" } ], "title":"Version" } }, "required":[ "name" ], "title":"TeamMemberResponse", "type":"object" }, "ToolSelection":{ "additionalProperties":false, "description":"A tool the agent may run: name one with `tool_id`, or define one inline.", "properties":{ "tool":{ "anyOf":[ { "$ref":"#/components/schemas/InlineTool" }, { "type":"null" } ] }, "tool_id":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Tool Id" }, "tool_version":{ "anyOf":[ { "type":"integer" }, { "type":"null" } ], "title":"Tool Version" } }, "title":"ToolSelection", "type":"object" }, "TransferConfig":{ "additionalProperties":false, "properties":{ "destination":{ "description":"A literal phone number in full international format, e.g. +14155550101.", "title":"Destination", "type":"string" }, "mode":{ "default":"cold", "enum":[ "cold", "warm" ], "title":"Mode", "type":"string" }, "on_failure":{ "default":"continue", "enum":[ "continue", "end_call" ], "title":"On Failure", "type":"string" }, "ringing_timeout":{ "anyOf":[ { "maximum":120.0, "minimum":5.0, "type":"number" }, { "type":"null" } ], "description":"Seconds the destination may ring. Defaults to 30.", "title":"Ringing Timeout" } }, "required":[ "destination" ], "title":"TransferConfig", "type":"object" }, "TransferOperation":{ "additionalProperties":false, "properties":{ "config":{ "$ref":"#/components/schemas/TransferConfig" }, "kind":{ "const":"transfer", "title":"Kind", "type":"string" }, "on_error":{ "default":"abort", "enum":[ "abort", "continue" ], "title":"On Error", "type":"string" } }, "required":[ "kind", "config" ], "title":"TransferOperation", "type":"object" }, "TurnHandlingSpec":{ "additionalProperties":false, "description":"How the agent decides the caller has finished, and what it does about it.", "properties":{ "endpointing":{ "$ref":"#/components/schemas/EndpointingSpec", "description":"Endpointing configuration." }, "interruption":{ "$ref":"#/components/schemas/InterruptionSpec", "description":"Interruption handling configuration." }, "preemptive_generation":{ "$ref":"#/components/schemas/PreemptiveGenerationSpec", "description":"Preemptive generation configuration." } }, "title":"TurnHandlingSpec", "type":"object" }, "VarDeclaration":{ "additionalProperties":false, "description":"One `{{vars.*}}` variable this agent reads, and what it falls back to.\n\nThe request that starts the session supplies values that override `default`;\nan inbound phone call or message has none, so `default` is what resolves.", "properties":{ "default":{ "anyOf":[ { "type":"string" }, { "type":"null" } ], "title":"Default" }, "description":{ "default":"", "title":"Description", "type":"string" }, "name":{ "minLength":1, "title":"Name", "type":"string" }, "required":{ "default":false, "description":"Refuse the session rather than resolve this to nothing; a `default` satisfies it. An inbound phone call carries no request to supply values, so a voice agent requiring a variable with no default cannot be assigned to a phone number.", "title":"Required", "type":"boolean" }, "type":{ "default":"text", "description":"'file' takes a PDF on a task run. Tasks only.", "enum":[ "text", "file" ], "title":"Type", "type":"string" }, "untrusted":{ "default":false, "description":"Third-party content: given to the model as data, never templated. Tasks only.", "title":"Untrusted", "type":"boolean" } }, "required":[ "name" ], "title":"VarDeclaration", "type":"object" }, "VisionInputSpec":{ "additionalProperties":false, "description":"What the agent watches live during a call, as opposed to images people send it.\n\nWeb voice and video calls only, on a cascade pipeline, and only on a model\nwhose catalog entry says `vision`. Enabling it on `text` is refused.", "properties":{ "screenshare":{ "$ref":"#/components/schemas/VisionSourceSpec" } }, "title":"VisionInputSpec", "type":"object" }, "VisionSourceSpec":{ "additionalProperties":false, "description":"One live video source the agent watches while a call is running.", "properties":{ "enabled":{ "default":false, "description":"Let the agent see this. On each turn it is shown the most recent frame, and only that one, so a long call does not get slower or more expensive over time. Each frame is charged as image input on your language model.", "title":"Enabled", "type":"boolean" }, "record":{ "default":false, "description":"Record what was shared as a 1 fps video, so the call can be replayed with the screen in sync with the audio. Stored and purged exactly like the call recording, under this workspace's retention policy.", "title":"Record", "type":"boolean" } }, "title":"VisionSourceSpec", "type":"object" }, "VoicemailDetectionSpec":{ "additionalProperties":false, "description":"Hang up on, or leave a message for, an outbound call that reaches voicemail.", "properties":{ "enabled":{ "default":false, "description":"On calls the agent places, let it recognise a voicemail greeting and hang up. The call ends as `voicemail`.", "title":"Enabled", "type":"boolean" }, "message":{ "anyOf":[ { "maxLength":2000, "minLength":1, "type":"string" }, { "type":"null" } ], "description":"Spoken word for word after the greeting, then the agent hangs up. Null hangs up without one. Supports the same substitutions as the greeting.", "title":"Message" } }, "title":"VoicemailDetectionSpec", "type":"object" } } } } ```