The Fish Audio connector lets your AI agent act in each user's Fish Audio account. Each user connects their own Fish Audio access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 34 tools.
- Tools
- 34
- What they doRead · write · destructive
- 19 · 11 · 419 read11 write4 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Fish Audio connection
In AgentKit > Connections, create a Fish Audio connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'fishaudio'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Fish Audio:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'fishaudio_get_api_credit',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "fishaudio"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Fish Audio:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="fishaudio_get_api_credit",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Fish Audio credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolfishaudio_get_agentGet one voice agent's profile.Read-onlyGet Agent
Get one voice agent's profile. Returns agent_id, workspace_id, name, description, status, publication_state, public_enabled, allowed_origins, overrides_allowed and timestamps. Use this for agent-level settings. Use fishaudio_get_agent_config for the draft voice, prompt and conversation settings.
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
fishaudio_get_agent_configGet a voice agent's current draft configuration, the state the next publish will freeze.Read-onlyGet Agent Config
Get a voice agent's current draft configuration, the state the next publish will freeze. Returns config_hash and the prompt, voice, asr, conversation, tools, webhooks, knowledge_base, analysis, guardrails, llm and variables sections; secrets read back as has_secret. Use this to read voice and prompt settings. Live sessions run the published version: use fishaudio_get_agent_version for that.
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
fishaudio_get_agent_sessionGet one voice agent session with its full conversation timeline.Read-onlyGet Agent Session
Get one voice agent session with its full conversation timeline. Returns status, timing, caller details and the timeline of transcript turns interleaved with tool calls, in order, plus post-call analysis when available. Use this to read what was said on a call. Use fishaudio_get_agent_session_recording for the audio.
Inputs
session_idstringrequired- Agent session ID, from fishaudio_list_agent_sessions or the session_id returned by fishaudio_create_phone_call. Example: 9b1d3f5a7c9e4b2d8f6a1c3e5b7d9f0a
fishaudio_get_agent_session_recordingGet time-limited download links for a session's audio recording, one track per speaker.Read-onlyGet Agent Session Recording
Get time-limited download links for a session's audio recording, one track per speaker. Returns status (processing, complete or failed) and tracks, each with role (agent, user or human), url, expires_at and duration_ms. Use this to fetch call audio; the links expire, so download soon. Recording must be on in the agent's conversation settings. Use fishaudio_get_agent_session for the transcript.
Inputs
session_idstringrequired- Agent session ID, from fishaudio_list_agent_sessions or the session_id returned by fishaudio_create_phone_call. Example: 9b1d3f5a7c9e4b2d8f6a1c3e5b7d9f0a
fishaudio_get_agent_toolGet one voice agent tool's full definition.Read-onlyGet Agent Tool
Get one voice agent tool's full definition. Returns name, description, tool_type, arguments, method, url, content_type, body_template, headers (credentials shown only as has_secret), timeout and execution settings. Use this before editing a tool with fishaudio_update_agent_tool.
Inputs
tool_idstringrequired- Agent tool ID, from fishaudio_list_agent_tools. Example: tool_8f2c4e6a1b3d
fishaudio_get_agent_versionGet one published version of a voice agent with its frozen configuration.Read-onlyGet Agent Version
Get one published version of a voice agent with its frozen configuration. Returns version_number, version_title, config_hash, published_at and config (prompt, voice, asr, conversation, tools, knowledge_base, llm and other sections), with secrets redacted. Use this to see what a live or past version runs. Use fishaudio_get_agent_config for the unpublished draft.
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
version_numberintegerrequired- Version number to read, from fishaudio_list_agent_versions. Example: 3
fishaudio_get_api_creditGet the API credit balance of the account that owns the API key.Read-onlyGet API Credit
Get the API credit balance of the account that owns the API key. Returns credit (remaining balance, as a decimal string), cumulative_top_up, has_free_credit and timestamps. Use this before large jobs to check the balance. Use fishaudio_get_package for the subscription plan and its quota.
Inputs
check_free_creditboolean- Set to true to also report whether the account still has free credit (has_free_credit). Defaults to false.
team_idstring- Team ID to read the credit of, when the key belongs to several teams. Leave empty for the key's own account.
fishaudio_get_knowledge_sourceGet one knowledge source with its full text content.Read-onlyGet Knowledge Source
Get one knowledge source with its full text content. Returns the source's ID, name, description, full text content and current revision number. Use this to read what an agent knows. Use fishaudio_list_knowledge_sources to find the ID.
Inputs
source_idstringrequired- Knowledge source ID, from fishaudio_list_knowledge_sources. Example: 3e5a7c9b1d2f4e6a8c0b2d4f6a8c1e3b
fishaudio_get_packageGet the subscription package of the account that owns the API key.Read-onlyGet Subscription Package
Get the subscription package of the account that owns the API key. Returns type (plan), total and balance, billing_period, current_period_end, subscription_status, cancel_at_period_end and extra_balance. Use this to see the plan and its remaining quota. Use fishaudio_get_api_credit for the pay-as-you-go API credit balance.
Inputs
This tool takes no inputs.
fishaudio_get_phone_numberGet one phone number with its current agent binding and settings.Read-onlyGet Phone Number
Get one phone number with its current agent binding and settings. Returns the number's ID, E.164 number, label, provider, bound agent_id and caller ID sync status. Use this to check a single number. Use fishaudio_list_phone_numbers to find its ID.
Inputs
phone_number_idstringrequired- Phone number ID, from fishaudio_list_phone_numbers (the id field). Example: 7c9e6f2a4b8d4e1f9a3c5d7e8f0b1a2c
fishaudio_get_voice_modelGet one Fish Audio voice model by ID.Read-onlyGet Voice Model
Get one Fish Audio voice model by ID. Returns the model's _id, title, description, type, state, visibility, tags, languages, sample audio links, author and usage counts. Use this to check a voice before using its ID. Use fishaudio_search_voice_models or fishaudio_list_my_voice_models to find an ID.
Inputs
model_idstringrequired- Fish Audio voice model ID (the _id field from fishaudio_search_voice_models or fishaudio_list_my_voice_models). The same ID is the reference_id used for text-to-speech and the voice_id used in agent voice settings. Example: 802e3bc2b27e49c2995d23ef70e6ac89
fishaudio_list_agent_sessionsList voice agent sessions (calls and web conversations), newest first, with optional filters.Read-onlyList Agent Sessions
List voice agent sessions (calls and web conversations), newest first, with optional filters. Returns sessions with session_id, agent_id, agent_name, status, end_reason, direction, caller_number, dialed_number, created_at, duration_seconds and metadata, plus has_more and next_cursor. Use this to find calls. Use fishaudio_get_agent_session for one session's transcript and tool calls.
Inputs
agent_idstring- ID of the agent whose sessions to return, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
call_sidstring- Exact carrier call ID, such as a Twilio CallSid on inbound calls.
caller_numberstring- Exact caller phone number in E.164 format (phone sessions only). Example: +14155550123
created_afterstring- Only sessions created after this ISO 8601 time. Example: 2026-10-01T00:00:00Z
created_beforestring- Only sessions created before this ISO 8601 time. Example: 2026-10-20T00:00:00Z
cursorstring- Cursor for the next page: pass the next_cursor value from the previous response while has_more is true. Do not combine with page.
directionstring- Call direction: inbound or outbound.one of
inboundoutbound end_reasonstring- Comma-separated end reasons to include, such as user_hangup, agent_hangup, escalated, conversation_timeout, internal_error, cancelled, dial_failed. Example: user_hangup,agent_hangup
end_user_idstring- Exact end_user_id set when the session was created. Example: user-42
include_totalboolean- Set to true to also return the total count when paging with cursor. Defaults to false.
pageinteger- 1-based page number for offset pagination; the response then includes total. Do not combine with cursor. Example: 2
page_sizeinteger- Number of results per page, 1 to 100. Defaults to 30.
sip_call_idstring- Exact SIP Call-ID of the call (phone sessions only), to match a carrier record.
statusstring- Comma-separated statuses to include: pending, active, completed, failed, unknown. Example: completed,failed
fishaudio_list_agent_toolsList your team's voice agent tools (webhook and client tools), newest first, optionally filtered by text or agent.Read-onlyList Agent Tools
List your team's voice agent tools (webhook and client tools), newest first, optionally filtered by text or agent. Returns tools with their ID, name, description, tool_type, method and url, plus has_more and next_cursor. Use this to find tool IDs to attach in fishaudio_update_agent_config. Use fishaudio_get_agent_tool for one tool's full definition.
Inputs
agent_idstring- ID of the agent whose attached tools to return, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
cursorstring- Cursor for the next page: pass the next_cursor value from the previous response while has_more is true. Do not combine with page.
include_totalboolean- Set to true to also return the total count when paging with cursor. Defaults to false.
pageinteger- 1-based page number for offset pagination; the response then includes total. Do not combine with cursor. Example: 2
page_sizeinteger- Number of results per page, 1 to 100. Defaults to 30.
searchstring- Text matched against tool name and description. Example: order
fishaudio_list_agent_versionsList a voice agent's published versions, newest first.Read-onlyList Agent Versions
List a voice agent's published versions, newest first. Returns versions with version_number, version_title, version_description, config_hash and published_at, plus has_more and next_cursor; the highest version_number is live. Use this to see publish history. Use fishaudio_get_agent_version for one version's full configuration.
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
cursorstring- Cursor for the next page: pass the next_cursor value from the previous response while has_more is true. Do not combine with page.
include_totalboolean- Set to true to also return the total count when paging with cursor. Defaults to false.
pageinteger- 1-based page number for offset pagination; the response then includes total. Do not combine with cursor. Example: 2
page_sizeinteger- Number of results per page, 1 to 100. Defaults to 30.
fishaudio_list_agentsList your team's Fish Audio voice agents, newest first, optionally filtered by text or publication state.Read-onlyList Agents
List your team's Fish Audio voice agents, newest first, optionally filtered by text or publication state. Returns agents with agent_id, name, description, status, publication_state, public_enabled and timestamps, plus has_more and next_cursor. Use this to find an agent_id. Use fishaudio_get_agent for one agent and fishaudio_get_agent_config for its voice and prompt settings.
Inputs
cursorstring- Cursor for the next page: pass the next_cursor value from the previous response while has_more is true. Do not combine with page.
include_archivedboolean- Set to true to include archived agents. Defaults to false.
include_totalboolean- Set to true to also return the total count when paging with cursor. Defaults to false.
pageinteger- 1-based page number for offset pagination; the response then includes total. Do not combine with cursor. Example: 2
page_sizeinteger- Number of results per page, 1 to 100. Defaults to 30.
publication_statestring- Filter by state: all (default), live (has a published version) or draft (never published).one of
alllivedraft searchstring- Case-insensitive text matched against agent name and description. Example: support
fishaudio_list_knowledge_sourcesList your team's knowledge sources (documents agents answer from), newest first.Read-onlyList Knowledge Sources
List your team's knowledge sources (documents agents answer from), newest first. Returns knowledge sources with their ID, name, description, revision and timestamps, plus has_more and next_cursor. Use this to find source IDs for the knowledge_base section of fishaudio_update_agent_config. Use fishaudio_get_knowledge_source to read one source's text.
Inputs
cursorstring- Cursor for the next page: pass the next_cursor value from the previous response while has_more is true. Do not combine with page.
include_totalboolean- Set to true to also return the total count when paging with cursor. Defaults to false.
pageinteger- 1-based page number for offset pagination; the response then includes total. Do not combine with cursor. Example: 2
page_sizeinteger- Number of results per page, 1 to 100. Defaults to 30.
searchstring- Text matched against source name and description. Example: pricing
fishaudio_list_my_voice_modelsList the voice models owned by your Fish Audio workspace, including private and unlisted ones.Read-onlyList My Voice Models
List the voice models owned by your Fish Audio workspace, including private and unlisted ones. Returns a page of voice models with _id, title, description, state, visibility, tags, languages and created_at, plus total. Use this for your own cloned or designed voices. Use fishaudio_search_voice_models to search the public library.
Inputs
page_numberinteger- 1-based page number. Defaults to 1.
page_sizeinteger- Number of voices per page, 1 to 100. Defaults to 10.
sort_bystring- Sort order: score (default), task_count (most used) or created_at (newest).one of
scoretask_countcreated_at titlestring- Text to match against your voice model titles. Example: brand voice
fishaudio_list_phone_numbersList your team's phone numbers, newest first, optionally filtered by number or bound agent.Read-onlyList Phone Numbers
List your team's phone numbers, newest first, optionally filtered by number or bound agent. Returns phone numbers with their ID, E.164 number, label, provider, bound agent and caller ID settings, plus has_more and next_cursor. Use this to get a phone_number_id for fishaudio_create_phone_call or to see which agent answers a number.
Inputs
agent_idstring- ID of the agent whose numbers to return, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
cursorstring- Cursor for the next page: pass the next_cursor value from the previous response while has_more is true. Do not combine with page.
include_totalboolean- Set to true to also return the total count when paging with cursor. Defaults to false.
pageinteger- 1-based page number for offset pagination; the response then includes total. Do not combine with cursor. Example: 2
page_sizeinteger- Number of results per page, 1 to 100. Defaults to 30.
phone_numberstring- Exact phone number in E.164 format. Example: +14155550123
fishaudio_search_voice_modelsSearch Fish Audio's public voice library by title, tag, language or author.Read-onlySearch Voice Models
Search Fish Audio's public voice library by title, tag, language or author. Returns a page of voice models with _id, title, description, tags, languages, author, visibility, like and usage counts, and sample audio links, plus total. Use this to find a voice to speak with. Use fishaudio_list_my_voice_models for voices your own workspace owns, and fishaudio_get_voice_model for one voice by ID.
Inputs
author_idstring- Only return public voices published by this author (the author._id field of a voice). Example: 4fc33e0b0d314efca22a5dcabebaa526
languagearray- Only return voices that speak these languages, as language codes. Example: ["en"]
licensedboolean- Set to true to return only voices Fish Audio has licensed from the voice owner. Defaults to false.
page_numberinteger- 1-based page number. Defaults to 1. The library only pages through its first 1000 matches.
page_sizeinteger- Number of voices per page, 1 to 100. Defaults to 10.
sort_bystring- Sort order: score (default, relevance and popularity), task_count (most used) or created_at (newest).one of
scoretask_countcreated_at tagarray- Only return voices that carry these tags. Example: ["male", "calm"]
titlestring- Text to match against voice model titles. Example: narrator
title_languagearray- Only return voices whose title is written in these languages, as language codes. Example: ["en"]
fishaudio_create_agentCreate a voice agent as a draft, optionally with its initial configuration.WriteCreate Agent
Create a voice agent as a draft, optionally with its initial configuration. Returns the new agent with agent_id, name, status and publication_state draft. Use this to start a new agent. Publish it with fishaudio_publish_agent before it can take calls; change settings later with fishaudio_update_agent_config.
Inputs
namestringrequired- Agent name, 1 to 120 characters. Example: Support Line Agent
configobject- Optional initial draft configuration, applied on top of the platform defaults. Configuration sections, each an object: prompt (system_prompt, first_message_mode off/fixed/prompt, first_message, first_message_prompt), voice (voice_id from a voice model, speaking_language, expressive, speed 0.5-2, tts_model s2.1-pro or drama-3), asr (speech recognition model, multilingual, keyterms), conversation (turn-taking, interruptions, max duration, recording, transfers), tools (tool_ids to attach, system tools), knowledge_base (knowledge_source_ids), llm (model), variables (default placeholder values), guardrails and analysis. Example: {"prompt": {"system_prompt": "You are a friendly support agent.", "first_message_mode": "fixed", "first_message": "Hi, how can I help?"}, "voice": {"voice_id": "802e3bc2b27e49c2995d23ef70e6ac89", "speaking_language": "en"}}
descriptionstring- Optional description, up to 2000 characters. Example: Answers billing questions for inbound callers.
fishaudio_create_agent_toolCreate a workspace tool that voice agents can call during conversations: a webhook to your HTTP endpoint, or a client tool your frontend runs.WriteCreate Agent Tool
Create a workspace tool that voice agents can call during conversations: a webhook to your HTTP endpoint, or a client tool your frontend runs. Returns the new tool with its ID and definition. Use this to give agents an action. Attach it with the tools.tool_ids field of fishaudio_update_agent_config, then fishaudio_publish_agent.
Inputs
namestringrequired- Tool name the agent sees, 1 to 120 characters. Example: lookup_order
argumentsarray- Arguments the agent fills in, each with a name (up to 64 characters) and description. Example: [{"name": "order_id", "description": "The customer's order ID"}]
body_templatestring- Request body for non-GET calls; {{argument}}, {{system.*}} and session variable placeholders are filled in at call time. Example: {"order_id": "{{order_id}}"}
content_typestring- Content type of the request body. Defaults to application/json.
descriptionstring- What the tool does and when the agent should call it, up to 2000 characters. Example: Look up an order's status by order ID.
error_handlingstring- passthrough (default) lets the agent see endpoint errors; hide hides them.one of
passthroughhide execution_modestring- blocking (default) waits for the result, fire_and_forget does not wait, background runs while the conversation continues.one of
blockingfire_and_forgetbackground expects_responseboolean- Whether the agent waits for and uses the endpoint's response. Defaults to true.
headersarray- Request headers, each with name, value and kind (custom, authorization_bearer or authorization_basic). Credential values are write-only. Example: [{"name": "Authorization", "value": "secret-token", "kind": "authorization_bearer"}]
methodstring- HTTP method for webhook tools. Defaults to POST.one of
GETPOSTPUTPATCHDELETE timeout_secondsinteger- Seconds to wait for your endpoint. Defaults to 30.
tool_typestring- webhook (default) calls your HTTP endpoint during the conversation; client is run by your own frontend through the SDK and has no URL.one of
webhookclient urlstring- Endpoint URL for webhook tools; may contain {{argument}} placeholders. Example: https://api.example.com/orders/{{order_id}}
fishaudio_create_phone_callPlace an outbound phone call in which a published voice agent talks to the person who answers.WriteCreate Phone Call
Place an outbound phone call in which a published voice agent talks to the person who answers. Returns session_id and status queued; the call dials in the background and is billed only once answered. Use this to have an agent call a number. Poll fishaudio_get_agent_session with the session_id for the outcome. Get phone_number_id from fishaudio_list_phone_numbers.
Inputs
agent_idstringrequired- ID of the published agent that will speak on the call, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
phone_number_idstringrequired- ID of the team-owned phone number to call from, from fishaudio_list_phone_numbers. Example: 7c9e6f2a4b8d4e1f9a3c5d7e8f0b1a2c
to_numberstringrequired- Number to call in E.164 format. Platform numbers dial US, Canada and Japan destinations. Example: +14155550123
dynamic_variablesobject- Values for {{placeholders}} in the agent's prompt and messages for this call, as a flat object of strings, numbers or booleans. Example: {"customer_name": "Dana", "order_id": "A-1042"}
idempotency_keystring- Retry-safe key: sending the same key with the same inputs within 24 hours returns the call already placed instead of dialing again. Example: call-a1042-1
metadataobject- Your own key-value data stored on the session. Example: {"crm_id": "0031x00000ABCDE"}
overridesobject- Per-call overrides of first_message, first_message_prompt, system_prompt, voice_id, language or asr; each must be allowed in the agent's overrides_allowed. Example: {"first_message": "Hi Dana, this is Acme calling about your order."}
fishaudio_design_voiceGenerate 1 to 4 candidate voices from a plain-language description, each speaking a short preview line.WriteDesign Voice
Generate 1 to 4 candidate voices from a plain-language description, each speaking a short preview line. Returns candidates, each with id, index, audio_base64 (the preview audio, base64-encoded), sample_rate, duration_ms, text and language. Use this to audition a new voice from a prompt; it creates no voice model and is billed once per request. Use fishaudio_search_voice_models to reuse an existing voice instead.
Inputs
instructionstringrequired- Description of the voice to create, 1 to 2000 characters: age, gender, accent, tone, pace, character. Example: Warm, confident studio narrator with a natural tone
guidance_scalenumber- How strongly generation follows the prompt, 0 or higher. Defaults to 2.
instruct_guidance_scalenumber- Extra guidance on the instruction text, 0 or higher. Defaults to 0.
languagestring- Language hint for the preview as a BCP-47 code, such as en, zh or ja. Example: en
ninteger- Number of candidate voices to generate, 1 to 4. Defaults to 2.
num_stepinteger- Diffusion steps used by the voice-design model, 1 to 128. More steps can improve quality and take longer. Defaults to 32.
reference_textstring- Preview line the candidate voices speak, up to 150 characters. Example: Welcome to Fish Audio.
seedinteger- Seed for reproducible candidates. Send the same seed and inputs to get similar results. Example: 42
speednumber- Speaking speed multiplier for the previews, above 0 and up to 3. Defaults to 1.
fishaudio_end_agent_sessionHang up a live voice agent session; the agent disconnects and the call ends.WriteEnd Agent Session
Hang up a live voice agent session; the agent disconnects and the call ends. Returns an empty object on success. The session record, transcript and recording stay readable. Use this to stop an active call. Use fishaudio_list_agent_sessions with status active to find live sessions.
Inputs
session_idstringrequired- Agent session ID, from fishaudio_list_agent_sessions or the session_id returned by fishaudio_create_phone_call. Example: 9b1d3f5a7c9e4b2d8f6a1c3e5b7d9f0a
fishaudio_publish_agentPublish a voice agent's current draft as a new immutable version and make it live for new sessions.WritePublish Agent
Publish a voice agent's current draft as a new immutable version and make it live for new sessions. Returns version_number, version_title, version_description, config_hash and published_at; if the draft already matches the live version, that version is returned unchanged. Use this after fishaudio_update_agent_config so calls use the new settings. Use fishaudio_list_agent_versions to see the history.
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
version_descriptionstring- Optional note for the new version, up to 2000 characters.
version_titlestring- Optional label for the new version, up to 120 characters. Example: Friendlier greeting
fishaudio_update_agentUpdate agent-level fields: name, description, status (active or archived), public browser access and allowed session overrides.WriteUpdate Agent
Update agent-level fields: name, description, status (active or archived), public browser access and allowed session overrides. Returns the updated agent profile. Use this for agent-level settings only. Use fishaudio_update_agent_config to change the voice, prompt or conversation behavior.
- Idempotent
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
allowed_originsarray- Web origins allowed to start public sessions, up to 20. Example: ["https://www.example.com"]
descriptionstring- New description, up to 2000 characters.
namestring- New name, 1 to 120 characters. Example: Support Line Agent v2
overrides_allowedarray- Session settings a caller may override when starting a session: first_message, system_prompt, voice_id, language, asr.model. An empty list rejects all overrides.
public_enabledboolean- Set to true to allow keyless sessions from the browser SDK, limited to allowed_origins.
statusstring- Set to archived to archive the agent, or active to restore it.one of
activearchived
fishaudio_update_agent_configPatch a voice agent's draft configuration section by section; sections you leave out keep their value.WriteUpdate Agent Config
Patch a voice agent's draft configuration section by section; sections you leave out keep their value. Returns the full updated draft configuration with its new config_hash. Use this to change the agent's voice, prompt, speech recognition, conversation behavior, tools or knowledge. Changes reach live calls only after fishaudio_publish_agent.
- Idempotent
Inputs
agent_idstringrequired- ID of the agent, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
analysisobject- Post-call analysis section: summary, data_fields (values to extract from each call) and criteria (success criteria to score). Example: {"summary": {"enabled": true}}
asrobject- Speech recognition section: model (deepgram:nova-3, elevenlabs:scribe_v2_realtime, elevenlabs:scribe_v2_medical or fish_audio:transcribe-stream-1), multilingual, strict_language, keyterms (up to 50 words to recognize). Example: {"model": "deepgram:nova-3", "keyterms": ["Acme", "refund"]}
conversationobject- Conversation section: turn-taking and call handling, for example max_duration_seconds, response_wait_ms, eagerness (relaxed, balanced, eager), interruptible, interruption_sensitivity (low, balanced, high), hangup_after_seconds, record_audio, timezone, transfer_destinations. Example: {"max_duration_seconds": 900, "eagerness": "balanced", "record_audio": true}
guardrailsobject- Guardrails section: focus (keep the agent on topic) and manipulation (resist prompt manipulation), both true/false. Example: {"focus": true, "manipulation": true}
knowledge_baseobject- Knowledge base section: enabled and knowledge_source_ids (replaces the attached sources; IDs from fishaudio_list_knowledge_sources). Example: {"enabled": true, "knowledge_source_ids": ["3e5a7c9b1d2f4e6a8c0b2d4f6a8c1e3b"]}
llmobject- Language model section: model, a platform model ID such as anthropic/claude-sonnet-4.6 or openai/gpt-4.1 (the vendor's current list is in the API reference). Example: {"model": "anthropic/claude-sonnet-4.6"}
promptobject- Prompt section: system_prompt (up to 32000 tokens; under 2000 recommended), first_message_mode (off, fixed or prompt), first_message, first_message_prompt. Example: {"system_prompt": "You are a friendly support agent for Acme.", "first_message_mode": "fixed", "first_message": "Hi, thanks for calling Acme!"}
toolsobject- Tools section: enabled, tool_ids (replaces the attached tool set; IDs from fishaudio_list_agent_tools) and system_tools. Example: {"enabled": true, "tool_ids": ["tool_8f2c4e6a1b3d"]}
variablesobject- Variables section: defaults (values for {{placeholders}} in the prompt when a session supplies none; the map is replaced as a whole) and on_missing (keep, empty or reject). Example: {"defaults": {"company": "Acme"}, "on_missing": "empty"}
voiceobject- Voice section: voice_id (any public voice model ID), speaking_language (ISO 639-1 code such as en), expressive (true/false), speed (0.5 to 2), tts_model (s2.1-pro or drama-3), pronunciation_dictionary_ids. Example: {"voice_id": "802e3bc2b27e49c2995d23ef70e6ac89", "speaking_language": "en", "speed": 1.1}
fishaudio_update_agent_toolUpdate fields of a voice agent tool; fields you leave out keep their value.WriteUpdate Agent Tool
Update fields of a voice agent tool; fields you leave out keep their value. Returns the updated tool. Attached agents' drafts pick up the change at once; published versions change only after re-publishing. Use this to change a tool's endpoint, arguments or headers. Use fishaudio_get_agent_tool to read it first.
- Idempotent
Inputs
tool_idstringrequired- Agent tool ID, from fishaudio_list_agent_tools. Example: tool_8f2c4e6a1b3d
argumentsarray- Arguments the agent fills in, each with a name (up to 64 characters) and description. Example: [{"name": "order_id", "description": "The customer's order ID"}]
body_templatestring- Request body for non-GET calls; {{argument}}, {{system.*}} and session variable placeholders are filled in at call time. Example: {"order_id": "{{order_id}}"}
content_typestring- Content type of the request body. Defaults to application/json.
descriptionstring- What the tool does and when the agent should call it, up to 2000 characters. Example: Look up an order's status by order ID.
error_handlingstring- passthrough (default) lets the agent see endpoint errors; hide hides them.one of
passthroughhide execution_modestring- blocking (default) waits for the result, fire_and_forget does not wait, background runs while the conversation continues.one of
blockingfire_and_forgetbackground expects_responseboolean- Whether the agent waits for and uses the endpoint's response. Defaults to true.
headersarray- Request headers, each with name, value and kind (custom, authorization_bearer or authorization_basic). Credential values are write-only. Sending this replaces the whole list, so include credential values again. Example: [{"name": "Authorization", "value": "secret-token", "kind": "authorization_bearer"}]
methodstring- HTTP method for webhook tools. Defaults to POST.one of
GETPOSTPUTPATCHDELETE namestring- Tool name the agent sees, 1 to 120 characters. Example: lookup_order
timeout_secondsinteger- Seconds to wait for your endpoint. Defaults to 30.
urlstring- Endpoint URL for webhook tools; may contain {{argument}} placeholders. Example: https://api.example.com/orders/{{order_id}}
fishaudio_update_phone_numberChange a phone number's label, the agent that answers its inbound calls, or its transfer caller ID.WriteUpdate Phone Number
Change a phone number's label, the agent that answers its inbound calls, or its transfer caller ID. Returns the updated phone number. Changes apply from the next call without publishing. Use this to point a number at another agent. Use fishaudio_list_agents to find the agent_id.
- Idempotent
Inputs
phone_number_idstringrequired- Phone number ID, from fishaudio_list_phone_numbers (the id field). Example: 7c9e6f2a4b8d4e1f9a3c5d7e8f0b1a2c
agent_idstring- ID of the agent that should answer this number's inbound calls, from fishaudio_list_agents; it must be in the number's workspace. Leave empty to keep the current binding (this tool cannot unbind a number). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
labelstring- New label for the number, up to 120 characters. Example: Main support line
retry_caller_id_syncboolean- Set to true to re-apply the caller ID setting after a failed sync (managed Twilio numbers only).
transfer_caller_idstring- Managed Twilio numbers only: the caller ID a transfer target sees, agent_number (this number) or original_caller (the caller's own number).one of
agent_numberoriginal_caller
fishaudio_update_voice_modelUpdate the title, description, visibility or tags of a voice model your workspace owns.WriteUpdate Voice Model
Update the title, description, visibility or tags of a voice model your workspace owns. Returns an empty object on success. Use this to rename or retag one of your voices. Use fishaudio_get_voice_model afterwards to read the result.
- Idempotent
Inputs
model_idstringrequired- Fish Audio voice model ID (the _id field from fishaudio_search_voice_models or fishaudio_list_my_voice_models). The same ID is the reference_id used for text-to-speech and the voice_id used in agent voice settings. Must be a model your workspace owns. Example: 802e3bc2b27e49c2995d23ef70e6ac89
descriptionstring- New description for the voice model. Example: Calm, mid-pitch narration voice for product videos.
tagsarray- Replacement list of tags. Example: ["narration", "calm"]
titlestring- New title for the voice model. Example: Brand Narrator v2
visibilitystring- Who can see the voice: private (only your workspace), unlist (anyone with the link) or public.one of
publicunlistprivate
fishaudio_delete_agentPermanently delete a voice agent with its configuration and version history; past session records are kept.DestructiveDelete Agent
Permanently delete a voice agent with its configuration and version history; past session records are kept. Returns an empty object on success. Use this to remove an agent for good. Use fishaudio_update_agent with status archived to hide it instead.
- Idempotent
Inputs
agent_idstringrequired- ID of the agent to delete, from fishaudio_list_agents or fishaudio_create_agent (the agent_id field). Example: 4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e
fishaudio_delete_agent_toolPermanently delete a voice agent tool.DestructiveDelete Agent Tool
Permanently delete a voice agent tool. Returns an empty object on success, or a 409 error while any agent's draft still uses the tool. Use this after detaching the tool from every agent with fishaudio_update_agent_config. Use fishaudio_list_agent_tools with agent_id to check.
- Idempotent
Inputs
tool_idstringrequired- Agent tool ID, from fishaudio_list_agent_tools. Example: tool_8f2c4e6a1b3d
fishaudio_delete_knowledge_sourcePermanently delete a knowledge source.DestructiveDelete Knowledge Source
Permanently delete a knowledge source. Returns an empty object on success, or a 409 error while any agent's draft or published version still uses it. Use this after removing the source from every agent with fishaudio_update_agent_config and re-publishing.
- Idempotent
Inputs
source_idstringrequired- Knowledge source ID, from fishaudio_list_knowledge_sources. Example: 3e5a7c9b1d2f4e6a8c0b2d4f6a8c1e3b
fishaudio_delete_voice_modelPermanently delete a voice model your workspace owns.DestructiveDelete Voice Model
Permanently delete a voice model your workspace owns. Returns an empty object on success. Use this only for your own voices; agents or apps that use this voice ID stop working with it.
- Idempotent
Inputs
model_idstringrequired- Fish Audio voice model ID (the _id field from fishaudio_search_voice_models or fishaudio_list_my_voice_models). The same ID is the reference_id used for text-to-speech and the voice_id used in agent voice settings. Must be a model your workspace owns. Example: 802e3bc2b27e49c2995d23ef70e6ac89
No tools match.
