{"openapi":"3.1.0","info":{"title":"FishAudio OpenAPI","version":"1"},"paths":{"/wallet/{user_id}/package":{"get":{"summary":"Get User Package","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"user_id","description":"User ID or 'self'","required":false,"schema":{"default":"self","title":"User Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"user_id":{"title":"User Id","type":"string"},"type":{"title":"Type","type":"string"},"total":{"title":"Total","type":"integer"},"balance":{"title":"Balance","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"finished_at":{"format":"date-time","title":"Finished At","type":"string"},"stripe_subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Stripe Subscription Id"},"stripe_price_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Stripe Price Id"},"billing_period":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Billing Period"},"current_period_end":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Current Period End"},"cancel_at_period_end":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Cancel At Period End"},"cancel_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Cancel At"},"scheduled_change":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Scheduled Change"},"last_synced_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Last Synced At"},"subscription_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Subscription Currency"},"subscription_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Subscription Status"},"extra_balance":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":0,"title":"Extra Balance"},"has_used_trial":{"default":false,"title":"Has Used Trial","type":"boolean"}},"required":["user_id","type","total","balance","created_at","updated_at","finished_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Wallet"]}},"/wallet/{user_id}/api-credit":{"get":{"summary":"Get API Credit","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"check_free_credit","description":"","required":false,"schema":{"default":false,"title":"Check Free Credit","type":"boolean"},"deprecated":false},{"in":"query","name":"team_id","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Team Id"},"deprecated":false},{"in":"path","name":"user_id","description":"User ID or 'self'","required":false,"schema":{"default":"self","title":"User Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"_id":{"title":"Id","type":"string"},"user_id":{"title":"User Id","type":"string"},"credit":{"title":"Credit","type":"string"},"cumulative_top_up":{"title":"Cumulative Top Up","type":"string"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"has_phone_sha256":{"title":"Has Phone Sha256","type":"boolean"},"has_free_credit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Has Free Credit"}},"required":["_id","user_id","credit","cumulative_top_up","created_at","updated_at","has_phone_sha256"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Wallet"]}},"/v1/agent/sessions":{"get":{"summary":"List Agent Sessions","description":"List your team's sessions, newest first. Filter by agent, status, end\nreason, caller number, or creation time. Paginate with `cursor` (recommended; follow\n`next_cursor` while `has_more` is true) or with `page` for offset pagination\nwith a `total` count — the two are mutually exclusive.","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"agent_id","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"deprecated":false},{"in":"query","name":"status","description":"Comma-separated status filter (pending/active/completed/failed/unknown). Default: every status.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"deprecated":false},{"in":"query","name":"end_reason","description":"Comma-separated end reason filter (user_hangup/agent_hangup/escalated/conversation_timeout/heartbeat_timeout/agent_join_timeout/internal_error/llm_endpoint_failure/room_join_timeout/cancelled/dial_failed).","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"End Reason"},"deprecated":false},{"in":"query","name":"direction","description":"Filter by call direction (inbound/outbound). Sessions predating the field count as inbound.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Direction"},"deprecated":false},{"in":"query","name":"caller_number","description":"Exact-match caller E.164 (phone sessions only).","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caller Number"},"deprecated":false},{"in":"query","name":"created_after","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created After"},"deprecated":false},{"in":"query","name":"created_before","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created Before"},"deprecated":false},{"in":"query","name":"cursor","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cursor"},"deprecated":false},{"in":"query","name":"page","description":"1-based page number (offset pagination). Returns total; mutually exclusive with cursor, which deep scans must use.","required":false,"schema":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page"},"deprecated":false},{"in":"query","name":"include_total","description":"Also count the filtered set on the cursor path.","required":false,"schema":{"default":false,"title":"Include Total","type":"boolean"},"deprecated":false},{"in":"query","name":"page_size","description":"","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"sessions":{"items":{"$ref":"#/components/schemas/AgentSessionSummary"},"title":"Sessions","type":"array"},"has_more":{"title":"Has More","type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"}},"required":["sessions","has_more"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Sessions"]},"post":{"summary":"Create Agent Session","description":"Start a conversation session with an agent and receive a join token for the\nsession transport (currently LiveKit WebRTC). Authenticate with an API key to\nstart sessions with any agent in your team; without credentials only agents\npublished as public are reachable, and the request `Origin` must match the\nagent's allowed origins.\n\n`language` (and `overrides.language`) accepts `en`, `ja`, `zh`, `ko`, `es`,\n`fr`, `de`, `pt`, `it`, `nl`; anything else is 422. Omit it to use the agent's configured\nspeaking language.","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"origin","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Origin"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionCreatePayload"}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"description":"Wire twin of @fishaudio/agent-protocol `SessionToken` (session.ts); keep in sync.","properties":{"session_id":{"title":"Session Id","type":"string"},"expires_at":{"title":"Expires At","type":"string"},"max_duration_seconds":{"title":"Max Duration Seconds","type":"integer"},"transport":{"const":"livekit","title":"Transport","type":"string"},"livekit_url":{"title":"Livekit Url","type":"string"},"token":{"title":"Token","type":"string"}},"required":["session_id","expires_at","max_duration_seconds","transport","livekit_url","token"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"429":{"description":"The user has sent too many requests in a given amount of time (\"rate limiting\")","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Sessions"],"x-codeSamples":[{"lang":"bash","label":"Create Session","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/agent/sessions \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"agent_id\": \"<agent-id>\"\n  }'"}]}},"/v1/agent/sessions/{session_id}":{"get":{"summary":"Get Agent Session","description":"Fetch one session's full detail: status, timing, and the conversation\ntimeline (transcript turns interleaved with tool calls, in order).","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"session_id","description":"","required":true,"schema":{"title":"Session Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"session_id":{"title":"Session Id","type":"string"},"agent_id":{"title":"Agent Id","type":"string"},"agent_name":{"title":"Agent Name","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"status":{"enum":["pending","active","completed","failed","unknown"],"title":"Status","type":"string"},"end_reason":{"anyOf":[{"enum":["user_hangup","agent_hangup","escalated","conversation_timeout","heartbeat_timeout","agent_join_timeout","internal_error","llm_endpoint_failure","room_join_timeout","cancelled","dial_failed"],"type":"string"},{"type":"null"}],"default":null,"title":"End Reason"},"source":{"enum":["api_key","dashboard","public","phone"],"title":"Source","type":"string"},"direction":{"default":"inbound","enum":["inbound","outbound"],"title":"Direction","type":"string"},"dial_status":{"anyOf":[{"enum":["answered","busy","no_answer","failed"],"type":"string"},{"type":"null"}],"default":null,"title":"Dial Status"},"answered_by":{"anyOf":[{"enum":["human","voicemail","unknown"],"type":"string"},{"type":"null"}],"default":null,"title":"Answered By"},"caller_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caller Number"},"dialed_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Dialed Number"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timezone"},"created_at":{"title":"Created At","type":"string"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Started At"},"ended_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ended At"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Duration Seconds"},"metadata":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"title":"Metadata","type":"object"},"unattributed_llm_usage":{"items":{"$ref":"#/components/schemas/LLMMessageUsage"},"title":"Unattributed Llm Usage","type":"array"},"items":{"items":{"discriminator":{"mapping":{"message":"#/components/schemas/AgentSessionMessageItem","tool_call":"#/components/schemas/AgentSessionToolCallItem","tool_result":"#/components/schemas/AgentSessionToolResultItem"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/AgentSessionMessageItem"},{"$ref":"#/components/schemas/AgentSessionToolCallItem"},{"$ref":"#/components/schemas/AgentSessionToolResultItem"}]},"title":"Items","type":"array"},"analysis":{"anyOf":[{"$ref":"#/components/schemas/AgentSessionAnalysisResult"},{"type":"null"}],"default":null}},"required":["session_id","agent_id","agent_name","status","source","created_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Sessions"]}},"/v1/agent/sessions/{session_id}/recording":{"get":{"summary":"Get Agent Session Recording","description":"Return time-limited download URLs for the session's audio recording, one\nper speaker track (agent and user are recorded separately).","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"session_id","description":"","required":true,"schema":{"title":"Session Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"session_id":{"title":"Session Id","type":"string"},"status":{"enum":["processing","complete","failed"],"title":"Status","type":"string"},"tracks":{"items":{"$ref":"#/components/schemas/AgentSessionRecordingTrackEntity"},"title":"Tracks","type":"array"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error Message"}},"required":["session_id","status","tracks"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Sessions"]}},"/v1/agent/sessions/{session_id}/end":{"post":{"summary":"End Agent Session","description":"Hang up a live session: the agent disconnects and the call terminates. The\nsession record, transcript, and recording are retained and stay readable.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"session_id","description":"","required":true,"schema":{"title":"Session Id","type":"string"},"deprecated":false}],"responses":{"204":{"description":"Request fulfilled, nothing follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Sessions"],"x-codeSamples":[{"lang":"bash","label":"End Session","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/agent/sessions/<session-id>/end \\\n  --header 'Authorization: Bearer <token>'"}]}},"/v1/agent/agents":{"get":{"summary":"List Agents","description":"List your team's agents, newest first. Paginate with `cursor` (follow\n`next_cursor` while `has_more` is true) or with `page` for offset\npagination with a `total` count — the two are mutually exclusive.","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"search","description":"Case-insensitive match on name and description.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Search"},"deprecated":false},{"in":"query","name":"include_archived","description":"","required":false,"schema":{"default":false,"title":"Include Archived","type":"boolean"},"deprecated":false},{"in":"query","name":"publication_state","description":"`live` = has a published version; `draft` = never published.","required":false,"schema":{"default":"all","enum":["all","live","draft"],"title":"Publication State","type":"string"},"deprecated":false},{"in":"query","name":"cursor","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cursor"},"deprecated":false},{"in":"query","name":"page","description":"1-based page number (offset pagination). Returns total; mutually exclusive with cursor.","required":false,"schema":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page"},"deprecated":false},{"in":"query","name":"include_total","description":"Also count the filtered set on the cursor path.","required":false,"schema":{"default":false,"title":"Include Total","type":"boolean"},"deprecated":false},{"in":"query","name":"page_size","description":"","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/PublicAgentEntity"},"title":"Agents","type":"array"},"has_more":{"title":"Has More","type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"}},"required":["agents","has_more"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]},"post":{"summary":"Create Agent","description":"Create an agent, optionally with its full initial configuration inline —\none call provisions a ready-to-publish agent. The agent starts as a draft:\npublish it before creating sessions with it.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentCreatePayload"}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"status":{"enum":["active","archived"],"title":"Status","type":"string"},"publication_state":{"description":"`live` once at least one version is published; `draft` agents cannot take sessions yet.","enum":["live","draft"],"title":"Publication State","type":"string"},"public_enabled":{"default":false,"title":"Public Enabled","type":"boolean"},"allowed_origins":{"items":{"type":"string"},"title":"Allowed Origins","type":"array"},"overrides_allowed":{"items":{"enum":["first_message","system_prompt","voice_id","language"],"type":"string"},"title":"Overrides Allowed","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","workspace_id","name","status","publication_state","created_at","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"],"x-codeSamples":[{"lang":"bash","label":"Create Agent","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/agent/agents \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"name\": \"Receptionist\",\n    \"description\": \"Handles inbound calls.\",\n    \"config\": {\n      \"prompt\": {\n        \"system_prompt\": \"You are the receptionist for Fish Dental.\"\n      },\n      \"voice\": {\n        \"voice_id\": \"<voice-model-id>\",\n        \"speaking_language\": \"en\"\n      }\n    }\n  }'"}]}},"/v1/agent/agents/{agent_id}":{"get":{"summary":"Get Agent","description":"Fetch one agent's profile fields. The draft configuration lives at\n`GET /v1/agent/agents/{agent_id}/config`.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"status":{"enum":["active","archived"],"title":"Status","type":"string"},"publication_state":{"description":"`live` once at least one version is published; `draft` agents cannot take sessions yet.","enum":["live","draft"],"title":"Publication State","type":"string"},"public_enabled":{"default":false,"title":"Public Enabled","type":"boolean"},"allowed_origins":{"items":{"type":"string"},"title":"Allowed Origins","type":"array"},"overrides_allowed":{"items":{"enum":["first_message","system_prompt","voice_id","language"],"type":"string"},"title":"Overrides Allowed","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","workspace_id","name","status","publication_state","created_at","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]},"patch":{"summary":"Update Agent","description":"Update agent-level fields (name, description, status, public access and\nsession-override policy). Omitted fields keep their value. Conversation\nbehavior — voice, prompt, recording and the rest — is draft configuration:\nuse `PATCH /v1/agent/agents/{agent_id}/config`.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentUpdatePayload"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"status":{"enum":["active","archived"],"title":"Status","type":"string"},"publication_state":{"description":"`live` once at least one version is published; `draft` agents cannot take sessions yet.","enum":["live","draft"],"title":"Publication State","type":"string"},"public_enabled":{"default":false,"title":"Public Enabled","type":"boolean"},"allowed_origins":{"items":{"type":"string"},"title":"Allowed Origins","type":"array"},"overrides_allowed":{"items":{"enum":["first_message","system_prompt","voice_id","language"],"type":"string"},"title":"Overrides Allowed","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","workspace_id","name","status","publication_state","created_at","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]},"delete":{"summary":"Delete Agent","description":"Delete an agent together with its configuration and version history.\nExisting session records are retained.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false}],"responses":{"204":{"description":"Request fulfilled, nothing follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]}},"/v1/agent/agents/{agent_id}/widget":{"get":{"summary":"Get Widget Config","description":"Unauthenticated display configuration for the embeddable `<fish-agent>`\nwidget. Only agents published as public are reachable, and the request\n`Origin` must match the agent's allowed origins — the same gate as\nanonymous session creation. Attributes set on the embed tag override\nevery field returned here.","parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false},{"in":"header","name":"origin","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Origin"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"description":"Display config for the embeddable `<fish-agent>` widget.\n\nServed without authentication for public agents; HTML attributes on the\nembed tag override every field. Grows alongside the Builder widget tab\n(greeting, policy switches, styles) — additions only, never renames.","properties":{"agent_name":{"title":"Agent Name","type":"string"}},"required":["agent_name"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]}},"/v1/agent/agents/{agent_id}/config":{"get":{"summary":"Get Draft Config","description":"Read the agent's current draft configuration — the state the next publish\nwill freeze. Sessions run the latest published version, not the draft; use\nthe versions endpoints to see what is live. Webhook signing secrets are\nwrite-only and reported as `has_secret`.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"config_hash":{"description":"Content hash of the draft; equal to a version's config_hash when the draft has no unpublished changes.","title":"Config Hash","type":"string"},"prompt":{"$ref":"#/components/schemas/AgentPromptConfig"},"voice":{"$ref":"#/components/schemas/AgentVoiceConfig"},"conversation":{"$ref":"#/components/schemas/AgentConversationConfig"},"tools":{"$ref":"#/components/schemas/PublicAgentToolsConfig"},"webhooks":{"$ref":"#/components/schemas/PublicAgentWebhooksConfig"},"knowledge_base":{"$ref":"#/components/schemas/PublicAgentKnowledgeBaseConfig"},"analysis":{"$ref":"#/components/schemas/AgentAnalysisConfig"},"guardrails":{"$ref":"#/components/schemas/AgentGuardrailsConfig"},"llm":{"$ref":"#/components/schemas/AgentLLMConfigRedacted"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","config_hash","prompt","voice","conversation","tools","webhooks","knowledge_base","analysis","guardrails","llm","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]},"patch":{"summary":"Update Draft Config","description":"Patch the draft configuration section by section; omitted sections keep\ntheir value. Changes only affect live sessions after the next publish.\n`prompt.system_prompt` is limited to 32000 tokens (422 beyond); keeping it\nunder 2000 tokens is recommended for latency and cost.\n`voice.voice_id` accepts any public voice model id.\n`voice.speaking_language` accepts any of the 52 supported ISO 639-1 codes\n(the same set the console offers, see the Voice & language docs); anything else is 422. `voice.expressive` opts into richer expressive\n\ndelivery (emotion steering, laughter and sounds, pauses); off keeps the\nstandard delivery. `voice.keyterms` is a speech-recognition vocabulary of\nup to 50 plain terms (brand names, product terms, personal names), each at\nmost 100 characters with no commas or semicolons; `[]` clears it and 20-50\nfocused terms work best. `tool_ids` and\n`knowledge_source_ids` replace their attachment lists wholesale and every\nid must resolve, else 422. `llm.custom` points the agent at your own\nOpenAI-compatible endpoint; mutually exclusive with `llm.model`, cleared\nwith an explicit null.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentConfigPatchPayload"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"config_hash":{"description":"Content hash of the draft; equal to a version's config_hash when the draft has no unpublished changes.","title":"Config Hash","type":"string"},"prompt":{"$ref":"#/components/schemas/AgentPromptConfig"},"voice":{"$ref":"#/components/schemas/AgentVoiceConfig"},"conversation":{"$ref":"#/components/schemas/AgentConversationConfig"},"tools":{"$ref":"#/components/schemas/PublicAgentToolsConfig"},"webhooks":{"$ref":"#/components/schemas/PublicAgentWebhooksConfig"},"knowledge_base":{"$ref":"#/components/schemas/PublicAgentKnowledgeBaseConfig"},"analysis":{"$ref":"#/components/schemas/AgentAnalysisConfig"},"guardrails":{"$ref":"#/components/schemas/AgentGuardrailsConfig"},"llm":{"$ref":"#/components/schemas/AgentLLMConfigRedacted"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","config_hash","prompt","voice","conversation","tools","webhooks","knowledge_base","analysis","guardrails","llm","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"],"x-codeSamples":[{"lang":"bash","label":"Update Draft Config","source":"curl --request PATCH \\\n  --url https://api.fish.audio/v1/agent/agents/<agent-id>/config \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"prompt\": {\n      \"system_prompt\": \"You are the receptionist for Fish Dental.\"\n    },\n    \"webhooks\": {\n      \"post_call\": [\n        {\n          \"url\": \"https://example.com/hooks/fish\",\n          \"secret\": \"<signing-secret>\"\n        }\n      ]\n    }\n  }'"}]}},"/v1/agent/agents/{agent_id}/publish":{"post":{"summary":"Publish Agent","description":"Freeze the current draft into an immutable version (version_number\nauto-increments) and make it the live configuration for new sessions. If\nthe draft already matches the live version, return that version unchanged.\nThe body is optional; the title and description label a newly created\nversion for audit and rollback.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"version_number":{"title":"Version Number","type":"integer"},"version_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Title"},"version_description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Description"},"config_hash":{"title":"Config Hash","type":"string"},"published_at":{"format":"date-time","title":"Published At","type":"string"}},"required":["version_number","config_hash","published_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"],"x-codeSamples":[{"lang":"bash","label":"Publish","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/agent/agents/<agent-id>/publish \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"version_title\": \"Tighter greeting\"\n  }'"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"version_title":{"type":"string","maxLength":120,"description":"Optional label shown in the version history."},"version_description":{"type":"string","maxLength":2000,"description":"Optional longer note for audit and rollback context."}}}}}}}},"/v1/agent/agents/{agent_id}/versions":{"get":{"summary":"List Agent Versions","description":"The publish history, newest first. The highest version_number is what live\nsessions run. Compare a version's config_hash with the draft's to detect\nunpublished changes.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false},{"in":"query","name":"cursor","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cursor"},"deprecated":false},{"in":"query","name":"page","description":"1-based page number; mutually exclusive with cursor.","required":false,"schema":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page"},"deprecated":false},{"in":"query","name":"include_total","description":"","required":false,"schema":{"default":false,"title":"Include Total","type":"boolean"},"deprecated":false},{"in":"query","name":"page_size","description":"","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"versions":{"items":{"$ref":"#/components/schemas/PublicAgentVersionSummary"},"title":"Versions","type":"array"},"has_more":{"title":"Has More","type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"}},"required":["versions","has_more"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]}},"/v1/agent/agents/{agent_id}/versions/{version_number}":{"get":{"summary":"Get Agent Version","description":"One published version with its full frozen configuration snapshot —\nincluding the current live version. Secrets inside the snapshot are\nredacted the same way as the draft config.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"agent_id","description":"","required":true,"schema":{"title":"Agent Id","type":"string"},"deprecated":false},{"in":"path","name":"version_number","description":"","required":true,"schema":{"title":"Version Number","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"version_number":{"title":"Version Number","type":"integer"},"version_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Title"},"version_description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Description"},"config_hash":{"title":"Config Hash","type":"string"},"published_at":{"format":"date-time","title":"Published At","type":"string"},"config":{"$ref":"#/components/schemas/PublicAgentConfigEntity","description":"The immutable configuration snapshot this version pinned at publish time."}},"required":["version_number","config_hash","published_at","config"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agents"]}},"/v1/agent/available-phone-numbers":{"get":{"summary":"Search Available Phone Numbers","description":"Search the purchasable number inventory. Buy an entry with\n`POST /v1/agent/phone-numbers`; availability is not a reservation, so a listed\nnumber can still be claimed by someone else first.","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"country_code","description":"ISO 3166-1 alpha-2 country code; `US` or `CA`.","required":false,"schema":{"default":"US","title":"Country Code","type":"string"},"deprecated":false},{"in":"query","name":"area_code","description":"Restrict to one area code, e.g. 415.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Area Code"},"deprecated":false},{"in":"query","name":"number_type","description":"The managed inventory is US/CA local numbers only; `toll_free` currently returns 400.","required":false,"schema":{"default":"local","enum":["local","toll_free"],"title":"Number Type","type":"string"},"deprecated":false},{"in":"query","name":"provider","description":"Inventory to search. Only the managed `twilio` inventory (call-transfer support) is available; the parameter is kept so importing your own numbers can extend it later.","required":false,"schema":{"anyOf":[{"const":"twilio","type":"string"},{"type":"null"}],"default":null,"title":"Provider"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"available_phone_numbers":{"description":"Inventory entries forwarded from the provider (number, region, pricing).","items":{"additionalProperties":true,"type":"object"},"title":"Available Phone Numbers","type":"array"}},"required":["available_phone_numbers"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]}},"/v1/agent/knowledge-sources":{"get":{"summary":"List Knowledge Sources","description":"List your team's knowledge sources, newest first. Paginate with `cursor`\n(follow `next_cursor` while `has_more` is true) or with `page` for offset\npagination with a `total` count — the two are mutually exclusive.","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"search","description":"Case-insensitive match on name and file name.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Search"},"deprecated":false},{"in":"query","name":"cursor","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cursor"},"deprecated":false},{"in":"query","name":"page","description":"1-based page number; mutually exclusive with cursor.","required":false,"schema":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page"},"deprecated":false},{"in":"query","name":"include_total","description":"","required":false,"schema":{"default":false,"title":"Include Total","type":"boolean"},"deprecated":false},{"in":"query","name":"page_size","description":"","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"knowledge_sources":{"items":{"$ref":"#/components/schemas/PublicKnowledgeSourceSummary"},"title":"Knowledge Sources","type":"array"},"has_more":{"title":"Has More","type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"}},"required":["knowledge_sources","has_more"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Knowledge Sources"]},"post":{"summary":"Create Knowledge Source","description":"Upload a plain-text or Markdown file (UTF-8, up to 1 MB) as a knowledge\nsource. Send `multipart/form-data` with the file in `source`; `name`\ndefaults to the file name. Attach it to agents via the agent config's\n`knowledge_base.knowledge_source_ids`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"properties":{"source":{"format":"binary","title":"Source","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"default":"","title":"Description","type":"string"}},"required":["source"],"type":"object"}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"properties":{"knowledge_source_id":{"title":"Knowledge Source Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"file_name":{"title":"File Name","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"chunk_count":{"title":"Chunk Count","type":"integer"},"revision_number":{"description":"Increments every time the content is replaced. Drafts always use the newest revision; published versions pin the revision current at publish time.","title":"Revision Number","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"content":{"description":"The full current text content.","title":"Content","type":"string"}},"required":["knowledge_source_id","workspace_id","name","file_name","size_bytes","chunk_count","revision_number","created_at","updated_at","content"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Knowledge Sources"]}},"/v1/agent/knowledge-sources/{source_id}":{"get":{"summary":"Get Knowledge Source","description":"Fetch one knowledge source including its full text content and current\nrevision number.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"source_id","description":"","required":true,"schema":{"title":"Source Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"knowledge_source_id":{"title":"Knowledge Source Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"file_name":{"title":"File Name","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"chunk_count":{"title":"Chunk Count","type":"integer"},"revision_number":{"description":"Increments every time the content is replaced. Drafts always use the newest revision; published versions pin the revision current at publish time.","title":"Revision Number","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"content":{"description":"The full current text content.","title":"Content","type":"string"}},"required":["knowledge_source_id","workspace_id","name","file_name","size_bytes","chunk_count","revision_number","created_at","updated_at","content"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Knowledge Sources"]},"patch":{"summary":"Update Knowledge Source","description":"Rename the source and/or replace its content by uploading a new file in\n`source` (multipart). Replacing content increments `revision_number` while\nthe id stays stable, and every attached agent's draft picks it up\nimmediately; published versions pin the revision they were published with,\nso republish each affected agent to put the new content live — that\ntwo-step (sync content, republish) is the nightly content-sync recipe.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"source_id","description":"","required":true,"schema":{"title":"Source Id","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"properties":{"source":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"title":"Source"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"}},"type":"object"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"knowledge_source_id":{"title":"Knowledge Source Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"file_name":{"title":"File Name","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"chunk_count":{"title":"Chunk Count","type":"integer"},"revision_number":{"description":"Increments every time the content is replaced. Drafts always use the newest revision; published versions pin the revision current at publish time.","title":"Revision Number","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"content":{"description":"The full current text content.","title":"Content","type":"string"}},"required":["knowledge_source_id","workspace_id","name","file_name","size_bytes","chunk_count","revision_number","created_at","updated_at","content"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Knowledge Sources"]},"delete":{"summary":"Delete Knowledge Source","description":"Delete a knowledge source. Returns 409 while any agent still references it\n— in its draft or in its currently published version (sessions resolve\nsources at call time, so deleting a published reference would change a\nrunning agent). Check `GET /v1/agent/knowledge-sources/{source_id}/agents`,\ndetach via the agent config, and republish if needed before deleting.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"source_id","description":"","required":true,"schema":{"title":"Source Id","type":"string"},"deprecated":false}],"responses":{"204":{"description":"Request fulfilled, nothing follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Knowledge Sources"]}},"/v1/agent/knowledge-sources/{source_id}/agents":{"get":{"summary":"List Agents Using Knowledge Source","description":"Every agent that references this source in its draft or currently\npublished configuration — the pre-flight check before a delete.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"source_id","description":"","required":true,"schema":{"title":"Source Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agents":{"description":"Agents that reference this resource in their configuration.","items":{"$ref":"#/components/schemas/PublicDependentAgent"},"title":"Agents","type":"array"},"total":{"title":"Total","type":"integer"}},"required":["agents","total"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Knowledge Sources"]}},"/v1/agent/tools":{"get":{"summary":"List Tools","description":"List your team's tools, newest first. Filter with `agent_id` to see one\nagent's attached tools. Paginate with `cursor` (follow `next_cursor` while\n`has_more` is true) or with `page` for offset pagination with a `total`\ncount — the two are mutually exclusive.","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"search","description":"Case-insensitive match on name.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Search"},"deprecated":false},{"in":"query","name":"agent_id","description":"Only tools attached to this agent's draft config.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"deprecated":false},{"in":"query","name":"cursor","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cursor"},"deprecated":false},{"in":"query","name":"page","description":"1-based page number; mutually exclusive with cursor.","required":false,"schema":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page"},"deprecated":false},{"in":"query","name":"include_total","description":"","required":false,"schema":{"default":false,"title":"Include Total","type":"boolean"},"deprecated":false},{"in":"query","name":"page_size","description":"","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/PublicAgentToolSummary"},"title":"Tools","type":"array"},"has_more":{"title":"Has More","type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"}},"required":["tools","has_more"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Tools"]},"post":{"summary":"Create Tool","description":"Create a workspace tool. `tool_type: webhook` calls your HTTP endpoint\nduring conversations; `tool_type: client` is executed by your own frontend\nthrough the SDK (no URL). Attach it to agents via the agent config's\n`tools.tool_ids`. Credential headers (authorization_bearer /\nauthorization_basic) are write-only and read back as `has_secret`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentToolCreatePayload"}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"properties":{"tool_id":{"title":"Tool Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"tool_type":{"enum":["webhook","client"],"title":"Tool Type","type":"string"},"method":{"enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","type":"string"},"url":{"title":"Url","type":"string"},"used_by":{"default":0,"description":"How many agents reference this tool in their draft configuration.","title":"Used By","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"arguments":{"items":{"$ref":"#/components/schemas/AgentWebhookArgumentPayload"},"title":"Arguments","type":"array"},"content_type":{"title":"Content Type","type":"string"},"body_template":{"default":"","title":"Body Template","type":"string"},"headers":{"items":{"$ref":"#/components/schemas/PublicToolHeader"},"title":"Headers","type":"array"},"timeout_seconds":{"title":"Timeout Seconds","type":"integer"},"error_handling":{"enum":["passthrough","hide"],"title":"Error Handling","type":"string"},"mock_responses":{"items":{"$ref":"#/components/schemas/AgentWebhookMockResponsePayload"},"title":"Mock Responses","type":"array"},"expects_response":{"default":true,"title":"Expects Response","type":"boolean"},"execution_mode":{"default":"blocking","enum":["blocking","fire_and_forget","background"],"title":"Execution Mode","type":"string"}},"required":["tool_id","workspace_id","name","tool_type","method","url","created_at","updated_at","content_type","timeout_seconds","error_handling"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Tools"],"x-codeSamples":[{"lang":"bash","label":"Create Webhook Tool","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/agent/tools \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"name\": \"Book appointment\",\n    \"description\": \"Creates an appointment in the scheduling system.\",\n    \"method\": \"POST\",\n    \"url\": \"https://api.example.com/appointments\",\n    \"arguments\": [\n      {\"name\": \"date\", \"description\": \"Appointment date, YYYY-MM-DD\"}\n    ],\n    \"body_template\": \"{\\\"date\\\": \\\"{{date}}\\\"}\",\n    \"headers\": [\n      {\"name\": \"Authorization\", \"value\": \"Bearer <api-token>\", \"kind\": \"authorization_bearer\"}\n    ]\n  }'"}]}},"/v1/agent/tools/{tool_id}":{"get":{"summary":"Get Tool","description":"Fetch one tool's full definition. Credential header values are never\nreturned — each credential header reports `has_secret` instead.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"tool_id","description":"","required":true,"schema":{"title":"Tool Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"tool_id":{"title":"Tool Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"tool_type":{"enum":["webhook","client"],"title":"Tool Type","type":"string"},"method":{"enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","type":"string"},"url":{"title":"Url","type":"string"},"used_by":{"default":0,"description":"How many agents reference this tool in their draft configuration.","title":"Used By","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"arguments":{"items":{"$ref":"#/components/schemas/AgentWebhookArgumentPayload"},"title":"Arguments","type":"array"},"content_type":{"title":"Content Type","type":"string"},"body_template":{"default":"","title":"Body Template","type":"string"},"headers":{"items":{"$ref":"#/components/schemas/PublicToolHeader"},"title":"Headers","type":"array"},"timeout_seconds":{"title":"Timeout Seconds","type":"integer"},"error_handling":{"enum":["passthrough","hide"],"title":"Error Handling","type":"string"},"mock_responses":{"items":{"$ref":"#/components/schemas/AgentWebhookMockResponsePayload"},"title":"Mock Responses","type":"array"},"expects_response":{"default":true,"title":"Expects Response","type":"boolean"},"execution_mode":{"default":"blocking","enum":["blocking","fire_and_forget","background"],"title":"Execution Mode","type":"string"}},"required":["tool_id","workspace_id","name","tool_type","method","url","created_at","updated_at","content_type","timeout_seconds","error_handling"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Tools"]},"patch":{"summary":"Update Tool","description":"Patch tool fields; omitted fields keep their value (null is rejected —\nsend an empty string to clear a text field). `headers` replaces the header\nlist wholesale — include credential values again whenever you send it,\nsince reads never return them. Attached agents' drafts pick up the change\nimmediately; published versions stay frozen until re-published.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"tool_id","description":"","required":true,"schema":{"title":"Tool Id","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentToolUpdatePayload"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"tool_id":{"title":"Tool Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"tool_type":{"enum":["webhook","client"],"title":"Tool Type","type":"string"},"method":{"enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","type":"string"},"url":{"title":"Url","type":"string"},"used_by":{"default":0,"description":"How many agents reference this tool in their draft configuration.","title":"Used By","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"arguments":{"items":{"$ref":"#/components/schemas/AgentWebhookArgumentPayload"},"title":"Arguments","type":"array"},"content_type":{"title":"Content Type","type":"string"},"body_template":{"default":"","title":"Body Template","type":"string"},"headers":{"items":{"$ref":"#/components/schemas/PublicToolHeader"},"title":"Headers","type":"array"},"timeout_seconds":{"title":"Timeout Seconds","type":"integer"},"error_handling":{"enum":["passthrough","hide"],"title":"Error Handling","type":"string"},"mock_responses":{"items":{"$ref":"#/components/schemas/AgentWebhookMockResponsePayload"},"title":"Mock Responses","type":"array"},"expects_response":{"default":true,"title":"Expects Response","type":"boolean"},"execution_mode":{"default":"blocking","enum":["blocking","fire_and_forget","background"],"title":"Execution Mode","type":"string"}},"required":["tool_id","workspace_id","name","tool_type","method","url","created_at","updated_at","content_type","timeout_seconds","error_handling"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Tools"]},"delete":{"summary":"Delete Tool","description":"Delete a tool. Returns 409 while any agent's draft configuration still\nreferences it — check `GET /v1/agent/tools/{tool_id}/agents` and detach it\nvia the agent config first, so a delete can never silently change agent\nbehavior.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"tool_id","description":"","required":true,"schema":{"title":"Tool Id","type":"string"},"deprecated":false}],"responses":{"204":{"description":"Request fulfilled, nothing follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Tools"]}},"/v1/agent/tools/{tool_id}/agents":{"get":{"summary":"List Agents Using Tool","description":"Every agent whose draft configuration references this tool — the\npre-flight check before a delete. Published versions keep executing their\nfrozen tool snapshot, so only draft references block deletion.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"tool_id","description":"","required":true,"schema":{"title":"Tool Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"agents":{"description":"Agents that reference this resource in their configuration.","items":{"$ref":"#/components/schemas/PublicDependentAgent"},"title":"Agents","type":"array"},"total":{"title":"Total","type":"integer"}},"required":["agents","total"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Agent Tools"]}},"/v1/agent/phone-numbers":{"get":{"summary":"List Phone Numbers","description":"List your team's phone numbers, newest first. Released numbers are gone\nfor good and never appear. Look an id up by E.164 with `phone_number`, or\nfilter with `agent_id` to see one agent's numbers. Paginate with `cursor`\n(follow `next_cursor` while `has_more` is true) or with `page` for offset\npagination with a `total` count — the two are mutually exclusive.","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"phone_number","description":"Exact E.164 match, e.g. +14155550123.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"},"deprecated":false},{"in":"query","name":"agent_id","description":"Only numbers bound to this agent.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"deprecated":false},{"in":"query","name":"cursor","description":"","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cursor"},"deprecated":false},{"in":"query","name":"page","description":"1-based page number; mutually exclusive with cursor.","required":false,"schema":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Page"},"deprecated":false},{"in":"query","name":"include_total","description":"","required":false,"schema":{"default":false,"title":"Include Total","type":"boolean"},"deprecated":false},{"in":"query","name":"page_size","description":"","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"phone_numbers":{"items":{"$ref":"#/components/schemas/PublicPhoneNumberEntity"},"title":"Phone Numbers","type":"array"},"has_more":{"title":"Has More","type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"}},"required":["phone_numbers","has_more"],"type":"object"}}}},"400":{"description":"Bad request syntax or unsupported method","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]},"post":{"summary":"Purchase or Import Phone Number","description":"`provider` discriminates two variants. `twilio` buys a number from the\nmanaged inventory: it lands in your default workspace, any `agent_id` you\nbind must live there too, and billing is the monthly price charged in\ndaily slices; the first day is charged before anything is bought (402\ncosts you nothing) and the daily run advances it from there. `sip`\nimports a number you already own at your carrier: point your trunk's\norigination at our SIP host, provide inbound authentication (digest\nand/or source CIDRs) and optionally a termination host so the number can\nplace calls; nothing is rented and there is no monthly fee. Either way,\n409 means the number is already on the platform; 502 means the provider\nor trunk provisioning refused, and the number stays visible with status\n`error` and is safe to release.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PublicPhoneNumberPurchasePayload"},{"$ref":"#/components/schemas/PublicSipNumberImportPayload"}]}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"properties":{"phone_number_id":{"title":"Phone Number Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"phone_number":{"description":"E.164, e.g. +14155550123.","title":"Phone Number","type":"string"},"provider":{"enum":["livekit","twilio","sip"],"title":"Provider","type":"string"},"label":{"default":"","title":"Label","type":"string"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Inbound calls route to this agent; unbound numbers ring busy.","title":"Agent Id"},"cold_transfer_use_original_caller":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Managed `twilio` numbers: whether a transfer target, cold or warm, sees the original caller's number (true) or this number (false). `null` for imported `sip` numbers, whose carrier owns the setting.","title":"Cold Transfer Use Original Caller"},"cold_transfer_use_original_caller_effective":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The cold-transfer policy the carrier has confirmed; `null` while unknown or for imported `sip` numbers. Warm transfers follow `cold_transfer_use_original_caller` directly from the next call.","title":"Cold Transfer Use Original Caller Effective"},"caller_id_sync_status":{"default":"carrier_managed","description":"`synced` once the carrier confirmed the policy, `pending` while it is being applied, `error` when the last attempt failed (send `retry_caller_id_sync`), `carrier_managed` for imported `sip` numbers.","enum":["synced","pending","error","carrier_managed"],"title":"Caller Id Sync Status","type":"string"},"caller_id_sync_error":{"default":"","description":"Why the last synchronization failed; empty otherwise.","title":"Caller Id Sync Error","type":"string"},"status":{"enum":["provisioning","active","error","released"],"title":"Status","type":"string"},"status_detail":{"default":"","description":"What failed when status is `error`; empty otherwise.","title":"Status Detail","type":"string"},"supports_outbound":{"default":false,"description":"Whether the number can place calls (outbound and warm-transfer consult legs): managed `twilio` always, imported `sip` only when a termination was configured.","title":"Supports Outbound","type":"boolean"},"termination_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the customer trunk's termination host.","title":"Termination Uri"},"inbound_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the inbound digest username. Passwords are never echoed.","title":"Inbound Auth Username"},"inbound_allowed_addresses":{"description":"Imported `sip` numbers: allowed source IPs/CIDRs.","items":{"type":"string"},"title":"Inbound Allowed Addresses","type":"array"},"termination_transport":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: termination transport.","title":"Termination Transport"},"termination_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the termination digest username. Passwords are never echoed.","title":"Termination Auth Username"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["phone_number_id","workspace_id","phone_number","provider","agent_id","status","created_at","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]}},"/v1/agent/phone-numbers/{phone_number_id}":{"get":{"summary":"Get Phone Number","description":"Fetch one phone number, including its current agent binding and\nprovisioning status.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"phone_number_id","description":"","required":true,"schema":{"title":"Phone Number Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"phone_number_id":{"title":"Phone Number Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"phone_number":{"description":"E.164, e.g. +14155550123.","title":"Phone Number","type":"string"},"provider":{"enum":["livekit","twilio","sip"],"title":"Provider","type":"string"},"label":{"default":"","title":"Label","type":"string"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Inbound calls route to this agent; unbound numbers ring busy.","title":"Agent Id"},"cold_transfer_use_original_caller":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Managed `twilio` numbers: whether a transfer target, cold or warm, sees the original caller's number (true) or this number (false). `null` for imported `sip` numbers, whose carrier owns the setting.","title":"Cold Transfer Use Original Caller"},"cold_transfer_use_original_caller_effective":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The cold-transfer policy the carrier has confirmed; `null` while unknown or for imported `sip` numbers. Warm transfers follow `cold_transfer_use_original_caller` directly from the next call.","title":"Cold Transfer Use Original Caller Effective"},"caller_id_sync_status":{"default":"carrier_managed","description":"`synced` once the carrier confirmed the policy, `pending` while it is being applied, `error` when the last attempt failed (send `retry_caller_id_sync`), `carrier_managed` for imported `sip` numbers.","enum":["synced","pending","error","carrier_managed"],"title":"Caller Id Sync Status","type":"string"},"caller_id_sync_error":{"default":"","description":"Why the last synchronization failed; empty otherwise.","title":"Caller Id Sync Error","type":"string"},"status":{"enum":["provisioning","active","error","released"],"title":"Status","type":"string"},"status_detail":{"default":"","description":"What failed when status is `error`; empty otherwise.","title":"Status Detail","type":"string"},"supports_outbound":{"default":false,"description":"Whether the number can place calls (outbound and warm-transfer consult legs): managed `twilio` always, imported `sip` only when a termination was configured.","title":"Supports Outbound","type":"boolean"},"termination_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the customer trunk's termination host.","title":"Termination Uri"},"inbound_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the inbound digest username. Passwords are never echoed.","title":"Inbound Auth Username"},"inbound_allowed_addresses":{"description":"Imported `sip` numbers: allowed source IPs/CIDRs.","items":{"type":"string"},"title":"Inbound Allowed Addresses","type":"array"},"termination_transport":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: termination transport.","title":"Termination Transport"},"termination_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the termination digest username. Passwords are never echoed.","title":"Termination Auth Username"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["phone_number_id","workspace_id","phone_number","provider","agent_id","status","created_at","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]},"patch":{"summary":"Update Phone Number","description":"Change the label and/or repoint the number at another agent — the\ndeployment-pipeline move (rebind from the staging agent to the production\none). Send `agent_id: null` to unbind; unbound numbers ring busy. The\nagent must live in the number's workspace. Rebinding is a routing-table\nupdate resolved on the next inbound call; nothing about the number itself\nis reprovisioned.\n\nManaged `twilio` numbers also accept `cold_transfer_use_original_caller`,\nwhich picks the number a transfer target sees (cold and warm alike), and\n`retry_caller_id_sync` to re-apply it after a failed synchronization; read\n`caller_id_sync_status` on the response. Imported `sip` numbers return 409\nfor either field because their carrier owns the setting.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"phone_number_id","description":"","required":true,"schema":{"title":"Phone Number Id","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPhoneNumberUpdatePayload"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"phone_number_id":{"title":"Phone Number Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"phone_number":{"description":"E.164, e.g. +14155550123.","title":"Phone Number","type":"string"},"provider":{"enum":["livekit","twilio","sip"],"title":"Provider","type":"string"},"label":{"default":"","title":"Label","type":"string"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Inbound calls route to this agent; unbound numbers ring busy.","title":"Agent Id"},"cold_transfer_use_original_caller":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Managed `twilio` numbers: whether a transfer target, cold or warm, sees the original caller's number (true) or this number (false). `null` for imported `sip` numbers, whose carrier owns the setting.","title":"Cold Transfer Use Original Caller"},"cold_transfer_use_original_caller_effective":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The cold-transfer policy the carrier has confirmed; `null` while unknown or for imported `sip` numbers. Warm transfers follow `cold_transfer_use_original_caller` directly from the next call.","title":"Cold Transfer Use Original Caller Effective"},"caller_id_sync_status":{"default":"carrier_managed","description":"`synced` once the carrier confirmed the policy, `pending` while it is being applied, `error` when the last attempt failed (send `retry_caller_id_sync`), `carrier_managed` for imported `sip` numbers.","enum":["synced","pending","error","carrier_managed"],"title":"Caller Id Sync Status","type":"string"},"caller_id_sync_error":{"default":"","description":"Why the last synchronization failed; empty otherwise.","title":"Caller Id Sync Error","type":"string"},"status":{"enum":["provisioning","active","error","released"],"title":"Status","type":"string"},"status_detail":{"default":"","description":"What failed when status is `error`; empty otherwise.","title":"Status Detail","type":"string"},"supports_outbound":{"default":false,"description":"Whether the number can place calls (outbound and warm-transfer consult legs): managed `twilio` always, imported `sip` only when a termination was configured.","title":"Supports Outbound","type":"boolean"},"termination_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the customer trunk's termination host.","title":"Termination Uri"},"inbound_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the inbound digest username. Passwords are never echoed.","title":"Inbound Auth Username"},"inbound_allowed_addresses":{"description":"Imported `sip` numbers: allowed source IPs/CIDRs.","items":{"type":"string"},"title":"Inbound Allowed Addresses","type":"array"},"termination_transport":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: termination transport.","title":"Termination Transport"},"termination_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the termination digest username. Passwords are never echoed.","title":"Termination Auth Username"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["phone_number_id","workspace_id","phone_number","provider","agent_id","status","created_at","updated_at"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]},"delete":{"summary":"Release Phone Number","description":"Release a number back to the provider's inventory and stop its daily\nbilling. This is irreversible: anyone — including other platforms — can\nbuy the number afterwards, so callers who saved it may reach a stranger.\nThe number disappears from this API immediately.","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"phone_number_id","description":"","required":true,"schema":{"title":"Phone Number Id","type":"string"},"deprecated":false}],"responses":{"204":{"description":"Request fulfilled, nothing follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]}},"/v1/agent/phone-calls":{"post":{"summary":"Create Phone Call","description":"Place an outbound call from one of your Twilio phone numbers to a US,\nCanada or Japan destination. A domestic trunk 0 after +81 (e.g.\n+81080...) is accepted and normalized to E.164 (+8180...). Returns\nimmediately with the session queued for\ndialing; subscribe to the `phone_call.dial_finished` webhook or poll\n`GET /v1/agent/sessions/{session_id}` for the dial outcome. Ringing is\nnever billed — metering starts when the callee answers.\n\nErrors carry a machine-readable `reason` (e.g. `destination_not_allowed`,\n`insufficient_credit`, `daily_limit_exceeded`,\n`concurrency_limit_exceeded`).","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"idempotency-key","description":"Retry-safe replay key: the same key with the same body returns the call already placed instead of dialing again (24h window).","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Idempotency-Key"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneCallCreatePayload"}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"properties":{"session_id":{"title":"Session Id","type":"string"},"status":{"const":"queued","default":"queued","title":"Status","type":"string"}},"required":["session_id"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"409":{"description":"Request conflict","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"429":{"description":"The user has sent too many requests in a given amount of time (\"rate limiting\")","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"502":{"description":"Invalid responses from another server/proxy","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Calls"],"x-codeSamples":[{"lang":"bash","label":"Create Phone Call","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/agent/phone-calls \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Idempotency-Key: <unique-key>' \\\n  --data '{\n    \"agent_id\": \"<agent-id>\",\n    \"phone_number_id\": \"<phone-number-id>\",\n    \"to_number\": \"+14155550123\"\n  }'"}]}},"/v1/asr":{"post":{"summary":"Speech to Text","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"model","description":"Specify which speech-to-text model to use.","required":false,"schema":{"default":"transcribe-1","enum":["transcribe-1","transcribe-1-pro"],"title":"Model","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"properties":{"audio":{"description":"Audio file to be converted to text","format":"binary","title":"Audio","type":"string"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional hint. The language is auto-detected regardless; the detected language is returned as `language_code`.","title":"Language"},"ignore_timestamps":{"default":true,"description":"Whether to return precise timestamps in the text, this will increase the latency in audio shorter than 30 seconds","title":"Ignore Timestamps","type":"boolean"}},"required":["audio"],"type":"object"}},"application/msgpack":{"schema":{"properties":{"audio":{"description":"Audio file to be converted to text","format":"binary","title":"Audio","type":"string"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional hint. The language is auto-detected regardless; the detected language is returned as `language_code`.","title":"Language"},"ignore_timestamps":{"default":true,"description":"Whether to return precise timestamps in the text, this will increase the latency in audio shorter than 30 seconds","title":"Ignore Timestamps","type":"boolean"}},"required":["audio"],"type":"object"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"text":{"title":"Text","type":"string"},"duration":{"description":"Duration of the audio in seconds","title":"Duration","type":"number"},"segments":{"items":{"$ref":"#/components/schemas/ASRSegment"},"title":"Segments","type":"array"},"language_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Detected language as an ISO 639-1 code (e.g. `en`, `ja`). Omitted if no language is detected.","title":"Language Code"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Detected language name (e.g. `English`). For display only; use `language_code` in code.","title":"Language"}},"required":["text","duration","segments"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["OpenAPI v1"]}},"/v1/tts":{"post":{"summary":"Text to Speech","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"model","description":"Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier. `drama-3-preview` is a preview model; its behavior and availability may change. If omitted or set to an unrecognized value, the request falls back to `s2.1-pro`.","required":false,"schema":{"default":"s2.1-pro","enum":["s1","s2-pro","s2.1-pro","s2.1-pro-free","drama-3-preview"],"title":"Model","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSRequest"}},"application/msgpack":{"schema":{"$ref":"#/components/schemas/TTSRequest"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{"Transfer-Encoding":{"schema":{"type":"string"},"description":"chunked"}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["OpenAPI v1"],"x-codeSamples":[{"lang":"bash","label":"Single Speaker","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/tts \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --header 'model: s2.1-pro-free' \\\n  --data '{\n    \"text\": \"Hello! Welcome to Fish Audio.\",\n    \"reference_id\": \"model-id\",\n    \"temperature\": 0.7,\n    \"top_p\": 0.7,\n    \"prosody\": {\n      \"speed\": 1,\n      \"volume\": 0,\n      \"normalize_loudness\": true\n    },\n    \"chunk_length\": 300,\n    \"normalize\": true,\n    \"format\": \"mp3\",\n    \"sample_rate\": 44100,\n    \"mp3_bitrate\": 128,\n    \"latency\": \"normal\",\n    \"max_new_tokens\": 1024,\n    \"repetition_penalty\": 1.2,\n    \"min_chunk_length\": 50,\n    \"condition_on_previous_chunks\": true,\n    \"early_stop_threshold\": 1\n  }'"},{"lang":"bash","label":"Multi Speaker (S2 family only)","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/tts \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --header 'model: s2.1-pro-free' \\\n  --data '{\n    \"text\": \"<|speaker:0|>Hello!<|speaker:1|>Hi there!\",\n    \"reference_id\": [\"speaker-a-id\", \"speaker-b-id\"],\n    \"temperature\": 0.7,\n    \"top_p\": 0.7,\n    \"prosody\": {\n      \"speed\": 1,\n      \"volume\": 0,\n      \"normalize_loudness\": true\n    },\n    \"chunk_length\": 300,\n    \"normalize\": true,\n    \"format\": \"mp3\",\n    \"sample_rate\": 44100,\n    \"mp3_bitrate\": 128,\n    \"latency\": \"normal\",\n    \"max_new_tokens\": 1024,\n    \"repetition_penalty\": 1.2,\n    \"min_chunk_length\": 50,\n    \"condition_on_previous_chunks\": true,\n    \"early_stop_threshold\": 1\n  }'"}]}},"/v1/tts/stream/with-timestamp":{"post":{"summary":"Text to Speech Stream with Timestamps","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"model","description":"Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier. `drama-3-preview` is a preview model; its behavior and availability may change. If omitted or set to an unrecognized value, the request falls back to `s2.1-pro`.","required":false,"schema":{"default":"s2.1-pro","enum":["s1","s2-pro","s2.1-pro","s2.1-pro-free","drama-3-preview"],"title":"Model","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSStreamWithTimestampRequest"}},"application/msgpack":{"schema":{"$ref":"#/components/schemas/TTSStreamWithTimestampRequest"}}}},"responses":{"200":{"description":"Server-Sent Events stream. Each `message` event contains a JSON payload with one base64 audio chunk. Concatenate every `audio_base64` chunk in arrival order to reconstruct the complete audio. `alignment` is the latest cumulative timestamp snapshot for `chunk_seq`; clients should replace the previous snapshot for that chunk instead of appending segments. `chunk_audio_offset_sec` can be added to segment times to derive absolute timestamps in the full audio.","headers":{"Transfer-Encoding":{"schema":{"type":"string"},"description":"chunked"}},"content":{"text/event-stream":{"schema":{"description":"One Server-Sent Events message payload for streaming TTS with timestamps. Each event contains one audio chunk. Concatenate all `audio_base64` chunks in arrival order to reconstruct the complete audio. `alignment` is the latest cumulative timestamp snapshot for the reported `chunk_seq`; clients should replace the previous snapshot for that chunk instead of appending segments.","examples":[{"alignment":{"audio_duration":16.24,"segments":[{"end":0.16,"start":0.0,"text":"I"},{"end":0.48,"start":0.16,"text":"can't"},{"end":0.8,"start":0.48,"text":"believe"},{"end":1.12,"start":0.8,"text":"its"},{"end":1.44,"start":1.2,"text":"been"},{"end":1.76,"start":1.44,"text":"this"},{"end":2.48,"start":1.76,"text":"long"},{"end":2.64,"start":2.56,"text":"It"},{"end":3.04,"start":2.72,"text":"feels"},{"end":3.28,"start":3.12,"text":"like"},{"end":4.0,"start":3.36,"text":"forever"},{"end":4.32,"start":4.0,"text":"since"},{"end":4.48,"start":4.32,"text":"we"},{"end":4.96,"start":4.48,"text":"last"},{"end":5.28,"start":4.96,"text":"really"},{"end":5.84,"start":5.28,"text":"talked"},{"end":6.24,"start":6.0,"text":"Ive"},{"end":6.64,"start":6.24,"text":"missed"},{"end":6.96,"start":6.64,"text":"hearing"},{"end":7.2,"start":6.96,"text":"your"},{"end":7.76,"start":7.2,"text":"voice"},{"end":7.92,"start":7.76,"text":"your"},{"end":8.48,"start":7.92,"text":"stories"},{"end":8.72,"start":8.48,"text":"even"},{"end":8.8,"start":8.72,"text":"the"},{"end":9.2,"start":8.8,"text":"little"},{"end":9.52,"start":9.2,"text":"things"},{"end":9.68,"start":9.52,"text":"you"},{"end":10.0,"start":9.68,"text":"used"},{"end":10.08,"start":10.0,"text":"to"},{"end":10.64,"start":10.08,"text":"say"},{"end":10.96,"start":10.64,"text":"How"},{"end":11.12,"start":10.96,"text":"have"},{"end":11.36,"start":11.12,"text":"you"},{"end":11.92,"start":11.36,"text":"been"},{"end":12.24,"start":12.0,"text":"Ive"},{"end":12.48,"start":12.24,"text":"thought"},{"end":12.8,"start":12.48,"text":"about"},{"end":13.2,"start":12.8,"text":"calling"},{"end":13.36,"start":13.2,"text":"you"},{"end":13.68,"start":13.36,"text":"so"},{"end":13.92,"start":13.68,"text":"many"},{"end":14.56,"start":13.92,"text":"times"},{"end":14.72,"start":14.56,"text":"but"},{"end":14.88,"start":14.72,"text":"I"},{"end":15.2,"start":14.88,"text":"never"},{"end":15.36,"start":15.2,"text":"knew"},{"end":15.6,"start":15.36,"text":"where"},{"end":15.6,"start":15.6,"text":"to"},{"end":16.24,"start":15.68,"text":"start"}]},"audio_base64":"SUQzBAAAAAAA...","chunk_audio_offset_sec":0.0,"chunk_seq":0,"content":"I can’t believe it’s been this long. It feels like forever since we last really talked. I’ve missed hearing your voice, your stories, even the little things you used to say. How have you been? I’ve thought about calling you so many times, but I never knew where to start."},{"alignment":{"audio_duration":16.24,"segments":[{"end":0.16,"start":0.0,"text":"I"},{"end":0.48,"start":0.16,"text":"can't"},{"end":0.8,"start":0.48,"text":"believe"},{"end":1.12,"start":0.8,"text":"its"},{"end":1.44,"start":1.2,"text":"been"},{"end":1.76,"start":1.44,"text":"this"},{"end":2.48,"start":1.76,"text":"long"},{"end":2.64,"start":2.56,"text":"It"},{"end":3.04,"start":2.72,"text":"feels"},{"end":3.28,"start":3.12,"text":"like"},{"end":4.0,"start":3.36,"text":"forever"},{"end":4.32,"start":4.0,"text":"since"},{"end":4.48,"start":4.32,"text":"we"},{"end":4.96,"start":4.48,"text":"last"},{"end":5.28,"start":4.96,"text":"really"},{"end":5.84,"start":5.28,"text":"talked"},{"end":6.24,"start":6.0,"text":"Ive"},{"end":6.64,"start":6.24,"text":"missed"},{"end":6.96,"start":6.64,"text":"hearing"},{"end":7.2,"start":6.96,"text":"your"},{"end":7.76,"start":7.2,"text":"voice"},{"end":7.92,"start":7.76,"text":"your"},{"end":8.48,"start":7.92,"text":"stories"},{"end":8.72,"start":8.48,"text":"even"},{"end":8.8,"start":8.72,"text":"the"},{"end":9.2,"start":8.8,"text":"little"},{"end":9.52,"start":9.2,"text":"things"},{"end":9.68,"start":9.52,"text":"you"},{"end":10.0,"start":9.68,"text":"used"},{"end":10.08,"start":10.0,"text":"to"},{"end":10.64,"start":10.08,"text":"say"},{"end":10.96,"start":10.64,"text":"How"},{"end":11.12,"start":10.96,"text":"have"},{"end":11.36,"start":11.12,"text":"you"},{"end":11.92,"start":11.36,"text":"been"},{"end":12.24,"start":12.0,"text":"Ive"},{"end":12.48,"start":12.24,"text":"thought"},{"end":12.8,"start":12.48,"text":"about"},{"end":13.2,"start":12.8,"text":"calling"},{"end":13.36,"start":13.2,"text":"you"},{"end":13.68,"start":13.36,"text":"so"},{"end":13.92,"start":13.68,"text":"many"},{"end":14.56,"start":13.92,"text":"times"},{"end":14.72,"start":14.56,"text":"but"},{"end":14.88,"start":14.72,"text":"I"},{"end":15.2,"start":14.88,"text":"never"},{"end":15.36,"start":15.2,"text":"knew"},{"end":15.6,"start":15.36,"text":"where"},{"end":15.6,"start":15.6,"text":"to"},{"end":16.24,"start":15.68,"text":"start"}]},"audio_base64":"//uSxOAAF...","chunk_audio_offset_sec":0.0,"chunk_seq":0,"content":"I can’t believe it’s been this long. It feels like forever since we last really talked. I’ve missed hearing your voice, your stories, even the little things you used to say. How have you been? I’ve thought about calling you so many times, but I never knew where to start."},{"alignment":{"audio_duration":10.48,"segments":[{"end":0.8,"start":0.4,"text":"Seeing"},{"end":0.96,"start":0.8,"text":"you"},{"end":1.44,"start":0.96,"text":"again"},{"end":1.68,"start":1.44,"text":"now"},{"end":2.08,"start":1.68,"text":"makes"},{"end":2.24,"start":2.08,"text":"me"},{"end":2.8,"start":2.24,"text":"realize"},{"end":3.12,"start":2.8,"text":"just"},{"end":3.28,"start":3.12,"text":"how"},{"end":3.6,"start":3.28,"text":"much"},{"end":3.76,"start":3.6,"text":"Ive"},{"end":4.24,"start":3.84,"text":"missed"},{"end":4.56,"start":4.24,"text":"you"},{"end":4.8,"start":4.64,"text":"We"},{"end":5.04,"start":4.8,"text":"have"},{"end":5.36,"start":5.04,"text":"so"},{"end":5.76,"start":5.36,"text":"much"},{"end":5.76,"start":5.76,"text":"to"},{"end":6.16,"start":5.76,"text":"catch"},{"end":6.4,"start":6.16,"text":"up"},{"end":6.72,"start":6.4,"text":"on"},{"end":6.96,"start":6.8,"text":"and"},{"end":7.04,"start":6.96,"text":"I"},{"end":7.36,"start":7.04,"text":"dont"},{"end":7.6,"start":7.36,"text":"even"},{"end":7.84,"start":7.6,"text":"know"},{"end":8.08,"start":7.84,"text":"which"},{"end":8.4,"start":8.08,"text":"part"},{"end":8.48,"start":8.4,"text":"of"},{"end":8.72,"start":8.56,"text":"my"},{"end":8.96,"start":8.72,"text":"life"},{"end":9.12,"start":9.12,"text":"to"},{"end":9.44,"start":9.12,"text":"tell"},{"end":9.6,"start":9.44,"text":"you"},{"end":10.0,"start":9.6,"text":"about"},{"end":10.48,"start":10.08,"text":"first"}]},"audio_base64":"//uSxImAl...","chunk_audio_offset_sec":16.24,"chunk_seq":1,"content":"Seeing you again now makes me realize just how much I’ve missed you. We have so much to catch up on, and I don’t even know which part of my life to tell you about first."}],"properties":{"audio_base64":{"description":"Base64 encoded audio chunk. Concatenate every chunk in event order to reconstruct the full audio.","title":"Audio Base64","type":"string"},"content":{"description":"Text content described by this event's latest alignment snapshot. Long input may be split into multiple content chunks in one stream.","title":"Content","type":"string"},"alignment":{"anyOf":[{"$ref":"#/components/schemas/TTSTimestampAlignment"},{"type":"null"}],"description":"Latest cumulative timestamp snapshot for `chunk_seq`. When present, replace the previous alignment for the same `chunk_seq`; do not append segments. Null means no alignment snapshot has been produced yet or alignment is unavailable."},"chunk_seq":{"description":"Sequence number of the text chunk described by `alignment`. Clients should bucket alignment snapshots by this value.","minimum":0,"title":"Chunk Seq","type":"integer"},"chunk_audio_offset_sec":{"description":"Absolute start time of this text chunk within the full audio, in seconds.","minimum":0.0,"title":"Chunk Audio Offset Sec","type":"number"}},"required":["audio_base64","content","alignment","chunk_seq","chunk_audio_offset_sec"],"title":"TTSTimestampStreamEvent","type":"object"},"examples":{"first_event":{"summary":"First text chunk event with alignment","value":"data: {\"audio_base64\": \"SUQzBAAAAAAA...\", \"content\": \"I can’t believe it’s been this long. It feels like forever since we last really talked. I’ve missed hearing your voice, your stories, even the little things you used to say. How have you been? I’ve thought about calling you so many times, but I never knew where to start.\", \"alignment\": {\"segments\": [{\"text\": \"I\", \"start\": 0.0, \"end\": 0.16}, {\"text\": \"can't\", \"start\": 0.16, \"end\": 0.48}, {\"text\": \"believe\", \"start\": 0.48, \"end\": 0.8}, {\"text\": \"its\", \"start\": 0.8, \"end\": 1.12}, {\"text\": \"been\", \"start\": 1.2, \"end\": 1.44}, {\"text\": \"this\", \"start\": 1.44, \"end\": 1.76}, {\"text\": \"long\", \"start\": 1.76, \"end\": 2.48}, {\"text\": \"It\", \"start\": 2.56, \"end\": 2.64}, {\"text\": \"feels\", \"start\": 2.72, \"end\": 3.04}, {\"text\": \"like\", \"start\": 3.12, \"end\": 3.28}, {\"text\": \"forever\", \"start\": 3.36, \"end\": 4.0}, {\"text\": \"since\", \"start\": 4.0, \"end\": 4.32}, {\"text\": \"we\", \"start\": 4.32, \"end\": 4.48}, {\"text\": \"last\", \"start\": 4.48, \"end\": 4.96}, {\"text\": \"really\", \"start\": 4.96, \"end\": 5.28}, {\"text\": \"talked\", \"start\": 5.28, \"end\": 5.84}, {\"text\": \"Ive\", \"start\": 6.0, \"end\": 6.24}, {\"text\": \"missed\", \"start\": 6.24, \"end\": 6.64}, {\"text\": \"hearing\", \"start\": 6.64, \"end\": 6.96}, {\"text\": \"your\", \"start\": 6.96, \"end\": 7.2}, {\"text\": \"voice\", \"start\": 7.2, \"end\": 7.76}, {\"text\": \"your\", \"start\": 7.76, \"end\": 7.92}, {\"text\": \"stories\", \"start\": 7.92, \"end\": 8.48}, {\"text\": \"even\", \"start\": 8.48, \"end\": 8.72}, {\"text\": \"the\", \"start\": 8.72, \"end\": 8.8}, {\"text\": \"little\", \"start\": 8.8, \"end\": 9.2}, {\"text\": \"things\", \"start\": 9.2, \"end\": 9.52}, {\"text\": \"you\", \"start\": 9.52, \"end\": 9.68}, {\"text\": \"used\", \"start\": 9.68, \"end\": 10.0}, {\"text\": \"to\", \"start\": 10.0, \"end\": 10.08}, {\"text\": \"say\", \"start\": 10.08, \"end\": 10.64}, {\"text\": \"How\", \"start\": 10.64, \"end\": 10.96}, {\"text\": \"have\", \"start\": 10.96, \"end\": 11.12}, {\"text\": \"you\", \"start\": 11.12, \"end\": 11.36}, {\"text\": \"been\", \"start\": 11.36, \"end\": 11.92}, {\"text\": \"Ive\", \"start\": 12.0, \"end\": 12.24}, {\"text\": \"thought\", \"start\": 12.24, \"end\": 12.48}, {\"text\": \"about\", \"start\": 12.48, \"end\": 12.8}, {\"text\": \"calling\", \"start\": 12.8, \"end\": 13.2}, {\"text\": \"you\", \"start\": 13.2, \"end\": 13.36}, {\"text\": \"so\", \"start\": 13.36, \"end\": 13.68}, {\"text\": \"many\", \"start\": 13.68, \"end\": 13.92}, {\"text\": \"times\", \"start\": 13.92, \"end\": 14.56}, {\"text\": \"but\", \"start\": 14.56, \"end\": 14.72}, {\"text\": \"I\", \"start\": 14.72, \"end\": 14.88}, {\"text\": \"never\", \"start\": 14.88, \"end\": 15.2}, {\"text\": \"knew\", \"start\": 15.2, \"end\": 15.36}, {\"text\": \"where\", \"start\": 15.36, \"end\": 15.6}, {\"text\": \"to\", \"start\": 15.6, \"end\": 15.6}, {\"text\": \"start\", \"start\": 15.68, \"end\": 16.24}], \"audio_duration\": 16.24}, \"chunk_seq\": 0, \"chunk_audio_offset_sec\": 0.0}\n\n"},"following_event":{"summary":"Following audio event with latest alignment snapshot","value":"data: {\"audio_base64\": \"//uSxOAAF...\", \"content\": \"I can’t believe it’s been this long. It feels like forever since we last really talked. I’ve missed hearing your voice, your stories, even the little things you used to say. How have you been? I’ve thought about calling you so many times, but I never knew where to start.\", \"alignment\": {\"segments\": [{\"text\": \"I\", \"start\": 0.0, \"end\": 0.16}, {\"text\": \"can't\", \"start\": 0.16, \"end\": 0.48}, {\"text\": \"believe\", \"start\": 0.48, \"end\": 0.8}, {\"text\": \"its\", \"start\": 0.8, \"end\": 1.12}, {\"text\": \"been\", \"start\": 1.2, \"end\": 1.44}, {\"text\": \"this\", \"start\": 1.44, \"end\": 1.76}, {\"text\": \"long\", \"start\": 1.76, \"end\": 2.48}, {\"text\": \"It\", \"start\": 2.56, \"end\": 2.64}, {\"text\": \"feels\", \"start\": 2.72, \"end\": 3.04}, {\"text\": \"like\", \"start\": 3.12, \"end\": 3.28}, {\"text\": \"forever\", \"start\": 3.36, \"end\": 4.0}, {\"text\": \"since\", \"start\": 4.0, \"end\": 4.32}, {\"text\": \"we\", \"start\": 4.32, \"end\": 4.48}, {\"text\": \"last\", \"start\": 4.48, \"end\": 4.96}, {\"text\": \"really\", \"start\": 4.96, \"end\": 5.28}, {\"text\": \"talked\", \"start\": 5.28, \"end\": 5.84}, {\"text\": \"Ive\", \"start\": 6.0, \"end\": 6.24}, {\"text\": \"missed\", \"start\": 6.24, \"end\": 6.64}, {\"text\": \"hearing\", \"start\": 6.64, \"end\": 6.96}, {\"text\": \"your\", \"start\": 6.96, \"end\": 7.2}, {\"text\": \"voice\", \"start\": 7.2, \"end\": 7.76}, {\"text\": \"your\", \"start\": 7.76, \"end\": 7.92}, {\"text\": \"stories\", \"start\": 7.92, \"end\": 8.48}, {\"text\": \"even\", \"start\": 8.48, \"end\": 8.72}, {\"text\": \"the\", \"start\": 8.72, \"end\": 8.8}, {\"text\": \"little\", \"start\": 8.8, \"end\": 9.2}, {\"text\": \"things\", \"start\": 9.2, \"end\": 9.52}, {\"text\": \"you\", \"start\": 9.52, \"end\": 9.68}, {\"text\": \"used\", \"start\": 9.68, \"end\": 10.0}, {\"text\": \"to\", \"start\": 10.0, \"end\": 10.08}, {\"text\": \"say\", \"start\": 10.08, \"end\": 10.64}, {\"text\": \"How\", \"start\": 10.64, \"end\": 10.96}, {\"text\": \"have\", \"start\": 10.96, \"end\": 11.12}, {\"text\": \"you\", \"start\": 11.12, \"end\": 11.36}, {\"text\": \"been\", \"start\": 11.36, \"end\": 11.92}, {\"text\": \"Ive\", \"start\": 12.0, \"end\": 12.24}, {\"text\": \"thought\", \"start\": 12.24, \"end\": 12.48}, {\"text\": \"about\", \"start\": 12.48, \"end\": 12.8}, {\"text\": \"calling\", \"start\": 12.8, \"end\": 13.2}, {\"text\": \"you\", \"start\": 13.2, \"end\": 13.36}, {\"text\": \"so\", \"start\": 13.36, \"end\": 13.68}, {\"text\": \"many\", \"start\": 13.68, \"end\": 13.92}, {\"text\": \"times\", \"start\": 13.92, \"end\": 14.56}, {\"text\": \"but\", \"start\": 14.56, \"end\": 14.72}, {\"text\": \"I\", \"start\": 14.72, \"end\": 14.88}, {\"text\": \"never\", \"start\": 14.88, \"end\": 15.2}, {\"text\": \"knew\", \"start\": 15.2, \"end\": 15.36}, {\"text\": \"where\", \"start\": 15.36, \"end\": 15.6}, {\"text\": \"to\", \"start\": 15.6, \"end\": 15.6}, {\"text\": \"start\", \"start\": 15.68, \"end\": 16.24}], \"audio_duration\": 16.24}, \"chunk_seq\": 0, \"chunk_audio_offset_sec\": 0.0}\n\n"},"later_text_chunk_event":{"summary":"Later text chunk event with another alignment","value":"data: {\"audio_base64\": \"//uSxImAl...\", \"content\": \"Seeing you again now makes me realize just how much I’ve missed you. We have so much to catch up on, and I don’t even know which part of my life to tell you about first.\", \"alignment\": {\"segments\": [{\"text\": \"Seeing\", \"start\": 0.4, \"end\": 0.8}, {\"text\": \"you\", \"start\": 0.8, \"end\": 0.96}, {\"text\": \"again\", \"start\": 0.96, \"end\": 1.44}, {\"text\": \"now\", \"start\": 1.44, \"end\": 1.68}, {\"text\": \"makes\", \"start\": 1.68, \"end\": 2.08}, {\"text\": \"me\", \"start\": 2.08, \"end\": 2.24}, {\"text\": \"realize\", \"start\": 2.24, \"end\": 2.8}, {\"text\": \"just\", \"start\": 2.8, \"end\": 3.12}, {\"text\": \"how\", \"start\": 3.12, \"end\": 3.28}, {\"text\": \"much\", \"start\": 3.28, \"end\": 3.6}, {\"text\": \"Ive\", \"start\": 3.6, \"end\": 3.76}, {\"text\": \"missed\", \"start\": 3.84, \"end\": 4.24}, {\"text\": \"you\", \"start\": 4.24, \"end\": 4.56}, {\"text\": \"We\", \"start\": 4.64, \"end\": 4.8}, {\"text\": \"have\", \"start\": 4.8, \"end\": 5.04}, {\"text\": \"so\", \"start\": 5.04, \"end\": 5.36}, {\"text\": \"much\", \"start\": 5.36, \"end\": 5.76}, {\"text\": \"to\", \"start\": 5.76, \"end\": 5.76}, {\"text\": \"catch\", \"start\": 5.76, \"end\": 6.16}, {\"text\": \"up\", \"start\": 6.16, \"end\": 6.4}, {\"text\": \"on\", \"start\": 6.4, \"end\": 6.72}, {\"text\": \"and\", \"start\": 6.8, \"end\": 6.96}, {\"text\": \"I\", \"start\": 6.96, \"end\": 7.04}, {\"text\": \"dont\", \"start\": 7.04, \"end\": 7.36}, {\"text\": \"even\", \"start\": 7.36, \"end\": 7.6}, {\"text\": \"know\", \"start\": 7.6, \"end\": 7.84}, {\"text\": \"which\", \"start\": 7.84, \"end\": 8.08}, {\"text\": \"part\", \"start\": 8.08, \"end\": 8.4}, {\"text\": \"of\", \"start\": 8.4, \"end\": 8.48}, {\"text\": \"my\", \"start\": 8.56, \"end\": 8.72}, {\"text\": \"life\", \"start\": 8.72, \"end\": 8.96}, {\"text\": \"to\", \"start\": 9.12, \"end\": 9.12}, {\"text\": \"tell\", \"start\": 9.12, \"end\": 9.44}, {\"text\": \"you\", \"start\": 9.44, \"end\": 9.6}, {\"text\": \"about\", \"start\": 9.6, \"end\": 10.0}, {\"text\": \"first\", \"start\": 10.08, \"end\": 10.48}], \"audio_duration\": 10.48}, \"chunk_seq\": 1, \"chunk_audio_offset_sec\": 16.24}\n\n"}}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["OpenAPI v1"],"x-codeSamples":[{"lang":"bash","label":"Stream With Timestamps","source":"curl --no-buffer --request POST \\\n  --url https://api.fish.audio/v1/tts/stream/with-timestamp \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --header 'model: s2.1-pro-free' \\\n  --data '{\n    \"text\": \"[happy] I can’t believe it’s been this long. It feels like forever since we last really talked. I’ve missed hearing your voice, your stories, even the little things you used to say. How have you been? I’ve thought about calling you so many times, but I never knew where to start. Seeing you again now makes me realize just how much I’ve missed you. We have so much to catch up on, and I don’t even know which part of my life to tell you about first.\",\n    \"format\": \"opus\",\n    \"normalize\": true,\n    \"temperature\": 0.9,\n    \"chunk_length\": 100,\n    \"top_p\": 0.9,\n    \"latency\": \"balanced\",\n    \"sample_rate\": 48000,\n    \"reference_id\": \"fbe02f8306fc4d3d915e9871722a39d5\"\n  }'"}]}},"/v1/tts/live/with-timestamp":{"get":{"summary":"Text to Speech Live with Timestamps (WebSocket)","description":"Streaming text-to-speech over a WebSocket that returns word-level timestamps\nalongside the audio. Connect to `wss://api.fish.audio/v1/tts/live/with-timestamp`;\nthis is a WebSocket upgrade, not a plain HTTP request.\n\nUse it when you need to feed text in as it is produced — an LLM token stream,\na live caption feed — and want word timings for lip-sync, subtitles or\nhighlighting. For a one-shot request use `POST /v1/tts/stream/with-timestamp`\ninstead.\n\n## Handshake\n\nSend the same headers as any other API call:\n\n- `Authorization: Bearer <your-api-key>`\n- `model: <model>` — optional, defaults to `s2.1-pro`.\n\n## Framing\n\nEvery frame in both directions is a MessagePack-encoded **binary** frame\nholding a map with an `event` key. Text frames are ignored by the server and\nshould be ignored by your client.\n\n## Client to server\n\nThe inbound protocol is identical to `/v1/tts/live`:\n\n- `start` — opens the session. Send it once per session, before any other\n  event. Carries a `request` object with the same fields as the\n  `POST /v1/tts` body; leave `text` empty and stream the words with `text`\n  events. After a `finish` you may send another `start` to run a new session\n  on the same socket.\n- `text` — appends a text fragment to the session buffer.\n- `flush` — forces buffered text through generation without waiting for the\n  chunk to fill. The session stays open.\n- `stop` — ends the session. The server drains the buffer and answers with a\n  final `finish` event.\n\n## Server to client\n\n- `audio` — one audio chunk. Beyond the `audio` bytes it carries `content`,\n  `alignment`, `chunk_seq` and `chunk_audio_offset_sec`; these last three are\n  what this endpoint adds over `/v1/tts/live`. Concatenate every `audio`\n  payload in arrival order to reconstruct the full audio. Note that `audio`\n  here is raw MessagePack `bin`, not the base64 string used by the SSE\n  endpoint.\n- `finish` — terminal event, with `reason` of `stop` or `error`.\n- `error` — a request-level failure such as an invalid `start` request or a\n  concurrency refusal; the socket closes afterwards.\n\n## Reading the alignment\n\n`alignment` is a **cumulative snapshot** for its `chunk_seq`, not a delta:\nwhen it is non-null, replace the alignment you stored for that chunk rather\nthan appending to it. A `null` alignment means nothing new has been committed\nfor the chunk yet, which is normal early on.\n\nSegment times inside `alignment` are relative to the start of their chunk.\n`chunk_audio_offset_sec` is the chunk's own start time within the full audio,\nso the absolute time of a word is `chunk_audio_offset_sec + segment.start`.\nBoth `chunk_seq` and `chunk_audio_offset_sec` are monotonically\nnon-decreasing. A frame may be labelled with the previous chunk's\n`chunk_seq` while carrying the next chunk's audio bytes, so never use\n`chunk_seq` to attribute audio bytes — only alignment.","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"model","description":"Specify which TTS model to use. Use `s2.1-pro-free` for the free developer tier. `drama-3-preview` is a preview model; its behavior and availability may change. If omitted or set to an unrecognized value, the request falls back to `s2.1-pro`.","required":false,"schema":{"default":"s2.1-pro","enum":["s1","s2-pro","s2.1-pro","s2.1-pro-free","drama-3-preview"],"title":"Model","type":"string"},"deprecated":false}],"responses":{"200":{"description":"WebSocket handshake accepted (the server answers `101 Switching Protocols` on the wire). Every frame the server then sends is a MessagePack-encoded binary frame holding one of the events below. `audio` events carry the audio chunk together with `alignment`, `chunk_seq` and `chunk_audio_offset_sec`; `alignment` is the cumulative snapshot for its `chunk_seq` and replaces the previous one rather than extending it. Segment times are relative to the chunk, so absolute time is `chunk_audio_offset_sec + segment.start`. The stream ends with a `finish` event.","content":{"application/msgpack":{"schema":{"discriminator":{"mapping":{"audio":"#/components/schemas/TTSLiveWithTimestampAudioEvent","error":"#/components/schemas/TTSLiveErrorEvent","finish":"#/components/schemas/TTSLiveFinishEvent"},"propertyName":"event"},"oneOf":[{"$ref":"#/components/schemas/TTSLiveWithTimestampAudioEvent"},{"$ref":"#/components/schemas/TTSLiveFinishEvent"},{"$ref":"#/components/schemas/TTSLiveErrorEvent"}]}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["OpenAPI v1"],"x-codeSamples":[{"lang":"python","label":"Live WebSocket With Timestamps","source":"import asyncio\n\nimport ormsgpack\nimport websockets\n\nTEXT = \"Hello there. This is a live synthesis, streamed word by word.\"\n\n\nasync def send_text(socket) -> None:\n    # `request` takes the same fields as POST /v1/tts. Leave `text` empty and\n    # stream the words in as they become available.\n    await socket.send(\n        ormsgpack.packb(\n            {\n                \"event\": \"start\",\n                \"request\": {\n                    \"text\": \"\",\n                    \"format\": \"opus\",\n                    \"latency\": \"balanced\",\n                    \"chunk_length\": 100,\n                    \"reference_id\": \"fbe02f8306fc4d3d915e9871722a39d5\",\n                },\n            }\n        )\n    )\n    for word in TEXT.split(\" \"):\n        await socket.send(ormsgpack.packb({\"event\": \"text\", \"text\": word + \" \"}))\n    await socket.send(ormsgpack.packb({\"event\": \"stop\"}))\n\n\nasync def main() -> None:\n    async with websockets.connect(\n        \"wss://api.fish.audio/v1/tts/live/with-timestamp\",\n        additional_headers={\n            \"Authorization\": \"Bearer <token>\",\n            \"model\": \"s2.1-pro-free\",\n        },\n        max_size=None,\n    ) as socket:\n        # Send and receive concurrently. Sending everything before reading can\n        # stall on flow control once the audio outpaces your receive buffer.\n        sender = asyncio.create_task(send_text(socket))\n\n        audio = bytearray()\n        alignments: dict[int, dict] = {}\n        offsets: dict[int, float] = {}\n\n        try:\n            async for frame in socket:\n                if isinstance(frame, str):\n                    continue\n                message = ormsgpack.unpackb(frame)\n                if message[\"event\"] == \"audio\":\n                    audio += message[\"audio\"]\n                    offsets[message[\"chunk_seq\"]] = message[\"chunk_audio_offset_sec\"]\n                    if message[\"alignment\"] is not None:\n                        # Cumulative snapshot: replace the chunk, never append.\n                        alignments[message[\"chunk_seq\"]] = message[\"alignment\"]\n                elif message[\"event\"] == \"finish\":\n                    if message[\"reason\"] == \"error\":\n                        raise RuntimeError(message.get(\"message\", \"synthesis failed\"))\n                    break\n                elif message[\"event\"] == \"error\":\n                    raise RuntimeError(message[\"error\"])\n        finally:\n            sender.cancel()\n\n        with open(\"output.opus\", \"wb\") as f:\n            f.write(audio)\n\n        # Segment times are chunk-relative; fold in the offset to get absolute.\n        for chunk_seq in sorted(alignments):\n            offset = offsets[chunk_seq]\n            for segment in alignments[chunk_seq][\"segments\"]:\n                start = offset + segment[\"start\"]\n                end = offset + segment[\"end\"]\n                print(f\"{start:6.2f}s -> {end:6.2f}s  {segment['text']}\")\n\n\nasyncio.run(main())"}],"x-fish-websocket":{"url":"wss://api.fish.audio/v1/tts/live/with-timestamp","encoding":"application/msgpack","clientEvents":{"description":"Frames the client sends, MessagePack encoded. Identical to the `/v1/tts/live` inbound protocol: `start` once, then any number of `text` events, optional `flush` events, and a final `stop`.","schema":{"discriminator":{"mapping":{"flush":"#/components/schemas/TTSLiveFlushEvent","start":"#/components/schemas/TTSLiveStartEvent","stop":"#/components/schemas/TTSLiveStopEvent","text":"#/components/schemas/TTSLiveTextEvent"},"propertyName":"event"},"oneOf":[{"$ref":"#/components/schemas/TTSLiveStartEvent"},{"$ref":"#/components/schemas/TTSLiveTextEvent"},{"$ref":"#/components/schemas/TTSLiveFlushEvent"},{"$ref":"#/components/schemas/TTSLiveStopEvent"}]}}}}},"/v1/voice-design":{"post":{"summary":"Voice Design","security":[{"BearerAuth":[]}],"parameters":[{"in":"header","name":"model","description":"Specify which voice-design model to use.","required":true,"schema":{"const":"voice-design-1","default":"voice-design-1","title":"Model","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceDesignRequest"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"candidates":{"description":"Generated voice candidates.","items":{"$ref":"#/components/schemas/VoiceDesignCandidate"},"title":"Candidates","type":"array"}},"required":["candidates"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"402":{"description":"No payment -- see charging schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["OpenAPI v1"],"x-codeSamples":[{"lang":"bash","label":"Voice Design","source":"curl --request POST \\\n  --url https://api.fish.audio/v1/voice-design \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --header 'model: voice-design-1' \\\n  --data '{\n    \"instruction\": \"Warm, confident studio narrator with a natural tone\",\n    \"reference_text\": \"Welcome to Fish Audio.\",\n    \"language\": \"en\",\n    \"n\": 2,\n    \"speed\": 1,\n    \"num_step\": 32,\n    \"guidance_scale\": 2,\n    \"instruct_guidance_scale\": 0,\n    \"seed\": 42\n  }'"}]}},"/model":{"get":{"summary":"List Models","security":[{"BearerAuth":[]}],"parameters":[{"in":"query","name":"page_size","description":"Page size","required":false,"schema":{"default":10,"maximum":100,"minimum":1,"title":"Page Size","type":"integer"},"deprecated":false},{"in":"query","name":"page_number","description":"Page number","required":false,"schema":{"default":1,"minimum":1,"title":"Page Number","type":"integer"},"deprecated":false},{"in":"query","name":"title","description":"Title to filter models","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"deprecated":false},{"in":"query","name":"tag","description":"Tag to filter models","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"title":"Tag"},"deprecated":false},{"in":"query","name":"self","description":"If True, return models owned by the active workspace","required":false,"schema":{"default":false,"title":"Self","type":"boolean"},"deprecated":false},{"in":"query","name":"author_id","description":"Author ID to filter public models; ignored if self is True","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Author Id"},"deprecated":false},{"in":"query","name":"language","description":"Language to filter models","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"title":"Language"},"deprecated":false},{"in":"query","name":"title_language","description":"Title language to filter models","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"title":"Title Language"},"deprecated":false},{"in":"query","name":"licensed","description":"If True, only voices licensed by Fish Audio (rights secured from the voice owner) are returned; ignored if self is True","required":false,"schema":{"default":false,"title":"Licensed","type":"boolean"},"deprecated":false},{"in":"query","name":"sort_by","description":"","required":false,"schema":{"default":"score","enum":["score","task_count","created_at"],"title":"Sort By","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"max_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Offset"},"accessible_upper_bound":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Accessible Upper Bound"},"window_limited":{"default":false,"title":"Window Limited","type":"boolean"},"total_is_exact":{"default":true,"title":"Total Is Exact","type":"boolean"},"total":{"title":"Total","type":"integer"},"items":{"items":{"$ref":"#/components/schemas/ModelEntity"},"title":"Items","type":"array"},"has_more":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Has More"}},"required":["total","items"],"type":"object"}}}}},"tags":["Model"]},"post":{"summary":"Create Model for Users via API","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"visibility":{"default":"private","description":"Model visibility. Public requests are downgraded to private; use the web publish flow to publish publicly. Unlist allows anyone with the link to access, while private is visible only to the creator.","enum":["public","unlist","private"],"title":"Visibility","type":"string"},"type":{"const":"tts","description":"Model type, tts is for text to speech","title":"Type","type":"string"},"title":{"description":"Model title or name","title":"Title","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Model description","title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"description":"Model cover image, this is required if the model is public","title":"Cover Image"},"train_mode":{"const":"fast","description":"Model train mode, for TTS model, fast means model instantly available after creation","title":"Train Mode","type":"string"},"voices":{"anyOf":[{"items":{"format":"binary","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"format":"binary","type":"string"}],"description":"Upload voices files that will be used to tune the model","title":"Voices"},"texts":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Texts corresponding to the voices, if unspecified, ASR will be performed on the voices","title":"Texts"},"voice_design_signatures":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Signatures from /v1/voice-design candidates, one per voice in the same order. When every uploaded voice verifies, the model is stamped source=voice_design; an invalid signature rejects the request.","title":"Voice Design Signatures"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"description":"Model tags","title":"Tags"},"enhance_audio_quality":{"default":true,"description":"Enhance audio quality","title":"Enhance Audio Quality","type":"boolean"},"generate_sample":{"default":false,"description":"Generate default text","title":"Generate Sample","type":"boolean"}},"required":["type","title","train_mode","voices"],"type":"object"}},"application/x-www-form-urlencoded":{"schema":{"properties":{"visibility":{"default":"private","description":"Model visibility. Public requests are downgraded to private; use the web publish flow to publish publicly. Unlist allows anyone with the link to access, while private is visible only to the creator.","enum":["public","unlist","private"],"title":"Visibility","type":"string"},"type":{"const":"tts","description":"Model type, tts is for text to speech","title":"Type","type":"string"},"title":{"description":"Model title or name","title":"Title","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Model description","title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"description":"Model cover image, this is required if the model is public","title":"Cover Image"},"train_mode":{"const":"fast","description":"Model train mode, for TTS model, fast means model instantly available after creation","title":"Train Mode","type":"string"},"voices":{"anyOf":[{"items":{"format":"binary","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"format":"binary","type":"string"}],"description":"Upload voices files that will be used to tune the model","title":"Voices"},"texts":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Texts corresponding to the voices, if unspecified, ASR will be performed on the voices","title":"Texts"},"voice_design_signatures":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Signatures from /v1/voice-design candidates, one per voice in the same order. When every uploaded voice verifies, the model is stamped source=voice_design; an invalid signature rejects the request.","title":"Voice Design Signatures"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"description":"Model tags","title":"Tags"},"enhance_audio_quality":{"default":true,"description":"Enhance audio quality","title":"Enhance Audio Quality","type":"boolean"},"generate_sample":{"default":false,"description":"Generate default text","title":"Generate Sample","type":"boolean"}},"required":["type","title","train_mode","voices"],"type":"object"}},"multipart/form-data":{"schema":{"properties":{"visibility":{"default":"private","description":"Model visibility. Public requests are downgraded to private; use the web publish flow to publish publicly. Unlist allows anyone with the link to access, while private is visible only to the creator.","enum":["public","unlist","private"],"title":"Visibility","type":"string"},"type":{"const":"tts","description":"Model type, tts is for text to speech","title":"Type","type":"string"},"title":{"description":"Model title or name","title":"Title","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Model description","title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"description":"Model cover image, this is required if the model is public","title":"Cover Image"},"train_mode":{"const":"fast","description":"Model train mode, for TTS model, fast means model instantly available after creation","title":"Train Mode","type":"string"},"voices":{"anyOf":[{"items":{"format":"binary","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"format":"binary","type":"string"}],"description":"Upload voices files that will be used to tune the model","title":"Voices"},"texts":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Texts corresponding to the voices, if unspecified, ASR will be performed on the voices","title":"Texts"},"voice_design_signatures":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Signatures from /v1/voice-design candidates, one per voice in the same order. When every uploaded voice verifies, the model is stamped source=voice_design; an invalid signature rejects the request.","title":"Voice Design Signatures"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"description":"Model tags","title":"Tags"},"enhance_audio_quality":{"default":true,"description":"Enhance audio quality","title":"Enhance Audio Quality","type":"boolean"},"generate_sample":{"default":false,"description":"Generate default text","title":"Generate Sample","type":"boolean"}},"required":["type","title","train_mode","voices"],"type":"object"}},"application/msgpack":{"schema":{"properties":{"visibility":{"default":"private","description":"Model visibility. Public requests are downgraded to private; use the web publish flow to publish publicly. Unlist allows anyone with the link to access, while private is visible only to the creator.","enum":["public","unlist","private"],"title":"Visibility","type":"string"},"type":{"const":"tts","description":"Model type, tts is for text to speech","title":"Type","type":"string"},"title":{"description":"Model title or name","title":"Title","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Model description","title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"description":"Model cover image, this is required if the model is public","title":"Cover Image"},"train_mode":{"const":"fast","description":"Model train mode, for TTS model, fast means model instantly available after creation","title":"Train Mode","type":"string"},"voices":{"anyOf":[{"items":{"format":"binary","type":"string"},"maxItems":20,"minItems":1,"type":"array"},{"format":"binary","type":"string"}],"description":"Upload voices files that will be used to tune the model","title":"Voices"},"texts":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Texts corresponding to the voices, if unspecified, ASR will be performed on the voices","title":"Texts"},"voice_design_signatures":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Signatures from /v1/voice-design candidates, one per voice in the same order. When every uploaded voice verifies, the model is stamped source=voice_design; an invalid signature rejects the request.","title":"Voice Design Signatures"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"description":"Model tags","title":"Tags"},"enhance_audio_quality":{"default":true,"description":"Enhance audio quality","title":"Enhance Audio Quality","type":"boolean"},"generate_sample":{"default":false,"description":"Generate default text","title":"Generate Sample","type":"boolean"}},"required":["type","title","train_mode","voices"],"type":"object"}}}},"responses":{"201":{"description":"Document created, URL follows","headers":{},"content":{"application/json":{"schema":{"properties":{"_id":{"title":"Id","type":"string"},"type":{"enum":["svc","tts"],"title":"Type","type":"string"},"title":{"title":"Title","type":"string"},"description":{"default":"","title":"Description","type":"string"},"cover_image":{"default":"","title":"Cover Image","type":"string"},"train_mode":{"default":"full","enum":["fast","full"],"title":"Train Mode","type":"string"},"state":{"enum":["created","training","trained","failed"],"title":"State","type":"string"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"},"samples":{"default":[],"items":{"$ref":"#/components/schemas/SampleEntity"},"title":"Samples","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"languages":{"default":[],"items":{"type":"string"},"title":"Languages","type":"array"},"visibility":{"enum":["public","unlist","private"],"title":"Visibility","type":"string"},"lock_visibility":{"default":false,"title":"Lock Visibility","type":"boolean"},"dmca_taken_down":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Dmca Taken Down"},"takedown_category":{"anyOf":[{"enum":["dmca","policy"],"type":"string"},{"type":"null"}],"default":null,"title":"Takedown Category"},"default_text":{"default":"","title":"Default Text","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"licensed":{"default":false,"title":"Licensed","type":"boolean"},"pvc_release_state":{"anyOf":[{"enum":["released","retiring"],"type":"string"},{"type":"null"}],"default":null,"title":"Pvc Release State"},"pvc_notice_period_months":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pvc Notice Period Months"},"pvc_released_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Released At"},"pvc_retire_requested_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Retire Requested At"},"pvc_retire_effective_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Retire Effective At"},"quality":{"anyOf":[{"$ref":"#/components/schemas/ModelQualityEntity"},{"type":"null"}],"default":null},"like_count":{"title":"Like Count","type":"integer"},"mark_count":{"title":"Mark Count","type":"integer"},"shared_count":{"title":"Shared Count","type":"integer"},"task_count":{"title":"Task Count","type":"integer"},"unliked":{"default":false,"title":"Unliked","type":"boolean"},"liked":{"default":false,"title":"Liked","type":"boolean"},"marked":{"default":false,"title":"Marked","type":"boolean"},"author":{"$ref":"#/components/schemas/AuthorEntity"}},"required":["_id","type","title","state","tags","created_at","updated_at","visibility","like_count","mark_count","shared_count","task_count","author"],"type":"object"}}}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Model"]}},"/model/{id}":{"get":{"summary":"Get Model","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"id","description":"","required":true,"schema":{"title":"Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{},"content":{"application/json":{"schema":{"properties":{"_id":{"title":"Id","type":"string"},"type":{"enum":["svc","tts"],"title":"Type","type":"string"},"title":{"title":"Title","type":"string"},"description":{"default":"","title":"Description","type":"string"},"cover_image":{"default":"","title":"Cover Image","type":"string"},"train_mode":{"default":"full","enum":["fast","full"],"title":"Train Mode","type":"string"},"state":{"enum":["created","training","trained","failed"],"title":"State","type":"string"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"},"samples":{"default":[],"items":{"$ref":"#/components/schemas/SampleEntity"},"title":"Samples","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"languages":{"default":[],"items":{"type":"string"},"title":"Languages","type":"array"},"visibility":{"enum":["public","unlist","private"],"title":"Visibility","type":"string"},"lock_visibility":{"default":false,"title":"Lock Visibility","type":"boolean"},"dmca_taken_down":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Dmca Taken Down"},"takedown_category":{"anyOf":[{"enum":["dmca","policy"],"type":"string"},{"type":"null"}],"default":null,"title":"Takedown Category"},"default_text":{"default":"","title":"Default Text","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"licensed":{"default":false,"title":"Licensed","type":"boolean"},"pvc_release_state":{"anyOf":[{"enum":["released","retiring"],"type":"string"},{"type":"null"}],"default":null,"title":"Pvc Release State"},"pvc_notice_period_months":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pvc Notice Period Months"},"pvc_released_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Released At"},"pvc_retire_requested_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Retire Requested At"},"pvc_retire_effective_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Retire Effective At"},"quality":{"anyOf":[{"$ref":"#/components/schemas/ModelQualityEntity"},{"type":"null"}],"default":null},"like_count":{"title":"Like Count","type":"integer"},"mark_count":{"title":"Mark Count","type":"integer"},"shared_count":{"title":"Shared Count","type":"integer"},"task_count":{"title":"Task Count","type":"integer"},"unliked":{"default":false,"title":"Unliked","type":"boolean"},"liked":{"default":false,"title":"Liked","type":"boolean"},"marked":{"default":false,"title":"Marked","type":"boolean"},"author":{"$ref":"#/components/schemas/AuthorEntity"}},"required":["_id","type","title","state","tags","created_at","updated_at","visibility","like_count","mark_count","shared_count","task_count","author"],"type":"object"}}}},"403":{"description":"Request forbidden -- authorization will not help","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"404":{"description":"Nothing matches the given URI","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Model"]},"patch":{"summary":"Update Model","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"id","description":"","required":true,"schema":{"title":"Id","type":"string"},"deprecated":false}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"title":"Cover Image"},"visibility":{"anyOf":[{"enum":["public","unlist","private"],"type":"string"},{"type":"null"}],"default":null,"title":"Visibility"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Tags"}},"type":"object"}},"application/x-www-form-urlencoded":{"schema":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"title":"Cover Image"},"visibility":{"anyOf":[{"enum":["public","unlist","private"],"type":"string"},{"type":"null"}],"default":null,"title":"Visibility"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Tags"}},"type":"object"}},"multipart/form-data":{"schema":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"title":"Cover Image"},"visibility":{"anyOf":[{"enum":["public","unlist","private"],"type":"string"},{"type":"null"}],"default":null,"title":"Visibility"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Tags"}},"type":"object"}},"application/msgpack":{"schema":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"cover_image":{"anyOf":[{"format":"binary","type":"string"},{"type":"null"}],"default":null,"title":"Cover Image"},"visibility":{"anyOf":[{"enum":["public","unlist","private"],"type":"string"},{"type":"null"}],"default":null,"title":"Visibility"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Tags"}},"type":"object"}}}},"responses":{"200":{"description":"Request fulfilled, document follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Model"]},"delete":{"summary":"Delete Model","security":[{"BearerAuth":[]}],"parameters":[{"in":"path","name":"id","description":"","required":true,"schema":{"title":"Id","type":"string"},"deprecated":false}],"responses":{"200":{"description":"Request fulfilled, document follows","headers":{}},"401":{"description":"No permission -- see authorization schemes","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}},"503":{"description":"The server cannot process the request due to a high load","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"}},"required":["status","message"],"type":"object"}}}}},"tags":["Model"]}}},"tags":[],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AgentSessionSummary":{"description":"One list row: lifecycle facts only — the conversation timeline lives on\nthe detail endpoint (Retell-style thin list).","properties":{"session_id":{"title":"Session Id","type":"string"},"agent_id":{"title":"Agent Id","type":"string"},"agent_name":{"title":"Agent Name","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"status":{"enum":["pending","active","completed","failed","unknown"],"title":"Status","type":"string"},"end_reason":{"anyOf":[{"enum":["user_hangup","agent_hangup","escalated","conversation_timeout","heartbeat_timeout","agent_join_timeout","internal_error","llm_endpoint_failure","room_join_timeout","cancelled","dial_failed"],"type":"string"},{"type":"null"}],"default":null,"title":"End Reason"},"source":{"enum":["api_key","dashboard","public","phone"],"title":"Source","type":"string"},"direction":{"default":"inbound","enum":["inbound","outbound"],"title":"Direction","type":"string"},"dial_status":{"anyOf":[{"enum":["answered","busy","no_answer","failed"],"type":"string"},{"type":"null"}],"default":null,"title":"Dial Status"},"answered_by":{"anyOf":[{"enum":["human","voicemail","unknown"],"type":"string"},{"type":"null"}],"default":null,"title":"Answered By"},"caller_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caller Number"},"dialed_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Dialed Number"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timezone"},"created_at":{"title":"Created At","type":"string"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Started At"},"ended_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ended At"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Duration Seconds"},"metadata":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"title":"Metadata","type":"object"}},"required":["session_id","agent_id","agent_name","status","source","created_at"],"title":"AgentSessionSummary","type":"object"},"JsonValue":{},"AgentSessionCreatePayload":{"additionalProperties":false,"properties":{"agent_id":{"title":"Agent Id","type":"string"},"name":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"timezone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"IANA timezone (like `Asia/Tokyo`) for the agent's sense of local date and time in this session. Overrides the agent's configured timezone, which defaults to UTC. Invalid names are rejected with 422.","title":"Timezone"},"client_timezone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"The end user's device timezone as an IANA name (like `Asia/Tokyo`), used as a fallback hint: it applies only when neither `timezone` nor the agent's configured timezone is set, and invalid values are ignored rather than rejected. The Web SDK fills it automatically from the browser for public agents. When your backend creates the session, forward the value from your client.","title":"Client Timezone"},"world_context":{"default":true,"title":"World Context","type":"boolean"},"overrides":{"anyOf":[{"$ref":"#/components/schemas/AgentSessionOverridesPayload"},{"type":"null"}],"default":null},"dynamic_variables":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"}]},"maxProperties":50,"type":"object"},{"type":"null"}],"default":null,"title":"Dynamic Variables"},"end_user_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"End User Id"},"metadata":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"default":null,"title":"Metadata"},"llm_extra_body":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"default":null,"title":"Llm Extra Body"},"tool_events":{"default":true,"title":"Tool Events","type":"boolean"},"record_audio":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Record Audio"}},"required":["agent_id"],"title":"AgentSessionCreatePayload","type":"object"},"AgentSessionOverridesPayload":{"additionalProperties":false,"description":"Wire twin of @fishaudio/agent-protocol `SessionOverrides` (session.ts).\n\nEvery field must be allow-listed in Agent.overrides_allowed; unauthorized\nfields fail session creation loudly rather than being silently dropped.","properties":{"first_message":{"anyOf":[{"maxLength":10000,"type":"string"},{"type":"null"}],"default":null,"title":"First Message"},"first_message_prompt":{"anyOf":[{"maxLength":10000,"type":"string"},{"type":"null"}],"default":null,"title":"First Message Prompt"},"system_prompt":{"anyOf":[{"maxLength":500000,"type":"string"},{"type":"null"}],"default":null,"description":"Limited to 32000 tokens (o200k_base), same budget as the configured prompt it replaces.","title":"System Prompt"},"voice_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Voice Id"},"language":{"anyOf":[{"enum":["en","ja","zh","ko","es","fr","de","pt","it","nl","ar","hi","id","tr","ru","bg","sr","hr","cs","sk","pl","uk","ro","hu","el","sv","da","no","fi","et","lv","lt","ca","he","fa","ur","kk","ka","hy","bn","ta","te","kn","mr","gu","pa","ne","th","vi","ms","tl","af"],"type":"string"},{"type":"null"}],"default":null,"title":"Language"}},"title":"AgentSessionOverridesPayload","type":"object"},"AgentSessionAnalysisCriterionResult":{"properties":{"name":{"title":"Name","type":"string"},"result":{"enum":["success","failure","unknown"],"title":"Result","type":"string"},"rationale":{"default":"","title":"Rationale","type":"string"}},"required":["name","result"],"title":"AgentSessionAnalysisCriterionResult","type":"object"},"AgentSessionAnalysisDataValue":{"properties":{"name":{"title":"Name","type":"string"},"type":{"enum":["boolean","text","number","enum"],"title":"Type","type":"string"},"value":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null,"title":"Value"},"rationale":{"default":"","title":"Rationale","type":"string"}},"required":["name","type"],"title":"AgentSessionAnalysisDataValue","type":"object"},"AgentSessionAnalysisResult":{"description":"Public trim of the post-call analysis record: outcomes only, no run\ninternals (model, tokens, config hash).","properties":{"status":{"enum":["queued","running","completed","skipped","error"],"title":"Status","type":"string"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Summary"},"data":{"items":{"$ref":"#/components/schemas/AgentSessionAnalysisDataValue"},"title":"Data","type":"array"},"criteria_results":{"items":{"$ref":"#/components/schemas/AgentSessionAnalysisCriterionResult"},"title":"Criteria Results","type":"array"}},"required":["status"],"title":"AgentSessionAnalysisResult","type":"object"},"AgentSessionMessageItem":{"description":"One transcript message; system messages never surface here.","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"runtime_message_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Runtime Message Id"},"message_generation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Message Generation Id"},"llm_usage":{"anyOf":[{"$ref":"#/components/schemas/LLMMessageUsage"},{"type":"null"}],"default":null},"type":{"const":"message","default":"message","title":"Type","type":"string"},"role":{"enum":["user","assistant"],"title":"Role","type":"string"},"content":{"title":"Content","type":"string"},"turn_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Turn Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"}},"required":["role","content"],"title":"AgentSessionMessageItem","type":"object"},"AgentSessionToolCallItem":{"description":"Tool invocation, mirroring the realtime `tool.started` event; `call_id`\nmatches the SDK event's callId, so live UIs and history line up.","properties":{"type":{"const":"tool_call","default":"tool_call","title":"Type","type":"string"},"call_id":{"title":"Call Id","type":"string"},"tool_name":{"title":"Tool Name","type":"string"},"tool_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tool Source"},"input":{"title":"Input","type":"string"},"turn_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Turn Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"}},"required":["call_id","tool_name","input"],"title":"AgentSessionToolCallItem","type":"object"},"AgentSessionToolResultItem":{"description":"Tool outcome (`tool.completed`/`tool.failed` twin). A call that never\nresolved (session died mid-flight) has no result item.","properties":{"type":{"const":"tool_result","default":"tool_result","title":"Type","type":"string"},"call_id":{"title":"Call Id","type":"string"},"tool_name":{"title":"Tool Name","type":"string"},"tool_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tool Source"},"status":{"enum":["completed","failed"],"title":"Status","type":"string"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Output"},"output_truncated":{"default":false,"title":"Output Truncated","type":"boolean"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Latency Ms"},"turn_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Turn Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"}},"required":["call_id","tool_name","status"],"title":"AgentSessionToolResultItem","type":"object"},"LLMMessageTokenCost":{"properties":{"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"rate_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Version"},"category":{"enum":["input","cache_read","cache_write_5m","cache_write_1h","output"],"title":"Category","type":"string"},"tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens"},"rate_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Per Million"},"cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Usd"}},"required":["model","rate_version","category","tokens","rate_per_million","cost_usd"],"title":"LLMMessageTokenCost","type":"object"},"LLMMessageUsage":{"properties":{"message_generation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Message Generation Id"},"turn_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Turn Id"},"status":{"enum":["complete","pending","unavailable"],"title":"Status","type":"string"},"billing_mode":{"enum":["tokens","included","legacy"],"title":"Billing Mode","type":"string"},"call_count":{"default":0,"title":"Call Count","type":"integer"},"usage_complete":{"default":false,"title":"Usage Complete","type":"boolean"},"call_ids":{"items":{"type":"string"},"title":"Call Ids","type":"array"},"cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cost Usd"},"billable_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Billable Cost Usd"},"known_cost_usd":{"default":"0","title":"Known Cost Usd","type":"string"},"tokens":{"items":{"$ref":"#/components/schemas/LLMMessageTokenCost"},"title":"Tokens","type":"array"}},"required":["status","billing_mode"],"title":"LLMMessageUsage","type":"object"},"AgentSessionRecordingTrackEntity":{"properties":{"role":{"enum":["agent","user","human"],"title":"Role","type":"string"},"status":{"enum":["requested","active","complete","failed"],"title":"Status","type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"expires_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Expires At"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Duration Ms"},"started_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Started At"},"ended_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Ended At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error Code"}},"required":["role","status"],"title":"AgentSessionRecordingTrackEntity","type":"object"},"PublicAgentEntity":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"status":{"enum":["active","archived"],"title":"Status","type":"string"},"publication_state":{"description":"`live` once at least one version is published; `draft` agents cannot take sessions yet.","enum":["live","draft"],"title":"Publication State","type":"string"},"public_enabled":{"default":false,"title":"Public Enabled","type":"boolean"},"allowed_origins":{"items":{"type":"string"},"title":"Allowed Origins","type":"array"},"overrides_allowed":{"items":{"enum":["first_message","system_prompt","voice_id","language"],"type":"string"},"title":"Overrides Allowed","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","workspace_id","name","status","publication_state","created_at","updated_at"],"title":"PublicAgentEntity","type":"object"},"AgentOutboundPatch":{"additionalProperties":false,"properties":{"amd_enabled":{"default":true,"title":"Amd Enabled","type":"boolean"},"voicemail":{"anyOf":[{"$ref":"#/components/schemas/AgentOutboundVoicemailPatch"},{"type":"null"}],"default":null}},"title":"AgentOutboundPatch","type":"object"},"AgentOutboundVoicemailPatch":{"additionalProperties":false,"properties":{"action":{"default":"hangup","enum":["hangup","leave_message","leave_prompt_message"],"title":"Action","type":"string"},"message":{"default":"","maxLength":10000,"title":"Message","type":"string"}},"title":"AgentOutboundVoicemailPatch","type":"object"},"AgentTransferDestinationPatch":{"additionalProperties":false,"properties":{"type":{"default":"phone","enum":["phone","sip"],"title":"Type","type":"string"},"label":{"default":"","title":"Label","type":"string"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"},"sip_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sip Uri"},"description":{"default":"","title":"Description","type":"string"},"mode":{"default":"cold","enum":["cold","warm"],"title":"Mode","type":"string"},"warm_connect":{"default":"confirm","enum":["confirm","briefing","direct"],"title":"Warm Connect","type":"string"},"warm_briefing_instructions":{"default":"","title":"Warm Briefing Instructions","type":"string"}},"title":"AgentTransferDestinationPatch","type":"object"},"PublicAgentAnalysisCriterion":{"additionalProperties":false,"properties":{"name":{"pattern":"^[a-z][a-z0-9_]{0,63}$","title":"Name","type":"string"},"description":{"default":"","maxLength":500,"title":"Description","type":"string"}},"required":["name"],"title":"PublicAgentAnalysisCriterion","type":"object"},"PublicAgentAnalysisDataField":{"additionalProperties":false,"properties":{"name":{"pattern":"^[a-z][a-z0-9_]{0,63}$","title":"Name","type":"string"},"type":{"default":"text","enum":["boolean","text","number","enum"],"title":"Type","type":"string"},"description":{"default":"","maxLength":500,"title":"Description","type":"string"},"enum_options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Enum Options"}},"required":["name"],"title":"PublicAgentAnalysisDataField","type":"object"},"PublicAgentAnalysisPatch":{"additionalProperties":false,"properties":{"summary":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentAnalysisSummaryPatch"},{"type":"null"}],"default":null},"data_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicAgentAnalysisDataField"},"maxItems":20,"type":"array"},{"type":"null"}],"default":null,"title":"Data Fields"},"criteria":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicAgentAnalysisCriterion"},"maxItems":10,"type":"array"},{"type":"null"}],"default":null,"title":"Criteria"}},"title":"PublicAgentAnalysisPatch","type":"object"},"PublicAgentAnalysisSummaryPatch":{"additionalProperties":false,"properties":{"enabled":{"default":true,"title":"Enabled","type":"boolean"},"prompt":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"title":"Prompt"},"language":{"default":"en","enum":["en","ja","zh","ko","es","fr","de","pt","it","nl","ar","hi","id","tr","ru","bg","sr","hr","cs","sk","pl","uk","ro","hu","el","sv","da","no","fi","et","lv","lt","ca","he","fa","ur","kk","ka","hy","bn","ta","te","kn","mr","gu","pa","ne","th","vi","ms","tl","af"],"title":"Language","type":"string"}},"title":"PublicAgentAnalysisSummaryPatch","type":"object"},"PublicAgentConfigPatchPayload":{"additionalProperties":false,"properties":{"prompt":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentPromptPatch"},{"type":"null"}],"default":null},"voice":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentVoicePatch"},{"type":"null"}],"default":null},"conversation":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentConversationPatch"},{"type":"null"}],"default":null},"tools":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentToolsPatch"},{"type":"null"}],"default":null},"webhooks":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentWebhooksPatch"},{"type":"null"}],"default":null},"knowledge_base":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentKnowledgeBasePatch"},{"type":"null"}],"default":null},"analysis":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentAnalysisPatch"},{"type":"null"}],"default":null},"guardrails":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentGuardrailsPatch"},{"type":"null"}],"default":null},"llm":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentLLMPatch"},{"type":"null"}],"default":null}},"title":"PublicAgentConfigPatchPayload","type":"object"},"PublicAgentConversationPatch":{"additionalProperties":false,"properties":{"max_duration_seconds":{"anyOf":[{"maximum":3600,"minimum":60,"type":"integer"},{"type":"null"}],"default":null,"title":"Max Duration Seconds"},"eagerness":{"anyOf":[{"enum":["relaxed","balanced","eager"],"type":"string"},{"type":"null"}],"default":null,"title":"Eagerness"},"interruptible":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Interruptible"},"interruption_sensitivity":{"anyOf":[{"enum":["low","balanced","high"],"type":"string"},{"type":"null"}],"default":null,"title":"Interruption Sensitivity"},"reengage_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Reengage Enabled"},"hangup_after_seconds":{"anyOf":[{"maximum":3600,"minimum":10,"type":"integer"},{"type":"null"}],"default":null,"title":"Hangup After Seconds"},"hangup_farewell_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Hangup Farewell Enabled"},"record_audio":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Record Audio"},"timezone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Timezone"},"transfer_destinations":{"anyOf":[{"items":{"$ref":"#/components/schemas/AgentTransferDestinationPatch"},"type":"array"},{"type":"null"}],"default":null,"title":"Transfer Destinations"},"outbound":{"anyOf":[{"$ref":"#/components/schemas/AgentOutboundPatch"},{"type":"null"}],"default":null}},"title":"PublicAgentConversationPatch","type":"object"},"PublicAgentCreatePayload":{"additionalProperties":false,"properties":{"name":{"maxLength":120,"minLength":1,"title":"Name","type":"string"},"description":{"default":"","maxLength":2000,"title":"Description","type":"string"},"config":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentConfigPatchPayload"},{"type":"null"}],"default":null,"description":"Optional initial draft configuration, applied atop the platform defaults; one call provisions a fully configured agent."}},"required":["name"],"title":"PublicAgentCreatePayload","type":"object"},"PublicAgentGuardrailsPatch":{"additionalProperties":false,"properties":{"focus":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Focus"},"manipulation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Manipulation"}},"title":"PublicAgentGuardrailsPatch","type":"object"},"PublicAgentKnowledgeBasePatch":{"additionalProperties":false,"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the agent retrieves from its attached sources. Defaults to true when omitted alongside a non-empty knowledge_source_ids; send false explicitly to attach sources without using them yet.","title":"Enabled"},"knowledge_source_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Replaces the attached knowledge sources wholesale. Every id must be an existing knowledge source visible to the agent, else 422.","title":"Knowledge Source Ids"}},"title":"PublicAgentKnowledgeBasePatch","type":"object"},"PublicAgentLLMCustomConfig":{"additionalProperties":false,"properties":{"base_url":{"maxLength":2000,"minLength":1,"title":"Base Url","type":"string"},"model":{"maxLength":256,"minLength":1,"title":"Model","type":"string"},"api_key":{"anyOf":[{"maxLength":4096,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Sent to your endpoint as the Authorization bearer token; write-only, reads return null. Required when introducing `custom`; omit to keep the stored key when updating.","title":"Api Key"}},"required":["base_url","model"],"title":"PublicAgentLLMCustomConfig","type":"object"},"PublicAgentLLMPatch":{"additionalProperties":false,"properties":{"model":{"anyOf":[{"enum":["google/gemini-3.5-flash-lite","google/gemini-3.6-flash","google/gemini-2.5-flash","google/gemma-4-26b-a4b-it","anthropic/claude-haiku-4.5","anthropic/claude-sonnet-4.6","openai/gpt-5.6-luna","openai/gpt-4o","openai/gpt-4.1"],"type":"string"},{"type":"null"}],"default":null,"title":"Model"},"custom":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentLLMCustomConfig"},{"type":"null"}],"default":null,"description":"Your own OpenAI-compatible endpoint; mutually exclusive with `model`, explicit null reverts to the platform model."}},"title":"PublicAgentLLMPatch","type":"object"},"PublicAgentPromptPatch":{"additionalProperties":false,"properties":{"system_prompt":{"anyOf":[{"maxLength":500000,"type":"string"},{"type":"null"}],"default":null,"description":"Limited to 32000 tokens (o200k_base); keeping it under 2000 tokens is recommended for latency and cost.","title":"System Prompt"},"first_message_mode":{"anyOf":[{"enum":["off","fixed","prompt"],"type":"string"},{"type":"null"}],"default":null,"title":"First Message Mode"},"first_message":{"anyOf":[{"maxLength":10000,"type":"string"},{"type":"null"}],"default":null,"title":"First Message"},"first_message_prompt":{"anyOf":[{"maxLength":10000,"type":"string"},{"type":"null"}],"default":null,"title":"First Message Prompt"}},"title":"PublicAgentPromptPatch","type":"object"},"PublicAgentToolsPatch":{"additionalProperties":false,"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Enabled"},"tool_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Replaces the attached tool set wholesale. Every id must be an existing tool in the agent's workspace, else 422.","title":"Tool Ids"},"system_tools":{"anyOf":[{"$ref":"#/components/schemas/PublicSystemToolsPatch"},{"type":"null"}],"default":null}},"title":"PublicAgentToolsPatch","type":"object"},"PublicAgentVoicePatch":{"additionalProperties":false,"properties":{"voice_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Voice Id"},"speaking_language":{"anyOf":[{"enum":["en","ja","zh","ko","es","fr","de","pt","it","nl","ar","hi","id","tr","ru","bg","sr","hr","cs","sk","pl","uk","ro","hu","el","sv","da","no","fi","et","lv","lt","ca","he","fa","ur","kk","ka","hy","bn","ta","te","kn","mr","gu","pa","ne","th","vi","ms","tl","af"],"type":"string"},{"type":"null"}],"default":null,"title":"Speaking Language"},"expressive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Expressive"},"keyterms":{"anyOf":[{"items":{"type":"string"},"maxItems":50,"type":"array"},{"type":"null"}],"default":null,"title":"Keyterms"},"speed":{"anyOf":[{"maximum":2.0,"minimum":0.5,"type":"number"},{"type":"null"}],"default":null,"title":"Speed"}},"title":"PublicAgentVoicePatch","type":"object"},"PublicAgentWebhooksPatch":{"additionalProperties":false,"properties":{"conversation_init":{"anyOf":[{"$ref":"#/components/schemas/PublicConversationInitWebhookPayload"},{"type":"null"}],"default":null,"description":"Pre-call webhook for inbound phone calls: called while the call is being set up; the response's dynamic_variables render into the published prompt before the agent speaks. An explicit null removes it. Takes effect after the next publish."},"post_call":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicPostCallWebhookPayload"},"maxItems":5,"type":"array"},{"type":"null"}],"default":null,"description":"Up to 5 endpoints, each receiving every post-call event. Replaces the configured list wholesale; a single object is still accepted and is stored as a one-element list, and null (or an empty list) clears every endpoint. URLs must be unique.","title":"Post Call"}},"title":"PublicAgentWebhooksPatch","type":"object"},"PublicConversationInitWebhookPayload":{"additionalProperties":false,"properties":{"url":{"maxLength":4000,"minLength":1,"title":"Url","type":"string"},"secret":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"description":"Optional HMAC-SHA256 signing secret (X-Fish-Webhook-Signature). Write-only: reads report `has_secret` instead of the value. Omit it (or send null) to keep the secret already stored for the same url; send an empty string to remove it.","title":"Secret"},"timeout_seconds":{"default":5.0,"description":"How long the platform waits for the endpoint before connecting the call without variables.","maximum":8.0,"minimum":1.0,"title":"Timeout Seconds","type":"number"}},"required":["url"],"title":"PublicConversationInitWebhookPayload","type":"object"},"PublicPostCallWebhookPayload":{"additionalProperties":false,"properties":{"url":{"maxLength":4000,"minLength":1,"title":"Url","type":"string"},"secret":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"description":"Optional HMAC-SHA256 signing secret (X-Fish-Webhook-Signature). Write-only: reads report `has_secret` instead of the value. Omit it (or send null) to keep the secret already stored for the same url; send an empty string to remove it.","title":"Secret"}},"required":["url"],"title":"PublicPostCallWebhookPayload","type":"object"},"PublicSystemToolsPatch":{"additionalProperties":false,"properties":{"hang_up_call":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Hang Up Call"}},"title":"PublicSystemToolsPatch","type":"object"},"PublicAgentUpdatePayload":{"additionalProperties":false,"properties":{"name":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"status":{"anyOf":[{"enum":["active","archived"],"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"public_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Allow keyless session creation from the browser SDK, gated by allowed_origins.","title":"Public Enabled"},"allowed_origins":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"null"}],"default":null,"title":"Allowed Origins"},"overrides_allowed":{"anyOf":[{"items":{"enum":["first_message","system_prompt","voice_id","language"],"type":"string"},"maxItems":8,"type":"array"},{"type":"null"}],"default":null,"description":"Which session-creation overrides callers may use. An empty list rejects all overrides.","title":"Overrides Allowed"}},"title":"PublicAgentUpdatePayload","type":"object"},"AgentAnalysisConfig":{"properties":{"summary":{"$ref":"#/components/schemas/AgentAnalysisSummaryConfig"},"data_fields":{"items":{"$ref":"#/components/schemas/AgentAnalysisDataField"},"maxItems":20,"title":"Data Fields","type":"array"},"criteria":{"items":{"$ref":"#/components/schemas/AgentAnalysisCriterion"},"maxItems":10,"title":"Criteria","type":"array"}},"title":"AgentAnalysisConfig","type":"object"},"AgentAnalysisCriterion":{"properties":{"name":{"pattern":"^[a-z][a-z0-9_]{0,63}$","title":"Name","type":"string"},"description":{"default":"","maxLength":500,"title":"Description","type":"string"}},"required":["name"],"title":"AgentAnalysisCriterion","type":"object"},"AgentAnalysisDataField":{"properties":{"name":{"pattern":"^[a-z][a-z0-9_]{0,63}$","title":"Name","type":"string"},"type":{"default":"text","enum":["boolean","text","number","enum"],"title":"Type","type":"string"},"description":{"default":"","maxLength":500,"title":"Description","type":"string"},"enum_options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Enum Options"}},"required":["name"],"title":"AgentAnalysisDataField","type":"object"},"AgentAnalysisSummaryConfig":{"properties":{"enabled":{"default":true,"title":"Enabled","type":"boolean"},"prompt":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"title":"Prompt"},"language":{"default":"en","enum":["en","ja","zh","ko","es","fr","de","pt","it","nl","ar","hi","id","tr","ru","bg","sr","hr","cs","sk","pl","uk","ro","hu","el","sv","da","no","fi","et","lv","lt","ca","he","fa","ur","kk","ka","hy","bn","ta","te","kn","mr","gu","pa","ne","th","vi","ms","tl","af"],"title":"Language","type":"string"}},"title":"AgentAnalysisSummaryConfig","type":"object"},"AgentConversationConfig":{"properties":{"max_duration_seconds":{"default":1800,"title":"Max Duration Seconds","type":"integer"},"eagerness":{"default":"balanced","enum":["relaxed","balanced","eager"],"title":"Eagerness","type":"string"},"interruptible":{"default":true,"title":"Interruptible","type":"boolean"},"interruption_sensitivity":{"default":"balanced","enum":["low","balanced","high"],"title":"Interruption Sensitivity","type":"string"},"reengage_enabled":{"default":false,"title":"Reengage Enabled","type":"boolean"},"hangup_after_seconds":{"default":60,"title":"Hangup After Seconds","type":"integer"},"hangup_farewell_enabled":{"default":false,"title":"Hangup Farewell Enabled","type":"boolean"},"record_audio":{"default":true,"title":"Record Audio","type":"boolean"},"timezone":{"default":"","title":"Timezone","type":"string"},"transfer_destinations":{"default":[],"items":{"$ref":"#/components/schemas/AgentTransferDestination"},"title":"Transfer Destinations","type":"array"},"outbound":{"anyOf":[{"$ref":"#/components/schemas/AgentOutboundConfig"},{"type":"null"}],"default":null}},"title":"AgentConversationConfig","type":"object"},"AgentGuardrailsConfig":{"properties":{"focus":{"default":false,"title":"Focus","type":"boolean"},"manipulation":{"default":false,"title":"Manipulation","type":"boolean"}},"title":"AgentGuardrailsConfig","type":"object"},"AgentLLMConfigRedacted":{"properties":{"model":{"default":"google/gemini-3.6-flash","enum":["google/gemini-3.5-flash-lite","google/gemini-3.6-flash","google/gemini-2.5-flash","google/gemma-4-26b-a4b-it","anthropic/claude-haiku-4.5","anthropic/claude-sonnet-4.6","openai/gpt-5.6-luna","openai/gpt-4o","openai/gpt-4.1"],"title":"Model","type":"string"},"custom":{"anyOf":[{"$ref":"#/components/schemas/AgentLLMCustomConfigRedacted"},{"type":"null"}],"default":null}},"title":"AgentLLMConfigRedacted","type":"object"},"AgentLLMCustomConfigRedacted":{"description":"Read entity: the stored api_key never leaves the collection.","properties":{"base_url":{"minLength":1,"title":"Base Url","type":"string"},"model":{"minLength":1,"title":"Model","type":"string"},"api_key":{"default":null,"title":"Api Key","type":"null"}},"required":["base_url","model"],"title":"AgentLLMCustomConfigRedacted","type":"object"},"AgentOutboundConfig":{"description":"Deprecated (2026-09-07): kept for compatibility only. `amd_enabled` and\n`voicemail` no longer change call behavior; outbound calls greet as soon as\nthe callee answers, and `answered_by` is always `unknown`.","properties":{"amd_enabled":{"default":true,"title":"Amd Enabled","type":"boolean"},"voicemail":{"anyOf":[{"$ref":"#/components/schemas/AgentOutboundVoicemailConfig"},{"type":"null"}],"default":null}},"title":"AgentOutboundConfig","type":"object"},"AgentOutboundVoicemailConfig":{"description":"Deprecated (2026-09-07): answering-machine detection was removed from the\ncall runtime, so voicemail actions never fire. The node is still accepted\nand stored so existing configs and API callers keep working; the worker\nno longer receives it.","properties":{"action":{"default":"hangup","enum":["hangup","leave_message","leave_prompt_message"],"title":"Action","type":"string"},"message":{"default":"","title":"Message","type":"string"}},"title":"AgentOutboundVoicemailConfig","type":"object"},"AgentPromptConfig":{"properties":{"system_prompt":{"default":"","title":"System Prompt","type":"string"},"first_message_mode":{"default":"prompt","enum":["off","fixed","prompt"],"title":"First Message Mode","type":"string"},"first_message":{"default":"Hi! Thanks for calling — how can I help you today?","title":"First Message","type":"string"},"first_message_prompt":{"default":"Greet the caller and ask what you can help with.","title":"First Message Prompt","type":"string"}},"title":"AgentPromptConfig","type":"object"},"AgentSystemToolsConfig":{"properties":{"hang_up_call":{"default":false,"title":"Hang Up Call","type":"boolean"}},"title":"AgentSystemToolsConfig","type":"object"},"AgentTransferDestination":{"properties":{"type":{"default":"phone","enum":["phone","sip"],"title":"Type","type":"string"},"label":{"default":"","title":"Label","type":"string"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone Number"},"sip_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sip Uri"},"description":{"default":"","title":"Description","type":"string"},"mode":{"default":"cold","enum":["cold","warm"],"title":"Mode","type":"string"},"warm_connect":{"default":"confirm","enum":["confirm","briefing","direct"],"title":"Warm Connect","type":"string"},"warm_briefing_instructions":{"default":"","title":"Warm Briefing Instructions","type":"string"}},"title":"AgentTransferDestination","type":"object"},"AgentVoiceConfig":{"properties":{"voice_id":{"default":"b347db033a6549378b48d00acb0d06cd","title":"Voice Id","type":"string"},"speaking_language":{"default":"en","enum":["en","ja","zh","ko","es","fr","de","pt","it","nl","ar","hi","id","tr","ru","bg","sr","hr","cs","sk","pl","uk","ro","hu","el","sv","da","no","fi","et","lv","lt","ca","he","fa","ur","kk","ka","hy","bn","ta","te","kn","mr","gu","pa","ne","th","vi","ms","tl","af"],"title":"Speaking Language","type":"string"},"expressive":{"default":false,"title":"Expressive","type":"boolean"},"keyterms":{"items":{"type":"string"},"maxItems":50,"title":"Keyterms","type":"array"},"speed":{"default":1.0,"maximum":2.0,"minimum":0.5,"title":"Speed","type":"number"}},"title":"AgentVoiceConfig","type":"object"},"PublicAgentKnowledgeBaseConfig":{"properties":{"enabled":{"default":false,"title":"Enabled","type":"boolean"},"knowledge_source_ids":{"items":{"type":"string"},"title":"Knowledge Source Ids","type":"array"}},"title":"PublicAgentKnowledgeBaseConfig","type":"object"},"PublicAgentToolsConfig":{"properties":{"enabled":{"default":true,"title":"Enabled","type":"boolean"},"tool_ids":{"items":{"type":"string"},"title":"Tool Ids","type":"array"},"system_tools":{"$ref":"#/components/schemas/AgentSystemToolsConfig"}},"title":"PublicAgentToolsConfig","type":"object"},"PublicAgentWebhooksConfig":{"properties":{"conversation_init":{"anyOf":[{"$ref":"#/components/schemas/PublicConversationInitWebhook"},{"type":"null"}],"default":null},"post_call":{"items":{"$ref":"#/components/schemas/PublicPostCallWebhook"},"title":"Post Call","type":"array"}},"title":"PublicAgentWebhooksConfig","type":"object"},"PublicConversationInitWebhook":{"properties":{"url":{"title":"Url","type":"string"},"has_secret":{"default":false,"description":"Whether a signing secret is configured; the value itself is never returned.","title":"Has Secret","type":"boolean"},"timeout_seconds":{"default":5.0,"title":"Timeout Seconds","type":"number"}},"required":["url"],"title":"PublicConversationInitWebhook","type":"object"},"PublicPostCallWebhook":{"properties":{"url":{"title":"Url","type":"string"},"has_secret":{"default":false,"description":"Whether a signing secret is configured; the value itself is never returned.","title":"Has Secret","type":"boolean"}},"required":["url"],"title":"PublicPostCallWebhook","type":"object"},"PublicAgentVersionSummary":{"properties":{"version_number":{"title":"Version Number","type":"integer"},"version_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Title"},"version_description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Version Description"},"config_hash":{"title":"Config Hash","type":"string"},"published_at":{"format":"date-time","title":"Published At","type":"string"}},"required":["version_number","config_hash","published_at"],"title":"PublicAgentVersionSummary","type":"object"},"PublicAgentConfigEntity":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"config_hash":{"description":"Content hash of the draft; equal to a version's config_hash when the draft has no unpublished changes.","title":"Config Hash","type":"string"},"prompt":{"$ref":"#/components/schemas/AgentPromptConfig"},"voice":{"$ref":"#/components/schemas/AgentVoiceConfig"},"conversation":{"$ref":"#/components/schemas/AgentConversationConfig"},"tools":{"$ref":"#/components/schemas/PublicAgentToolsConfig"},"webhooks":{"$ref":"#/components/schemas/PublicAgentWebhooksConfig"},"knowledge_base":{"$ref":"#/components/schemas/PublicAgentKnowledgeBaseConfig"},"analysis":{"$ref":"#/components/schemas/AgentAnalysisConfig"},"guardrails":{"$ref":"#/components/schemas/AgentGuardrailsConfig"},"llm":{"$ref":"#/components/schemas/AgentLLMConfigRedacted"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","config_hash","prompt","voice","conversation","tools","webhooks","knowledge_base","analysis","guardrails","llm","updated_at"],"title":"PublicAgentConfigEntity","type":"object"},"PublicKnowledgeSourceSummary":{"properties":{"knowledge_source_id":{"title":"Knowledge Source Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"file_name":{"title":"File Name","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"chunk_count":{"title":"Chunk Count","type":"integer"},"revision_number":{"description":"Increments every time the content is replaced. Drafts always use the newest revision; published versions pin the revision current at publish time.","title":"Revision Number","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["knowledge_source_id","workspace_id","name","file_name","size_bytes","chunk_count","revision_number","created_at","updated_at"],"title":"PublicKnowledgeSourceSummary","type":"object"},"PublicDependentAgent":{"properties":{"agent_id":{"title":"Agent Id","type":"string"},"name":{"title":"Name","type":"string"}},"required":["agent_id","name"],"title":"PublicDependentAgent","type":"object"},"PublicAgentToolSummary":{"properties":{"tool_id":{"title":"Tool Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"tool_type":{"enum":["webhook","client"],"title":"Tool Type","type":"string"},"method":{"enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","type":"string"},"url":{"title":"Url","type":"string"},"used_by":{"default":0,"description":"How many agents reference this tool in their draft configuration.","title":"Used By","type":"integer"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["tool_id","workspace_id","name","tool_type","method","url","created_at","updated_at"],"title":"PublicAgentToolSummary","type":"object"},"AgentWebhookArgumentPayload":{"properties":{"name":{"maxLength":64,"minLength":1,"title":"Name","type":"string"},"description":{"default":"","maxLength":500,"title":"Description","type":"string"}},"required":["name"],"title":"AgentWebhookArgumentPayload","type":"object"},"AgentWebhookHeaderPayload":{"properties":{"name":{"maxLength":128,"minLength":1,"title":"Name","type":"string"},"value":{"maxLength":4000,"title":"Value","type":"string"},"kind":{"default":"custom","enum":["custom","authorization_bearer","authorization_basic"],"title":"Kind","type":"string"}},"required":["name","value"],"title":"AgentWebhookHeaderPayload","type":"object"},"AgentWebhookMockResponsePayload":{"properties":{"name":{"default":"","maxLength":120,"title":"Name","type":"string"},"status_code":{"default":200,"maximum":599,"minimum":100,"title":"Status Code","type":"integer"},"content_type":{"default":"application/json","maxLength":128,"title":"Content Type","type":"string"},"body":{"default":"","maxLength":100000,"title":"Body","type":"string"}},"title":"AgentWebhookMockResponsePayload","type":"object"},"PublicAgentToolCreatePayload":{"additionalProperties":false,"description":"Console payload minus the folder concept (folders are console-only).","properties":{"name":{"maxLength":120,"minLength":1,"title":"Name","type":"string"},"description":{"default":"","maxLength":2000,"title":"Description","type":"string"},"tool_type":{"default":"webhook","enum":["webhook","client"],"title":"Tool Type","type":"string"},"arguments":{"items":{"$ref":"#/components/schemas/AgentWebhookArgumentPayload"},"title":"Arguments","type":"array"},"method":{"default":"POST","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","type":"string"},"url":{"default":"","maxLength":4000,"title":"Url","type":"string"},"content_type":{"default":"application/json","maxLength":128,"title":"Content Type","type":"string"},"body_template":{"default":"","maxLength":100000,"title":"Body Template","type":"string"},"headers":{"items":{"$ref":"#/components/schemas/AgentWebhookHeaderPayload"},"title":"Headers","type":"array"},"timeout_seconds":{"default":30,"maximum":300,"minimum":1,"title":"Timeout Seconds","type":"integer"},"error_handling":{"default":"passthrough","enum":["passthrough","hide"],"title":"Error Handling","type":"string"},"mock_responses":{"items":{"$ref":"#/components/schemas/AgentWebhookMockResponsePayload"},"title":"Mock Responses","type":"array"},"expects_response":{"default":true,"title":"Expects Response","type":"boolean"},"execution_mode":{"default":"blocking","enum":["blocking","fire_and_forget","background"],"title":"Execution Mode","type":"string"}},"required":["name"],"title":"PublicAgentToolCreatePayload","type":"object"},"PublicToolHeader":{"properties":{"name":{"title":"Name","type":"string"},"kind":{"enum":["custom","authorization_bearer","authorization_basic"],"title":"Kind","type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Header value; null for credential kinds (authorization_bearer / authorization_basic), which are write-only.","title":"Value"},"has_secret":{"default":false,"description":"Whether a credential value is stored; the value itself is never returned.","title":"Has Secret","type":"boolean"}},"required":["name","kind"],"title":"PublicToolHeader","type":"object"},"PublicAgentToolUpdatePayload":{"additionalProperties":false,"properties":{"name":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"description":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"arguments":{"anyOf":[{"items":{"$ref":"#/components/schemas/AgentWebhookArgumentPayload"},"type":"array"},{"type":"null"}],"default":null,"title":"Arguments"},"method":{"anyOf":[{"enum":["GET","POST","PUT","PATCH","DELETE"],"type":"string"},{"type":"null"}],"default":null,"title":"Method"},"url":{"anyOf":[{"maxLength":4000,"minLength":1,"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"content_type":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"title":"Content Type"},"body_template":{"anyOf":[{"maxLength":100000,"type":"string"},{"type":"null"}],"default":null,"title":"Body Template"},"headers":{"anyOf":[{"items":{"$ref":"#/components/schemas/AgentWebhookHeaderPayload"},"type":"array"},{"type":"null"}],"default":null,"title":"Headers"},"timeout_seconds":{"anyOf":[{"maximum":300,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Timeout Seconds"},"error_handling":{"anyOf":[{"enum":["passthrough","hide"],"type":"string"},{"type":"null"}],"default":null,"title":"Error Handling"},"mock_responses":{"anyOf":[{"items":{"$ref":"#/components/schemas/AgentWebhookMockResponsePayload"},"type":"array"},{"type":"null"}],"default":null,"title":"Mock Responses"},"expects_response":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Expects Response"},"execution_mode":{"anyOf":[{"enum":["blocking","fire_and_forget","background"],"type":"string"},{"type":"null"}],"default":null,"title":"Execution Mode"}},"title":"PublicAgentToolUpdatePayload","type":"object"},"PublicPhoneNumberEntity":{"properties":{"phone_number_id":{"title":"Phone Number Id","type":"string"},"workspace_id":{"title":"Workspace Id","type":"string"},"phone_number":{"description":"E.164, e.g. +14155550123.","title":"Phone Number","type":"string"},"provider":{"enum":["livekit","twilio","sip"],"title":"Provider","type":"string"},"label":{"default":"","title":"Label","type":"string"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Inbound calls route to this agent; unbound numbers ring busy.","title":"Agent Id"},"cold_transfer_use_original_caller":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Managed `twilio` numbers: whether a transfer target, cold or warm, sees the original caller's number (true) or this number (false). `null` for imported `sip` numbers, whose carrier owns the setting.","title":"Cold Transfer Use Original Caller"},"cold_transfer_use_original_caller_effective":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"The cold-transfer policy the carrier has confirmed; `null` while unknown or for imported `sip` numbers. Warm transfers follow `cold_transfer_use_original_caller` directly from the next call.","title":"Cold Transfer Use Original Caller Effective"},"caller_id_sync_status":{"default":"carrier_managed","description":"`synced` once the carrier confirmed the policy, `pending` while it is being applied, `error` when the last attempt failed (send `retry_caller_id_sync`), `carrier_managed` for imported `sip` numbers.","enum":["synced","pending","error","carrier_managed"],"title":"Caller Id Sync Status","type":"string"},"caller_id_sync_error":{"default":"","description":"Why the last synchronization failed; empty otherwise.","title":"Caller Id Sync Error","type":"string"},"status":{"enum":["provisioning","active","error","released"],"title":"Status","type":"string"},"status_detail":{"default":"","description":"What failed when status is `error`; empty otherwise.","title":"Status Detail","type":"string"},"supports_outbound":{"default":false,"description":"Whether the number can place calls (outbound and warm-transfer consult legs): managed `twilio` always, imported `sip` only when a termination was configured.","title":"Supports Outbound","type":"boolean"},"termination_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the customer trunk's termination host.","title":"Termination Uri"},"inbound_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the inbound digest username. Passwords are never echoed.","title":"Inbound Auth Username"},"inbound_allowed_addresses":{"description":"Imported `sip` numbers: allowed source IPs/CIDRs.","items":{"type":"string"},"title":"Inbound Allowed Addresses","type":"array"},"termination_transport":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: termination transport.","title":"Termination Transport"},"termination_auth_username":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Imported `sip` numbers: the termination digest username. Passwords are never echoed.","title":"Termination Auth Username"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["phone_number_id","workspace_id","phone_number","provider","agent_id","status","created_at","updated_at"],"title":"PublicPhoneNumberEntity","type":"object"},"PublicPhoneNumberPurchasePayload":{"additionalProperties":false,"properties":{"provider":{"const":"twilio","description":"`twilio` buys from the managed inventory (supports call transfer); `sip` imports a number you already own at your carrier; see the `sip` request variant.","title":"Provider","type":"string"},"phone_number":{"description":"E.164 number from `GET /v1/agent/available-phone-numbers`, e.g. +14155550123.","title":"Phone Number","type":"string"},"label":{"default":"","maxLength":120,"title":"Label","type":"string"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Bind an agent to answer inbound calls right away.","title":"Agent Id"}},"required":["provider","phone_number"],"title":"PublicPhoneNumberPurchasePayload","type":"object"},"PublicSipNumberImportPayload":{"additionalProperties":false,"description":"The `sip` variant of POST /v1/agent/phone-numbers: import a number that\nstays at your carrier. Point your trunk's origination at our SIP host,\ngive inbound at least one authentication factor (digest and/or source\nCIDRs), and optionally a termination host + credentials so the number can\nplace calls. Nothing is rented: carrier charges stay on your account, and\nimported numbers carry no telephony charges at all: no monthly fee, no\nphone surcharge, no transfer fees; you pay agent minutes only.","properties":{"inbound_auth_username":{"default":"","maxLength":128,"title":"Inbound Auth Username","type":"string"},"inbound_auth_password":{"default":"","maxLength":128,"title":"Inbound Auth Password","type":"string"},"inbound_allowed_addresses":{"items":{"type":"string"},"maxItems":32,"title":"Inbound Allowed Addresses","type":"array"},"termination_uri":{"default":"","title":"Termination Uri","type":"string"},"termination_transport":{"default":"auto","enum":["auto","udp","tcp","tls"],"title":"Termination Transport","type":"string"},"termination_auth_username":{"default":"","maxLength":128,"title":"Termination Auth Username","type":"string"},"termination_auth_password":{"default":"","maxLength":128,"title":"Termination Auth Password","type":"string"},"phone_number":{"title":"Phone Number","type":"string"},"label":{"default":"","maxLength":120,"title":"Label","type":"string"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Agent Id"},"provider":{"const":"sip","title":"Provider","type":"string"}},"required":["phone_number","provider"],"title":"PublicSipNumberImportPayload","type":"object"},"PublicPhoneNumberUpdatePayload":{"additionalProperties":false,"properties":{"label":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"title":"Label"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Agent that answers this number's inbound calls. Explicit null unbinds; omit the field to keep the current binding.","title":"Agent Id"},"cold_transfer_use_original_caller":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Managed `twilio` numbers only: show the original caller's number on transfers, cold and warm (true), or this number (false). Warm transfers follow it from the next call; cold transfers once `caller_id_sync_status` is `synced`.","title":"Cold Transfer Use Original Caller"},"retry_caller_id_sync":{"default":false,"description":"Re-apply the current caller ID policy after a failed synchronization.","title":"Retry Caller Id Sync","type":"boolean"}},"title":"PublicPhoneNumberUpdatePayload","type":"object"},"PhoneCallCreatePayload":{"additionalProperties":false,"description":"POST phone-calls body, shared by the public and console routes.\n\nto_number is deliberately not format-validated here: the contract orders\nthe E.164 check after the agent/published checks, so it runs in the\nservice with a machine-readable reason.","properties":{"agent_id":{"title":"Agent Id","type":"string"},"phone_number_id":{"description":"The team-owned number to dial from (twilio provider only).","title":"Phone Number Id","type":"string"},"to_number":{"description":"Destination in E.164, e.g. +14155550123.","title":"To Number","type":"string"},"dynamic_variables":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"}]},"maxProperties":50,"type":"object"},{"type":"null"}],"default":null,"title":"Dynamic Variables"},"overrides":{"anyOf":[{"$ref":"#/components/schemas/AgentSessionOverridesPayload"},{"type":"null"}],"default":null},"metadata":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"default":null,"title":"Metadata"},"llm_extra_body":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"default":null,"title":"Llm Extra Body"}},"required":["agent_id","phone_number_id","to_number"],"title":"PhoneCallCreatePayload","type":"object"},"ASRSegment":{"properties":{"text":{"title":"Text","type":"string"},"start":{"title":"Start","type":"number"},"end":{"title":"End","type":"number"}},"required":["text","start","end"],"title":"ASRSegment","type":"object"},"PronunciationDictionaryInline":{"additionalProperties":false,"description":"Inline literal pronunciation dictionary. The server forwards the entries directly to the inference engine without contacting the platform.","properties":{"items":{"description":"Replacement entries for this dictionary. See the top-level `pronunciation_dictionary` field description for replacement semantics.","items":{"$ref":"#/components/schemas/PronunciationItem"},"maxItems":5000,"title":"Items","type":"array"}},"required":["items"],"title":"PronunciationDictionaryInline","type":"object"},"PronunciationDictionaryRef":{"additionalProperties":false,"description":"Reference to a server-managed pronunciation dictionary. The server resolves contents via the platform pronunciation-dictionaries API and forwards the full merged dictionary to the inference engine, which performs the substitution.","properties":{"id":{"description":"Dictionary identifier as registered on the platform.","pattern":"^[A-Za-z0-9_-]{1,128}$","title":"Id","type":"string"},"version":{"description":"Immutable version identifier for the dictionary. Version is required — there is no implicit `latest`.","pattern":"^[A-Za-z0-9_-]{1,128}$","title":"Version","type":"string"}},"required":["id","version"],"title":"PronunciationDictionaryRef","type":"object"},"PronunciationItem":{"additionalProperties":false,"description":"A single key/value entry in a pronunciation dictionary. The inference engine replaces every occurrence of `key` in the request text with the phoneme form `value` during synthesis.","properties":{"key":{"description":"Source substring to match. Pure substring match — no tokenization, no regex. Overlapping matches resolve leftmost-longest. For CJK text include enough context to disambiguate.","maxLength":256,"minLength":1,"title":"Key","type":"string"},"value":{"description":"Phonetic representation that replaces the key during synthesis. Dictionary authors should NOT include the `<|phoneme_start|>` / `<|phoneme_end|>` markers themselves; the inference engine wraps the value with those markers internally so the body is treated as phonemes rather than orthographic text. Requests whose key or value contain either marker are rejected.","maxLength":1024,"minLength":1,"title":"Value","type":"string"},"case_sensitive":{"default":false,"description":"When true the match is case-sensitive; when false ASCII case folding is applied.","title":"Case Sensitive","type":"boolean"}},"required":["key","value"],"title":"PronunciationItem","type":"object"},"ProsodyControl":{"description":"Controls for adjusting the prosody (rhythm and intonation) of generated speech.","properties":{"speed":{"default":1.0,"description":"Speaking rate multiplier. Valid range: 0.5 to 2.0. 1.0 = normal speed, 0.5 = half speed, 2.0 = double speed. Useful for adjusting pacing without regenerating audio.","title":"Speed","type":"number"},"volume":{"default":0.0,"description":"Volume adjustment in decibels (dB). 0 = no change, positive values = louder, negative values = quieter.","title":"Volume","type":"number"},"normalize_loudness":{"default":true,"description":"Normalize output loudness for more consistent perceived volume. Applies to the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`); on `s1` it is accepted but has no effect.","title":"Normalize Loudness","type":"boolean"}},"title":"ProsodyControl","type":"object"},"ReferenceAudio":{"description":"A voice sample with its transcript, used for zero-shot voice cloning. The model will attempt to match the voice characteristics from the audio sample.","properties":{"audio":{"description":"Raw audio bytes of the voice sample. Supported formats: WAV, MP3, FLAC. For best results, use 10-30 seconds of clear speech with minimal background noise.","format":"binary","title":"Audio","type":"string"},"text":{"description":"The exact transcript of what is spoken in the audio sample. Accuracy is important for voice cloning quality.","title":"Text","type":"string"}},"required":["audio","text"],"title":"ReferenceAudio","type":"object"},"TTSRequest":{"description":"Request body for text-to-speech synthesis. Supports single-speaker synthesis on all compatible TTS models. Multi-speaker dialogue synthesis is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3-preview`, not `s1`.\n\n## Single Speaker\nProvide either `reference_id` (string) pointing to a voice model, or `references` (array of ReferenceAudio) for zero-shot cloning.\n\n## Multiple Speakers (Dialogue — S2 family and `drama-3-preview`)\nFor multi-speaker synthesis, provide:\n- `reference_id`: array of voice model IDs, e.g., [\"speaker-0-id\", \"speaker-1-id\"]\n- `text`: use speaker tags `<|speaker:0|>`, `<|speaker:1|>`, etc. to indicate speaker changes, e.g., \"<|speaker:0|>Hello!<|speaker:1|>Hi there!\"\n\nAlternatively, for zero-shot multi-speaker:\n- `references`: 2D array where each inner array contains references for one speaker\n- `reference_id`: array of identifiers (can be arbitrary strings for zero-shot)\n\n## Example (Multi-Speaker with Model IDs)\n```json\n{\n  \"text\": \"<|speaker:0|>Good morning!<|speaker:1|>Good morning! How are you?<|speaker:0|>I'm great, thanks!\",\n  \"reference_id\": [\"model-id-alice\", \"model-id-bob\"]\n}\n```","properties":{"text":{"description":"Text to convert to speech.","title":"Text","type":"string"},"temperature":{"default":0.7,"description":"Controls expressiveness. Higher is more varied, lower is more consistent.","maximum":1.0,"minimum":0.0,"title":"Temperature","type":"number"},"top_p":{"default":0.7,"description":"Controls diversity via nucleus sampling.","maximum":1.0,"minimum":0.0,"title":"Top P","type":"number"},"references":{"anyOf":[{"description":"Single speaker: array of reference audio samples","items":{"$ref":"#/components/schemas/ReferenceAudio"},"type":"array"},{"description":"Multiple speakers: array of arrays, where each inner array contains reference samples for one speaker","items":{"items":{"$ref":"#/components/schemas/ReferenceAudio"},"type":"array"},"type":"array"},{"type":"null"}],"description":"Inline voice references for zero-shot cloning. Requires MessagePack (not JSON). For single speaker, provide an array of ReferenceAudio objects. For multiple speakers, provide an array of arrays where each inner array contains references for one speaker. **Multi-speaker is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3-preview`, not `s1`.** The speaker index corresponds to the index in reference_id array. Example for multi-speaker: [[{audio, text}], [{audio, text}, {audio, text}]] for 2 speakers where speaker 1 has 2 reference samples.","title":"References"},"reference_id":{"anyOf":[{"description":"Single speaker: voice model ID string","type":"string"},{"description":"Multiple speakers: array of voice model IDs, one per speaker","items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Voice model ID(s) from Fish Audio library or your custom models. For single-speaker synthesis, provide a string. For multi-speaker synthesis (dialogue), provide an array of model IDs. **Multi-speaker is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3-preview`, not `s1`.** When using multiple speakers, use speaker tags in your text like `<|speaker:0|>` and `<|speaker:1|>` to indicate speaker changes. Example: `<|speaker:0|>Hello!<|speaker:1|>Hi there!<|speaker:0|>How are you?` with `reference_id: [\"speaker-a-id\", \"speaker-b-id\"]`.","title":"Reference Id"},"prosody":{"anyOf":[{"$ref":"#/components/schemas/ProsodyControl"},{"type":"null"}],"default":null,"description":"Speed and volume adjustments for the output."},"chunk_length":{"default":300,"description":"Text segment size for processing.","maximum":300,"minimum":100,"title":"Chunk Length","type":"integer"},"normalize":{"default":true,"description":"Normalizes text for English and Chinese, improving stability for numbers.","title":"Normalize","type":"boolean"},"format":{"default":"mp3","description":"Output audio format.","enum":["wav","pcm","mp3","opus"],"title":"Format","type":"string"},"sample_rate":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Audio sample rate in Hz. When null, uses the format's default (44100 Hz for most formats, 48000 Hz for opus).","title":"Sample Rate"},"mp3_bitrate":{"default":128,"description":"MP3 bitrate in kbps. Only applies when format is mp3.","enum":[64,128,192],"title":"Mp3 Bitrate","type":"integer"},"opus_bitrate":{"default":-1000,"description":"Opus bitrate in bps. -1000 for automatic. Only applies when format is opus.","enum":[-1000,24000,32000,48000,64000],"title":"Opus Bitrate","type":"integer"},"latency":{"default":"normal","description":"Latency-quality trade-off. normal: best quality, balanced: reduced latency, low: lowest latency.","enum":["low","normal","balanced"],"title":"Latency","type":"string"},"max_new_tokens":{"default":1024,"description":"Maximum audio tokens to generate per text chunk.","title":"Max New Tokens","type":"integer"},"repetition_penalty":{"default":1.2,"description":"Penalty for repeating audio patterns. Values above 1.0 reduce repetition.","title":"Repetition Penalty","type":"number"},"min_chunk_length":{"default":50,"description":"Minimum characters before splitting into a new chunk.","maximum":100,"minimum":0,"title":"Min Chunk Length","type":"integer"},"condition_on_previous_chunks":{"default":true,"description":"Use previous audio as context for voice consistency.","title":"Condition On Previous Chunks","type":"boolean"},"early_stop_threshold":{"default":1.0,"description":"Early stopping threshold for batch processing.","maximum":1.0,"minimum":0.0,"title":"Early Stop Threshold","type":"number"},"features":{"default":[],"description":"Optional request-scoped TTS feature flags forwarded verbatim to the inference backend. Use [\"quality-guard\"] to enable the quality guard for this synthesis request. Feature availability is determined by the inference backend.","items":{"type":"string"},"title":"Features","type":"array"},"pronunciation_dictionary":{"anyOf":[{"description":"Reference form: list of pointers to platform pronunciation dictionaries. Each entry identifies a dictionary by `id` and `version`; the server resolves the contents from the platform service before forwarding them to the inference engine.","items":{"$ref":"#/components/schemas/PronunciationDictionaryRef"},"maxItems":3,"type":"array"},{"description":"Inline form: list of literal pronunciation dictionaries. Each dictionary carries an `items` array of `{key, value, case_sensitive?}` entries.","items":{"$ref":"#/components/schemas/PronunciationDictionaryInline"},"maxItems":3,"type":"array"},{"type":"null"}],"default":null,"description":"Optional list of up to 3 pronunciation dictionaries to apply during synthesis. Provide either references to platform-managed dictionaries OR inline literal dictionaries (the two forms are mutually exclusive in a single request). The server resolves and merges the dictionaries, then forwards the full merged dictionary to the inference engine, which performs the substitution. Matching is plain substring matching, leftmost-longest, and case-insensitive unless an entry sets `case_sensitive`. Missing or unresolvable references are silently dropped — the request still succeeds. Use `application/json` or `application/msgpack` content-type; nested arrays are not representable in `multipart/form-data`.","title":"Pronunciation Dictionary"}},"required":["text"],"title":"TTSRequest","type":"object"},"TTSStreamWithTimestampRequest":{"description":"Request body for streaming text-to-speech synthesis with timestamp alignment. The request fields match the standard TTS endpoint, but the response is delivered as a Server-Sent Events stream. Each SSE payload includes an audio chunk and, when available, the latest cumulative alignment snapshot for a `chunk_seq`. Clients should concatenate `audio_base64` chunks in arrival order and replace the stored alignment for each `chunk_seq` whenever a newer snapshot is received.","properties":{"text":{"description":"Text to convert to speech.","title":"Text","type":"string"},"temperature":{"default":0.7,"description":"Controls expressiveness. Higher is more varied, lower is more consistent.","maximum":1.0,"minimum":0.0,"title":"Temperature","type":"number"},"top_p":{"default":0.7,"description":"Controls diversity via nucleus sampling.","maximum":1.0,"minimum":0.0,"title":"Top P","type":"number"},"references":{"anyOf":[{"description":"Single speaker: array of reference audio samples","items":{"$ref":"#/components/schemas/ReferenceAudio"},"type":"array"},{"description":"Multiple speakers: array of arrays, where each inner array contains reference samples for one speaker","items":{"items":{"$ref":"#/components/schemas/ReferenceAudio"},"type":"array"},"type":"array"},{"type":"null"}],"description":"Inline voice references for zero-shot cloning. Requires MessagePack (not JSON). For single speaker, provide an array of ReferenceAudio objects. For multiple speakers, provide an array of arrays where each inner array contains references for one speaker. **Multi-speaker is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3-preview`, not `s1`.** The speaker index corresponds to the index in reference_id array. Example for multi-speaker: [[{audio, text}], [{audio, text}, {audio, text}]] for 2 speakers where speaker 1 has 2 reference samples.","title":"References"},"reference_id":{"anyOf":[{"description":"Single speaker: voice model ID string","type":"string"},{"description":"Multiple speakers: array of voice model IDs, one per speaker","items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Voice model ID(s) from Fish Audio library or your custom models. For single-speaker synthesis, provide a string. For multi-speaker synthesis (dialogue), provide an array of model IDs. **Multi-speaker is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3-preview`, not `s1`.** When using multiple speakers, use speaker tags in your text like `<|speaker:0|>` and `<|speaker:1|>` to indicate speaker changes. Example: `<|speaker:0|>Hello!<|speaker:1|>Hi there!<|speaker:0|>How are you?` with `reference_id: [\"speaker-a-id\", \"speaker-b-id\"]`.","title":"Reference Id"},"prosody":{"anyOf":[{"$ref":"#/components/schemas/ProsodyControl"},{"type":"null"}],"default":null,"description":"Speed and volume adjustments for the output."},"chunk_length":{"default":300,"description":"Text segment size for processing.","maximum":300,"minimum":100,"title":"Chunk Length","type":"integer"},"normalize":{"default":true,"description":"Normalizes text for English and Chinese, improving stability for numbers.","title":"Normalize","type":"boolean"},"format":{"default":"mp3","description":"Output audio format.","enum":["wav","pcm","mp3","opus"],"title":"Format","type":"string"},"sample_rate":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Audio sample rate in Hz. When null, uses the format's default (44100 Hz for most formats, 48000 Hz for opus).","title":"Sample Rate"},"mp3_bitrate":{"default":128,"description":"MP3 bitrate in kbps. Only applies when format is mp3.","enum":[64,128,192],"title":"Mp3 Bitrate","type":"integer"},"opus_bitrate":{"default":-1000,"description":"Opus bitrate in bps. -1000 for automatic. Only applies when format is opus.","enum":[-1000,24000,32000,48000,64000],"title":"Opus Bitrate","type":"integer"},"latency":{"default":"normal","description":"Latency-quality trade-off. normal: best quality, balanced: reduced latency, low: lowest latency.","enum":["low","normal","balanced"],"title":"Latency","type":"string"},"max_new_tokens":{"default":1024,"description":"Maximum audio tokens to generate per text chunk.","title":"Max New Tokens","type":"integer"},"repetition_penalty":{"default":1.2,"description":"Penalty for repeating audio patterns. Values above 1.0 reduce repetition.","title":"Repetition Penalty","type":"number"},"min_chunk_length":{"default":50,"description":"Minimum characters before splitting into a new chunk.","maximum":100,"minimum":0,"title":"Min Chunk Length","type":"integer"},"condition_on_previous_chunks":{"default":true,"description":"Use previous audio as context for voice consistency.","title":"Condition On Previous Chunks","type":"boolean"},"early_stop_threshold":{"default":1.0,"description":"Early stopping threshold for batch processing.","maximum":1.0,"minimum":0.0,"title":"Early Stop Threshold","type":"number"},"features":{"default":[],"description":"Optional request-scoped TTS feature flags forwarded verbatim to the inference backend. Use [\"quality-guard\"] to enable the quality guard for this synthesis request. Feature availability is determined by the inference backend.","items":{"type":"string"},"title":"Features","type":"array"},"pronunciation_dictionary":{"anyOf":[{"description":"Reference form: list of pointers to platform pronunciation dictionaries. Each entry identifies a dictionary by `id` and `version`; the server resolves the contents from the platform service before forwarding them to the inference engine.","items":{"$ref":"#/components/schemas/PronunciationDictionaryRef"},"maxItems":3,"type":"array"},{"description":"Inline form: list of literal pronunciation dictionaries. Each dictionary carries an `items` array of `{key, value, case_sensitive?}` entries.","items":{"$ref":"#/components/schemas/PronunciationDictionaryInline"},"maxItems":3,"type":"array"},{"type":"null"}],"default":null,"description":"Optional list of up to 3 pronunciation dictionaries to apply during synthesis. Provide either references to platform-managed dictionaries OR inline literal dictionaries (the two forms are mutually exclusive in a single request). The server resolves and merges the dictionaries, then forwards the full merged dictionary to the inference engine, which performs the substitution. Matching is plain substring matching, leftmost-longest, and case-insensitive unless an entry sets `case_sensitive`. Missing or unresolvable references are silently dropped — the request still succeeds. Use `application/json` or `application/msgpack` content-type; nested arrays are not representable in `multipart/form-data`.","title":"Pronunciation Dictionary"}},"required":["text"],"title":"TTSStreamWithTimestampRequest","type":"object"},"TTSTimestampAlignment":{"properties":{"segments":{"description":"Ordered text timing segments for the generated audio.","items":{"$ref":"#/components/schemas/TTSTimestampSegment"},"title":"Segments","type":"array"},"audio_duration":{"description":"Audio duration in seconds for this alignment's content chunk.","title":"Audio Duration","type":"number"}},"required":["segments","audio_duration"],"title":"TTSTimestampAlignment","type":"object"},"TTSTimestampSegment":{"properties":{"text":{"description":"Text segment covered by this timing entry.","title":"Text","type":"string"},"start":{"description":"Segment start time in seconds.","title":"Start","type":"number"},"end":{"description":"Segment end time in seconds.","title":"End","type":"number"}},"required":["text","start","end"],"title":"TTSTimestampSegment","type":"object"},"TTSLiveErrorEvent":{"description":"Request-level failure raised before or instead of synthesis — an invalid `start` request, a missing voice reference, or a concurrency refusal. The socket closes afterwards.","examples":[{"error":"Concurrency limit exceeded","event":"error","max_concurrency":8}],"properties":{"event":{"const":"error","title":"Event","type":"string"},"error":{"description":"Failure detail.","title":"Error","type":"string"},"max_concurrency":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Your account's concurrency ceiling. Present only when the socket was refused for exceeding it.","title":"Max Concurrency"}},"required":["event","error"],"title":"TTSLiveErrorEvent","type":"object"},"TTSLiveFinishEvent":{"description":"Terminal event for the session. `reason: \"stop\"` follows a clean `stop`; `reason: \"error\"` reports a server-side failure and carries `message`. No further events arrive for the session.","examples":[{"event":"finish","reason":"stop","time":5460.0}],"properties":{"event":{"const":"finish","title":"Event","type":"string"},"reason":{"description":"`stop` when the session ended cleanly, `error` when the server aborted it.","enum":["stop","error"],"title":"Reason","type":"string"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Failure detail. Present only when `reason` is `error`.","title":"Message"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Milliseconds since the server began the session.","title":"Time"}},"required":["event","reason"],"title":"TTSLiveFinishEvent","type":"object"},"TTSLiveWithTimestampAudioEvent":{"description":"One audio chunk plus the latest word-level alignment snapshot. Concatenate every `audio` payload in arrival order to reconstruct the complete audio. `alignment` is the cumulative snapshot for `chunk_seq`: replace the stored alignment for that chunk instead of appending to it. Segment times are relative to the chunk, so the absolute time of a word is `chunk_audio_offset_sec + segment.start`.","examples":[{"alignment":{"audio_duration":16.24,"segments":[{"end":0.16,"start":0.0,"text":"I"},{"end":0.48,"start":0.16,"text":"can't"},{"end":0.8,"start":0.48,"text":"believe"},{"end":1.12,"start":0.8,"text":"its"},{"end":1.44,"start":1.2,"text":"been"},{"end":1.76,"start":1.44,"text":"this"},{"end":2.48,"start":1.76,"text":"long"},{"end":2.64,"start":2.56,"text":"It"},{"end":3.04,"start":2.72,"text":"feels"},{"end":3.28,"start":3.12,"text":"like"},{"end":4.0,"start":3.36,"text":"forever"},{"end":4.32,"start":4.0,"text":"since"},{"end":4.48,"start":4.32,"text":"we"},{"end":4.96,"start":4.48,"text":"last"},{"end":5.28,"start":4.96,"text":"really"},{"end":5.84,"start":5.28,"text":"talked"},{"end":6.24,"start":6.0,"text":"Ive"},{"end":6.64,"start":6.24,"text":"missed"},{"end":6.96,"start":6.64,"text":"hearing"},{"end":7.2,"start":6.96,"text":"your"},{"end":7.76,"start":7.2,"text":"voice"},{"end":7.92,"start":7.76,"text":"your"},{"end":8.48,"start":7.92,"text":"stories"},{"end":8.72,"start":8.48,"text":"even"},{"end":8.8,"start":8.72,"text":"the"},{"end":9.2,"start":8.8,"text":"little"},{"end":9.52,"start":9.2,"text":"things"},{"end":9.68,"start":9.52,"text":"you"},{"end":10.0,"start":9.68,"text":"used"},{"end":10.08,"start":10.0,"text":"to"},{"end":10.64,"start":10.08,"text":"say"},{"end":10.96,"start":10.64,"text":"How"},{"end":11.12,"start":10.96,"text":"have"},{"end":11.36,"start":11.12,"text":"you"},{"end":11.92,"start":11.36,"text":"been"},{"end":12.24,"start":12.0,"text":"Ive"},{"end":12.48,"start":12.24,"text":"thought"},{"end":12.8,"start":12.48,"text":"about"},{"end":13.2,"start":12.8,"text":"calling"},{"end":13.36,"start":13.2,"text":"you"},{"end":13.68,"start":13.36,"text":"so"},{"end":13.92,"start":13.68,"text":"many"},{"end":14.56,"start":13.92,"text":"times"},{"end":14.72,"start":14.56,"text":"but"},{"end":14.88,"start":14.72,"text":"I"},{"end":15.2,"start":14.88,"text":"never"},{"end":15.36,"start":15.2,"text":"knew"},{"end":15.6,"start":15.36,"text":"where"},{"end":15.6,"start":15.6,"text":"to"},{"end":16.24,"start":15.68,"text":"start"}]},"audio":"<raw audio bytes>","chunk_audio_offset_sec":0.0,"chunk_seq":0,"content":"I can’t believe it’s been this long. It feels like forever since we last really talked. I’ve missed hearing your voice, your stories, even the little things you used to say. How have you been? I’ve thought about calling you so many times, but I never knew where to start.","event":"audio","time":812.5},{"alignment":{"audio_duration":10.48,"segments":[{"end":0.8,"start":0.4,"text":"Seeing"},{"end":0.96,"start":0.8,"text":"you"},{"end":1.44,"start":0.96,"text":"again"},{"end":1.68,"start":1.44,"text":"now"},{"end":2.08,"start":1.68,"text":"makes"},{"end":2.24,"start":2.08,"text":"me"},{"end":2.8,"start":2.24,"text":"realize"},{"end":3.12,"start":2.8,"text":"just"},{"end":3.28,"start":3.12,"text":"how"},{"end":3.6,"start":3.28,"text":"much"},{"end":3.76,"start":3.6,"text":"Ive"},{"end":4.24,"start":3.84,"text":"missed"},{"end":4.56,"start":4.24,"text":"you"},{"end":4.8,"start":4.64,"text":"We"},{"end":5.04,"start":4.8,"text":"have"},{"end":5.36,"start":5.04,"text":"so"},{"end":5.76,"start":5.36,"text":"much"},{"end":5.76,"start":5.76,"text":"to"},{"end":6.16,"start":5.76,"text":"catch"},{"end":6.4,"start":6.16,"text":"up"},{"end":6.72,"start":6.4,"text":"on"},{"end":6.96,"start":6.8,"text":"and"},{"end":7.04,"start":6.96,"text":"I"},{"end":7.36,"start":7.04,"text":"dont"},{"end":7.6,"start":7.36,"text":"even"},{"end":7.84,"start":7.6,"text":"know"},{"end":8.08,"start":7.84,"text":"which"},{"end":8.4,"start":8.08,"text":"part"},{"end":8.48,"start":8.4,"text":"of"},{"end":8.72,"start":8.56,"text":"my"},{"end":8.96,"start":8.72,"text":"life"},{"end":9.12,"start":9.12,"text":"to"},{"end":9.44,"start":9.12,"text":"tell"},{"end":9.6,"start":9.44,"text":"you"},{"end":10.0,"start":9.6,"text":"about"},{"end":10.48,"start":10.08,"text":"first"}]},"audio":"<raw audio bytes>","chunk_audio_offset_sec":16.24,"chunk_seq":1,"content":"Seeing you again now makes me realize just how much I’ve missed you. We have so much to catch up on, and I don’t even know which part of my life to tell you about first.","event":"audio","time":4210.0}],"properties":{"event":{"const":"audio","title":"Event","type":"string"},"audio":{"description":"Raw audio chunk, carried as a MessagePack `bin` value — not base64, unlike the SSE `/v1/tts/stream/with-timestamp` endpoint. Concatenate every chunk in arrival order to reconstruct the full audio. May be empty on a trailing frame whose only purpose is to deliver a final `alignment` correction.","format":"binary","title":"Audio","type":"string"},"content":{"description":"Text content of the chunk identified by `chunk_seq`.","title":"Content","type":"string"},"alignment":{"anyOf":[{"$ref":"#/components/schemas/TTSTimestampAlignment"},{"type":"null"}],"description":"Cumulative word-level alignment snapshot for `chunk_seq`, with segment times relative to the start of that chunk. Always present on the wire; `null` means the alignment for this chunk has not changed yet (normal early in a chunk, while the aligner is still committing words). When non-null, replace the snapshot you stored for `chunk_seq` — never append to it."},"chunk_seq":{"description":"Sequence number of the text chunk that `alignment` and `content` describe. Monotonically non-decreasing. Bucket alignment snapshots by this value. Note that a frame may be labelled with the previous chunk's `chunk_seq` while carrying the next chunk's audio bytes, so do not use it to attribute audio.","minimum":0,"title":"Chunk Seq","type":"integer"},"chunk_audio_offset_sec":{"description":"Start time of this text chunk within the full audio, in seconds — the sum of the audio durations of every earlier chunk. Add it to a segment's `start`/`end` to get absolute timestamps. Monotonically non-decreasing.","minimum":0.0,"title":"Chunk Audio Offset Sec","type":"number"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Milliseconds since the server began the session.","title":"Time"}},"required":["event","audio","content","alignment","chunk_seq","chunk_audio_offset_sec"],"title":"TTSLiveWithTimestampAudioEvent","type":"object"},"TTSLiveFlushEvent":{"description":"Forces the buffered text through generation without waiting for the chunk to fill. A text-splitting control only: the session stays open and you may keep sending `text` events afterwards.","examples":[{"event":"flush"}],"properties":{"event":{"const":"flush","title":"Event","type":"string"}},"required":["event"],"title":"TTSLiveFlushEvent","type":"object"},"TTSLiveStartEvent":{"description":"Opens a synthesis session. Send this first, once per session. `request` carries the same fields as the `POST /v1/tts` body.","examples":[{"event":"start","request":{"chunk_length":100,"format":"opus","latency":"balanced","reference_id":"fbe02f8306fc4d3d915e9871722a39d5","text":""}}],"properties":{"event":{"const":"start","title":"Event","type":"string"},"request":{"$ref":"#/components/schemas/TTSRequest","description":"Synthesis parameters for this session, identical to the `POST /v1/tts` request body. `text` may be an empty string here; text sent later with `text` events is appended to it."}},"required":["event","request"],"title":"TTSLiveStartEvent","type":"object"},"TTSLiveStopEvent":{"description":"Ends the session. The server synthesizes whatever text is still buffered, emits any trailing `audio` events, then a `finish` event with `reason: \"stop\"`.","examples":[{"event":"stop"}],"properties":{"event":{"const":"stop","title":"Event","type":"string"}},"required":["event"],"title":"TTSLiveStopEvent","type":"object"},"TTSLiveTextEvent":{"description":"Appends a text fragment to the session buffer. Send as many as you like; the server splits the buffer into chunks and synthesizes them as they become long enough.","examples":[{"event":"text","text":"Hello there, "}],"properties":{"event":{"const":"text","title":"Event","type":"string"},"text":{"description":"Text fragment appended to the session buffer, verbatim.","title":"Text","type":"string"}},"required":["event","text"],"title":"TTSLiveTextEvent","type":"object"},"VoiceDesignRequest":{"additionalProperties":false,"description":"Request body for synchronous voice design generation. The endpoint returns generated voice candidates with base64-encoded audio.","examples":[{"guidance_scale":2.0,"instruct_guidance_scale":0.0,"instruction":"Warm, confident studio narrator with a natural tone","language":"en","n":2,"num_step":32,"reference_text":"Welcome to Fish Audio.","seed":42,"speed":1.0}],"properties":{"instruction":{"description":"Voice design prompt. Must contain 1 to 2000 characters.","maxLength":2000,"minLength":1,"title":"Instruction","type":"string"},"reference_text":{"anyOf":[{"maxLength":150,"type":"string"},{"type":"null"}],"default":null,"description":"Optional text used as reference content for the generated voice.","title":"Reference Text"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional BCP-47 language hint, such as `en`, `zh`, or `ja`.","title":"Language"},"n":{"default":2,"description":"Number of voice candidates to generate.","maximum":4,"minimum":1,"title":"N","type":"integer"},"speed":{"default":1.0,"description":"Speaking speed multiplier for candidate generation.","exclusiveMinimum":0.0,"maximum":3.0,"title":"Speed","type":"number"},"num_step":{"default":32,"description":"Number of diffusion steps used by the voice-design model.","maximum":128,"minimum":1,"title":"Num Step","type":"integer"},"guidance_scale":{"default":2.0,"description":"Classifier-free guidance scale. Higher values follow the prompt more strongly.","minimum":0.0,"title":"Guidance Scale","type":"number"},"instruct_guidance_scale":{"default":0.0,"description":"Instruction guidance scale for prompt conditioning.","minimum":0.0,"title":"Instruct Guidance Scale","type":"number"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional deterministic seed for candidate generation.","title":"Seed"}},"required":["instruction"],"title":"VoiceDesignRequest","type":"object"},"VoiceDesignCandidate":{"properties":{"id":{"description":"Stable candidate identifier.","title":"Id","type":"string"},"index":{"description":"Candidate index in this response.","minimum":0,"title":"Index","type":"integer"},"audio_base64":{"description":"Base64 encoded generated audio.","title":"Audio Base64","type":"string"},"sample_rate":{"description":"Audio sample rate in Hz.","exclusiveMinimum":0,"title":"Sample Rate","type":"integer"},"duration_ms":{"description":"Audio duration in milliseconds.","minimum":0,"title":"Duration Ms","type":"integer"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Preview text associated with this generated voice, when available.","title":"Text"},"instruct":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Instruction text associated with this candidate, when available.","title":"Instruct"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Detected or requested candidate language, when available.","title":"Language"}},"required":["id","index","audio_base64","sample_rate","duration_ms"],"title":"VoiceDesignCandidate","type":"object"},"AuthorEntity":{"properties":{"_id":{"title":"Id","type":"string"},"nickname":{"title":"Nickname","type":"string"},"avatar":{"title":"Avatar","type":"string"}},"required":["_id","nickname","avatar"],"title":"AuthorEntity","type":"object"},"ModelAudioQualityEntity":{"properties":{"filename":{"title":"Filename","type":"string"},"duration_ms":{"title":"Duration Ms","type":"number"},"language":{"default":"unknown","title":"Language","type":"string"},"quality":{"additionalProperties":{"type":"number"},"title":"Quality","type":"object"},"quality_passed":{"default":false,"title":"Quality Passed","type":"boolean"},"quality_reason":{"default":"","title":"Quality Reason","type":"string"}},"required":["filename","duration_ms"],"title":"ModelAudioQualityEntity","type":"object"},"ModelEntity":{"properties":{"_id":{"title":"Id","type":"string"},"type":{"enum":["svc","tts"],"title":"Type","type":"string"},"title":{"title":"Title","type":"string"},"description":{"default":"","title":"Description","type":"string"},"cover_image":{"default":"","title":"Cover Image","type":"string"},"train_mode":{"default":"full","enum":["fast","full"],"title":"Train Mode","type":"string"},"state":{"enum":["created","training","trained","failed"],"title":"State","type":"string"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"},"samples":{"default":[],"items":{"$ref":"#/components/schemas/SampleEntity"},"title":"Samples","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"},"languages":{"default":[],"items":{"type":"string"},"title":"Languages","type":"array"},"visibility":{"enum":["public","unlist","private"],"title":"Visibility","type":"string"},"lock_visibility":{"default":false,"title":"Lock Visibility","type":"boolean"},"dmca_taken_down":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Dmca Taken Down"},"takedown_category":{"anyOf":[{"enum":["dmca","policy"],"type":"string"},{"type":"null"}],"default":null,"title":"Takedown Category"},"default_text":{"default":"","title":"Default Text","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"licensed":{"default":false,"title":"Licensed","type":"boolean"},"pvc_release_state":{"anyOf":[{"enum":["released","retiring"],"type":"string"},{"type":"null"}],"default":null,"title":"Pvc Release State"},"pvc_notice_period_months":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pvc Notice Period Months"},"pvc_released_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Released At"},"pvc_retire_requested_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Retire Requested At"},"pvc_retire_effective_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Pvc Retire Effective At"},"quality":{"anyOf":[{"$ref":"#/components/schemas/ModelQualityEntity"},{"type":"null"}],"default":null},"like_count":{"title":"Like Count","type":"integer"},"mark_count":{"title":"Mark Count","type":"integer"},"shared_count":{"title":"Shared Count","type":"integer"},"task_count":{"title":"Task Count","type":"integer"},"unliked":{"default":false,"title":"Unliked","type":"boolean"},"liked":{"default":false,"title":"Liked","type":"boolean"},"marked":{"default":false,"title":"Marked","type":"boolean"},"author":{"$ref":"#/components/schemas/AuthorEntity"}},"required":["_id","type","title","state","tags","created_at","updated_at","visibility","like_count","mark_count","shared_count","task_count","author"],"title":"ModelEntity","type":"object"},"ModelQualityEntity":{"properties":{"audios":{"items":{"$ref":"#/components/schemas/ModelAudioQualityEntity"},"title":"Audios","type":"array"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["created_at","updated_at"],"title":"ModelQualityEntity","type":"object"},"SampleEntity":{"properties":{"title":{"title":"Title","type":"string"},"text":{"title":"Text","type":"string"},"task_id":{"title":"Task Id","type":"string"},"audio":{"title":"Audio","type":"string"}},"required":["title","text","task_id","audio"],"title":"SampleEntity","type":"object"}}},"servers":[{"description":"Fish Audio API","url":"https://api.fish.audio"}]}