{"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"},"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"}},"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"}},"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, caller\nnumber, 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 except pending.","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"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"}},"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"}},"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`; anything else is 422. Omit it to use the agent's configured\nbehavior (including automatic language detection when enabled).","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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"},"source":{"enum":["api_key","dashboard","public","phone"],"title":"Source","type":"string"},"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"},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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_profile_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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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_profile_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_profile_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"}},"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"}},"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_profile_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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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 (D-CI-17).\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"}},"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"}},"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"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","config_hash","prompt","voice","conversation","tools","webhooks","knowledge_base","analysis","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"}},"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"}},"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 4000 characters (422 beyond).\n`voice.voice_profile_id` accepts any public voice model id.\n`voice.speaking_language` accepts `en`, `ja`, `zh`, `ko`, `es`, `fr`, `de`;\nanything else is 422. `tool_ids` and\n`knowledge_source_ids` replace their attachment lists wholesale and every\nid must resolve, else 422.","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"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","config_hash","prompt","voice","conversation","tools","webhooks","knowledge_base","analysis","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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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        \"url\": \"https://example.com/hooks/fish\",\n        \"secret\": \"<signing-secret>\"\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. The\nbody is optional; the title and description label the version for audit\nand 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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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.","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 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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]},"post":{"summary":"Purchase Phone Number","description":"Buy a number from the inventory. The number lands in your default\nworkspace, and any `agent_id` you bind must live there too. Billing is the\nmonthly price charged in daily slices: the first day is charged before\nanything is bought (402 costs you nothing), and the daily run advances it\nfrom there. 409 means the number is already on the platform; 502 means the\nprovider refused the purchase — the number stays visible with status\n`error` and is safe to release.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPhoneNumberPurchasePayload"}}}},"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"],"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"},"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"},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"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"],"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"},"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"},"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"}},"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"}},"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.","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"],"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"},"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"},"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"}},"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"}},"required":["status","message"],"type":"object"}}}},"422":{"description":"","headers":{},"content":{"application/json":{"schema":{"properties":{"status":{"title":"Status","type":"integer"},"message":{"title":"Message","type":"string"}},"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"}},"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"}},"required":["status","message"],"type":"object"}}}}},"tags":["Phone Numbers"]}},"/v1/asr":{"post":{"summary":"Speech to Text","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"audio":{"description":"Audio to be converted to text","format":"binary","title":"Audio","type":"string"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Language to be used for the speech","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 to be converted to text","format":"binary","title":"Audio","type":"string"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Language to be used for the speech","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"}},"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"}},"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"}},"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.","required":true,"schema":{"default":"s2.1-pro-free","enum":["s1","s2-pro","s2.1-pro","s2.1-pro-free"],"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"}},"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"}},"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.1 Pro 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.","required":true,"schema":{"default":"s2.1-pro-free","enum":["s1","s2-pro","s2.1-pro","s2.1-pro-free"],"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"}},"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"}},"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/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"}},"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"}},"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":"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":"public","description":"Model visibility, public will be shown in the discovery page, unlist allows anyone with the link to access, private only be visible 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"},"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":"public","description":"Model visibility, public will be shown in the discovery page, unlist allows anyone with the link to access, private only be visible 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"},"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":"public","description":"Model visibility, public will be shown in the discovery page, unlist allows anyone with the link to access, private only be visible 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"},"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":"public","description":"Model visibility, public will be shown in the discovery page, unlist allows anyone with the link to access, private only be visible 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"},"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"},"default_text":{"default":"","title":"Default Text","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"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"}},"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"},"default_text":{"default":"","title":"Default Text","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"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"}},"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"}},"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"}},"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"}},"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"},"source":{"enum":["api_key","dashboard","public","phone"],"title":"Source","type":"string"},"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"},"language":{"anyOf":[{"enum":["en","ja","zh","ko","es","fr","de"],"type":"string"},{"type":"null"}],"default":null,"title":"Language"},"timezone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Timezone"},"client_timezone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"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"},"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"},"system_prompt":{"anyOf":[{"maxLength":8000,"type":"string"},{"type":"null"}],"default":null,"title":"System Prompt"},"voice_profile_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Voice Profile Id"},"language":{"anyOf":[{"enum":["en","ja","zh","ko","es","fr","de"],"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":{"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"},"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_profile_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"},"AgentTransferDestinationPatch":{"additionalProperties":false,"properties":{"type":{"const":"phone","default":"phone","title":"Type","type":"string"},"label":{"default":"","title":"Label","type":"string"},"phone_number":{"title":"Phone Number","type":"string"},"mode":{"default":"cold","enum":["cold","warm"],"title":"Mode","type":"string"},"warm_connect":{"default":"confirm","enum":["confirm","direct"],"title":"Warm Connect","type":"string"}},"required":["phone_number"],"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","zh","ja","ko","es","fr","de","pt","ru","ar"],"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}},"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"},"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"}},"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"},"PublicAgentKnowledgeBasePatch":{"additionalProperties":false,"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"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"},"PublicAgentPromptPatch":{"additionalProperties":false,"properties":{"system_prompt":{"anyOf":[{"maxLength":4000,"type":"string"},{"type":"null"}],"default":null,"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_profile_id":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}],"default":null,"title":"Voice Profile Id"},"speaking_language":{"anyOf":[{"enum":["en","ja","zh","ko","es","fr","de"],"type":"string"},{"type":"null"}],"default":null,"title":"Speaking Language"}},"title":"PublicAgentVoicePatch","type":"object"},"PublicAgentWebhooksPatch":{"additionalProperties":false,"properties":{"post_call":{"anyOf":[{"$ref":"#/components/schemas/PublicPostCallWebhookPayload"},{"type":"null"}],"default":null}},"title":"PublicAgentWebhooksPatch","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.","title":"Secret"}},"required":["url"],"title":"PublicPostCallWebhookPayload","type":"object"},"PublicSystemToolsPatch":{"additionalProperties":false,"properties":{"language_detection":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Language Detection"},"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_profile_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","zh","ja","ko","es","fr","de","pt","ru","ar"],"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"},"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"}},"title":"AgentConversationConfig","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 warmly, mention you can help with orders and callbacks.","title":"First Message Prompt","type":"string"}},"title":"AgentPromptConfig","type":"object"},"AgentSystemToolsConfig":{"properties":{"language_detection":{"default":false,"title":"Language Detection","type":"boolean"},"hang_up_call":{"default":false,"title":"Hang Up Call","type":"boolean"}},"title":"AgentSystemToolsConfig","type":"object"},"AgentTransferDestination":{"properties":{"type":{"const":"phone","default":"phone","title":"Type","type":"string"},"label":{"default":"","title":"Label","type":"string"},"phone_number":{"title":"Phone Number","type":"string"},"mode":{"default":"cold","enum":["cold","warm"],"title":"Mode","type":"string"},"warm_connect":{"default":"confirm","enum":["confirm","direct"],"title":"Warm Connect","type":"string"}},"required":["phone_number"],"title":"AgentTransferDestination","type":"object"},"AgentVoiceConfig":{"properties":{"voice_profile_id":{"default":"4501d82f5de3467ebf4d7ef095a2deee","title":"Voice Profile Id","type":"string"},"speaking_language":{"default":"en","enum":["en","ja","zh","ko","es","fr","de"],"title":"Speaking Language","type":"string"}},"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":{"post_call":{"anyOf":[{"$ref":"#/components/schemas/PublicPostCallWebhook"},{"type":"null"}],"default":null}},"title":"PublicAgentWebhooksConfig","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"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["agent_id","config_hash","prompt","voice","conversation","tools","webhooks","knowledge_base","analysis","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":120,"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"}},"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":120,"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"}},"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"],"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"},"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"},"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":"Inventory to buy from. Only the managed `twilio` inventory is purchasable (supports call transfer). The field discriminates so importing your own numbers can share this endpoint later.","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"},"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"}},"title":"PublicPhoneNumberUpdatePayload","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"},"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. **S2-Pro only.**","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 only available with the S2-Pro model.\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-Pro only)\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 only available with the S2-Pro model.** 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 only available with the S2-Pro model.** 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"}},"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 only available with the S2-Pro model.** 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 only available with the S2-Pro model.** 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"}},"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"},"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"},"default_text":{"default":"","title":"Default Text","type":"string"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source"},"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"}]}