{"openapi":"3.1.0","info":{"title":"Fish Audio (BYOK) API","version":"0.1.0","description":"Fish Audio (BYOK) lets an AI assistant read your own Fish Audio data through the Fish Audio API with a key you supply (Fish Audio API key). Read-only: 9 tools (get_api_credit, get_plan, list_voice_models, get_voice_model, list_agents, get_agent, list_agent_sessions, list_knowledge_sources, list_agent_tools). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-fish-audio.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-fish-audio/docs"},"termsOfService":"https://connectorbay.com/byok-fish-audio/terms"},"servers":[{"url":"https://byok-fish-audio.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-fish-audio/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_api_credit":{"post":{"operationId":"get_api_credit","summary":"Show the API credit balance and cumulative top-up amount of the key's account. Use for \"How much Fish Audio API credit d","description":"Show the API credit balance and cumulative top-up amount of the key's account. Use for \"How much Fish Audio API credit do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_creditArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_plan":{"post":{"operationId":"get_plan","summary":"Show the key account's current Fish Audio plan package: type, total and remaining balance, and dates. Use for \"What Fish","description":"Show the key account's current Fish Audio plan package: type, total and remaining balance, and dates. Use for \"What Fish Audio plan am I on and how much balance remains\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_planArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_voice_models":{"post":{"operationId":"list_voice_models","summary":"List or search voice models (public voices, or only your own with self=true) with language, state, tags and popularity. ","description":"List or search voice models (public voices, or only your own with self=true) with language, state, tags and popularity. Use for \"Find public Fish Audio voices titled 'narrator' sorted by popularity\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only models whose title matches this text.","title":"Title"},"self":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only voices owned by your workspace.","title":"Self"},"licensed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return only voices licensed by Fish Audio.","title":"Licensed"},"sort_by":{"anyOf":[{"enum":["score","task_count","created_at"],"type":"string"},{"type":"null"}],"default":"score","description":"Order by score, task_count or created_at.","title":"Sort By"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Page Size"},"page_number":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"}},"title":"list_voice_modelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_voice_model":{"post":{"operationId":"get_voice_model","summary":"Get one voice model's title, description, languages, training state, tags and popularity counts. Use for \"What is the st","description":"Get one voice model's title, description, languages, training state, tags and popularity counts. Use for \"What is the state and language of Fish Audio voice model abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Voice model id (the _id field from list_voice_models).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_voice_modelArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agents":{"post":{"operationId":"list_agents","summary":"List voice agents of the key's team, newest first, with publication state; page by cursor or page number. Use for \"Which","description":"List voice agents of the key's team, newest first, with publication state; page by cursor or page number. Use for \"Which Fish Audio voice agents are live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive match on agent name and description.","title":"Search"},"publication_state":{"anyOf":[{"enum":["all","live","draft"],"type":"string"},{"type":"null"}],"default":"all","description":"Filter: all, live (has a published version) or draft.","title":"Publication State"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived agents.","title":"Include Archived"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"The next_cursor from the previous answer while has_more is true.","title":"Cursor"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"1-based page number (offset paging, returns total); cannot be combined with cursor.","title":"Page"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the total count of matching items.","title":"Include Total"}},"title":"list_agentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_agent":{"post":{"operationId":"get_agent","summary":"Get one voice agent's profile: name, description, status and publication state. Use for \"Is Fish Audio agent agent_123 p","description":"Get one voice agent's profile: name, description, status and publication state. Use for \"Is Fish Audio agent agent_123 published\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"Agent id from list_agents.","maxLength":200,"title":"Agent Id","type":"string"}},"required":["agent_id"],"title":"get_agentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agent_sessions":{"post":{"operationId":"list_agent_sessions","summary":"List call sessions of voice agents, newest first, with status, end reason, direction, source and duration. Caller phone ","description":"List call sessions of voice agents, newest first, with status, end reason, direction, source and duration. Caller phone numbers are not returned. Use for \"Show my recent failed Fish Audio agent sessions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions of this agent id.","title":"Agent Id"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated status filter: pending, active, completed, failed, unknown.","title":"Status"},"direction":{"anyOf":[{"enum":["inbound","outbound"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by call direction: inbound or outbound.","title":"Direction"},"created_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions created after this ISO 8601 time.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions created before this ISO 8601 time.","title":"Created Before"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"The next_cursor from the previous answer while has_more is true.","title":"Cursor"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the total count of matching items.","title":"Include Total"}},"title":"list_agent_sessionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_knowledge_sources":{"post":{"operationId":"list_knowledge_sources","summary":"List knowledge sources (documents) available to voice agents with size, chunk count and revision. Use for \"What knowledg","description":"List knowledge sources (documents) available to voice agents with size, chunk count and revision. Use for \"What knowledge files do my Fish Audio agents use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive match on name and file name.","title":"Search"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"The next_cursor from the previous answer while has_more is true.","title":"Cursor"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the total count of matching items.","title":"Include Total"}},"title":"list_knowledge_sourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agent_tools":{"post":{"operationId":"list_agent_tools","summary":"List tools that voice agents can call (webhook or client type) with the number of agents using each. Use for \"Which tool","description":"List tools that voice agents can call (webhook or client type) with the number of agents using each. Use for \"Which tools do my Fish Audio agents have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive match on tool name.","title":"Search"},"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tools attached to this agent's draft configuration.","title":"Agent Id"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many results to return (1 to 100).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"The next_cursor from the previous answer while has_more is true.","title":"Cursor"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the total count of matching items.","title":"Include Total"}},"title":"list_agent_toolsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}