The Cartesia connector lets your AI agent act in each user's Cartesia account. Each user connects their own Cartesia access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 39 tools.
- Tools
- 39
- What they doRead · write · destructive
- 30 · 6 · 330 read6 write3 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 Cartesia connection
In AgentKit > Connections, create a Cartesia 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 = 'cartesia'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Cartesia:', 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: 'cartesia_accents_list',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 = "cartesia"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Cartesia:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="cartesia_accents_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Cartesia credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolcartesia_accents_listList the accents Cartesia supports, optionally filtered by language, locale, or whether a voice can be localized into them.Read-onlyList Accents
List the accents Cartesia supports, optionally filtered by language, locale, or whether a voice can be localized into them. Returns accents, each with id, name, language, locale, is_locale_default and is_localizable. Use this to find a valid accent id for cartesia_voice_update or cartesia_voice_localize (localize needs is_localizable true).
Inputs
is_localizableboolean- Set to true to return only accents a voice can be localized into with cartesia_voice_localize. Example: true
languagestring- Return only accents of this ISO 639-1 language code. Example: es
localestring- Return only accents of this BCP-47 locale. Example: es-MX
cartesia_agent_getGet one Managed Agent with its complete current configuration.Read-onlyGet Agent
Get one Managed Agent with its complete current configuration. Returns id, name, description, version, created_at, updated_at and config (instructions, initial_message, audio, model, language, tools, system_tools, turn and other settings). Use this to read an agent's prompt, voice and model before changing it with cartesia_agent_update. Use cartesia_agent_versions_list for its change history.
Inputs
agent_idstringrequired- ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
cartesia_agent_models_listList the LLMs available to Cartesia Managed Agents, with latency and pricing metadata.Read-onlyList Agent Models
List the LLMs available to Cartesia Managed Agents, with latency and pricing metadata. Returns data (each model's id, display_name, provider, description, average_latency_ms and per-million-token pricing), has_more and next_page. Use this to choose the model_id for cartesia_agent_create or cartesia_agent_update. Use cartesia_models_list for speech (TTS/STT) models.
Inputs
ending_beforestring- Pagination cursor: the ID of the first model on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: gpt-5.4-mini
limitinteger- Number of models to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last model on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: gpt-5.4-mini
cartesia_agent_tool_getGet one shared agent tool (webhook or client) with its full definition.Read-onlyGet Agent Tool
Get one shared agent tool (webhook or client) with its full definition. Returns id, name, description, type, execution settings, and the webhook api_schema or client parameters; with expand agents, also the agents that use it. Use this to inspect what a tool does before attaching it to an agent. Use cartesia_agent_tools_list to find tool IDs.
Inputs
tool_idstringrequired- ID of the agent tool. Get it from cartesia_agent_tools_list. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
expandarray- Extra data to include. The only value is agents, which adds the agents that currently use the tool. Example: ["agents"]
cartesia_agent_tools_listList the shared webhook and client tools that Managed Agents in your account can call, optionally filtered by type or agent.Read-onlyList Agent Tools
List the shared webhook and client tools that Managed Agents in your account can call, optionally filtered by type or agent. Returns data (tools with id, name, description, type and settings), has_more and next_page. Use this to find a tool ID to reference in an agent's config.tools. Use cartesia_agent_tool_get for one tool's full definition.
Inputs
agent_idstring- Return only tools used by this agent, from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
ending_beforestring- Pagination cursor: the ID of the first tool on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
limitinteger- Number of tools to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last tool on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
typestring- Return only webhook tools or client tools. Example: webhookone of
webhookclient
cartesia_agent_version_getGet one immutable configuration version of an agent.Read-onlyGet Agent Version
Get one immutable configuration version of an agent. Returns id, description, created_at, created_by and the complete config of that version. Use this to compare or restore an older configuration: pass its config to cartesia_agent_update to roll back. Use cartesia_agent_get for the current configuration.
Inputs
agent_idstringrequired- ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
version_idstringrequired- ID of the agent configuration version. Get it from cartesia_agent_versions_list. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
cartesia_agent_versions_listList an agent's configuration history, newest first.Read-onlyList Agent Versions
List an agent's configuration history, newest first. Each version is an immutable snapshot of the full configuration. Returns data (versions with id, description, created_at and created_by), has_more and next_page. Use this to audit or roll back agent changes. Use cartesia_agent_version_get for one version's full config.
Inputs
agent_idstringrequired- ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
ending_beforestring- Pagination cursor: the ID of the first version on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
limitinteger- Number of versions to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last version on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
cartesia_agents_listList the Managed Agents in your Cartesia account, optionally searching by name or description.Read-onlyList Agents
List the Managed Agents in your Cartesia account, optionally searching by name or description. Returns data (agent summaries with id, name, description and timestamps; full configuration is left out), has_more and next_page. Use this to find an agent_id. Use cartesia_agent_get for one agent's full configuration.
Inputs
ending_beforestring- Pagination cursor: the ID of the first agent on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
limitinteger- Number of agents to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
qstring- Text to match against agent name or description. Example: receptionist
starting_afterstring- Pagination cursor: the ID of the last agent on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
cartesia_call_batch_getGet one outbound call batch and the current status of each recipient.Read-onlyGet Call Batch
Get one outbound call batch and the current status of each recipient. Returns id, name, agent_id, from_number_id, status, scheduling and concurrency settings, scheduled/dispatched/finished call counts, retry_count, timestamps and recipients. Use this to track a calling campaign. Use cartesia_calls_list with batch_id for the resulting calls and transcripts.
Inputs
batch_idstringrequired- ID of the call batch. Get it from cartesia_call_batches_list. Example: batch_8c1d2e3f4a5b
cartesia_call_batches_listList outbound call batches (bulk calling campaigns), optionally for one agent.Read-onlyList Call Batches
List outbound call batches (bulk calling campaigns), optionally for one agent. Returns data (batches with id, name, agent_id, status, call counts and timestamps), has_more and next_page. Use this to find a batch_id and see campaign progress. Use cartesia_call_batch_get for per-recipient status and cartesia_calls_list with batch_id for the calls.
Inputs
agent_idstring- Return only batches for this agent, from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
ending_beforestring- Pagination cursor: the ID of the first batch on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: batch_8c1d2e3f4a5b
limitinteger- Number of batches to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last batch on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: batch_8c1d2e3f4a5b
cartesia_call_getGet one Managed Agent call with its transcript.Read-onlyGet Call
Get one Managed Agent call with its transcript. Returns id, agent_id, agent_name, agent_version_id, status, start_time, end_time, end_reason, error_message, summary, transcript, telephony_params, dynamic_variables and zdr_enabled. Use this to read what was said on a call and how it ended. Use cartesia_calls_list to find call IDs and cartesia_metric_results_list for its evaluation scores.
Inputs
call_idstringrequired- ID of the call. Get it from cartesia_calls_list. Example: call_2b7e4f9a1c0d
cartesia_calls_listList the calls of one Managed Agent, or the calls placed for one outbound call batch, optionally in a time range.Read-onlyList Calls
List the calls of one Managed Agent, or the calls placed for one outbound call batch, optionally in a time range. Pass agent_id or batch_id. Returns data (calls with id, agent_id, status, start_time, end_time, end_reason, summary and telephony details; transcript when expanded), has_more and next_page. Use this to review an agent's recent calls. Use cartesia_call_get for one call's full transcript and details.
Inputs
agent_idstring- Agent whose calls to list, from cartesia_agents_list. Required unless batch_id is set. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
batch_idstring- Outbound call batch whose calls to list, from cartesia_call_batches_list. Required unless agent_id is set. Returns one entry per call attempt, so a retried recipient can appear more than once. Example: batch_8c1d2e3f4a5b
ending_beforestring- Pagination cursor: the ID of the first call on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: call_2b7e4f9a1c0d
expandstring- Set to transcript to include each call's transcript. Transcripts can make the response large. Example: transcriptone of
transcript limitinteger- Number of calls to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
start_time_gtestring- Only calls that started at or after this RFC 3339 timestamp. Example: 2026-10-01T00:00:00Z
start_time_ltestring- Only calls that started at or before this RFC 3339 timestamp. Example: 2026-10-21T23:59:59Z
starting_afterstring- Pagination cursor: the ID of the last call on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: call_2b7e4f9a1c0d
cartesia_dataset_files_listList the audio files in a dataset.Read-onlyList Dataset Files
List the audio files in a dataset. Returns data (files with id, filename, size and created_at), has_more and next_page. Use this to check what a dataset holds before fine-tuning. Use cartesia_file_get for one file's metadata.
Inputs
dataset_idstringrequired- ID of the dataset. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d
ending_beforestring- Pagination cursor: the ID of the first file on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: file_EneDabCuJCpfe5CFi5X12e
limitinteger- Number of files to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last file on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: file_EneDabCuJCpfe5CFi5X12e
cartesia_dataset_getGet one dataset by ID.Read-onlyGet Dataset
Get one dataset by ID. Returns id, name, description and created_at. Use this to check a dataset's details. Use cartesia_dataset_files_list for the files in it.
Inputs
dataset_idstringrequired- ID of the dataset. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d
cartesia_datasets_listList the datasets in your Cartesia account.Read-onlyList Datasets
List the datasets in your Cartesia account. Datasets group audio files used to fine-tune voices. Returns data (datasets with id, name, description and created_at), has_more and next_page. Use this to find a dataset_id. Use cartesia_dataset_get for one dataset and cartesia_dataset_files_list for its files.
Inputs
ending_beforestring- Pagination cursor: the ID of the first dataset on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: dataset_9b2f4e7a1c3d
limitinteger- Number of datasets to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last dataset on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: dataset_9b2f4e7a1c3d
cartesia_file_getGet one uploaded file's metadata (not its content).Read-onlyGet File
Get one uploaded file's metadata (not its content). Returns id, filename, purpose, size, status, owner_id and created_at. Use this to check a file's processing status or purpose. Use cartesia_files_list to find file IDs.
Inputs
file_idstringrequired- ID of the file. Get it from cartesia_files_list or cartesia_dataset_files_list. Example: file_EneDabCuJCpfe5CFi5X12e
cartesia_files_listList files uploaded to your Cartesia account, optionally by purpose or filename.Read-onlyList Files
List files uploaded to your Cartesia account, optionally by purpose or filename. Returns data (files with id, filename, purpose, size, status and created_at) and has_more. Use this to find a file ID, for example an agent background sound or a fine-tune sample. Use cartesia_file_get for one file.
Inputs
ending_beforestring- Pagination cursor: the ID of the first file on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: file_EneDabCuJCpfe5CFi5X12e
limitinteger- Number of files to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
purposestring- Return only files uploaded for this purpose: agent_background_sound, fine_tune, tts_generation or voice-clone. Example: fine_tuneone of
agent_background_soundfine_tunetts_generationvoice-clone qstring- Return only files whose filename contains this text. Example: intro
starting_afterstring- Pagination cursor: the ID of the last file on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: file_EneDabCuJCpfe5CFi5X12e
cartesia_fine_tune_getGet one voice fine-tune by ID.Read-onlyGet Fine-Tune
Get one voice fine-tune by ID. Returns id, name, description, language, accent, model_id, supported_model_ids, dataset, status and user_errors. Use this to check whether a fine-tune has finished or failed. Use cartesia_fine_tune_voices_list for the voices it produced.
Inputs
fine_tune_idstringrequired- ID of the fine-tune. Get it from cartesia_fine_tunes_list. Example: fine_tune_4c7e1a9b2d5f
cartesia_fine_tune_voices_listList the voices created by a completed fine-tune.Read-onlyList Fine-Tune Voices
List the voices created by a completed fine-tune. Returns data (voices with id, name, description, language and created_at), has_more and next_page. Use this to get the voice IDs a fine-tune produced. Use cartesia_voice_get for one voice's details.
Inputs
fine_tune_idstringrequired- ID of the fine-tune. Get it from cartesia_fine_tunes_list. Example: fine_tune_4c7e1a9b2d5f
ending_beforestring- Pagination cursor: the ID of the first voice on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: a0e99841-438c-4a64-b679-ae501e7d6091
limitinteger- Number of voices to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last voice on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: a0e99841-438c-4a64-b679-ae501e7d6091
cartesia_fine_tunes_listList the voice fine-tunes in your Cartesia account.Read-onlyList Fine-Tunes
List the voice fine-tunes in your Cartesia account. Returns data (fine-tunes with id, name, description, language, model_id, dataset and status), has_more and next_page. Use this to track fine-tuning jobs. Use cartesia_fine_tune_get for one job and cartesia_fine_tune_voices_list for the voices it produced.
Inputs
ending_beforestring- Pagination cursor: the ID of the first fine-tune on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: fine_tune_4c7e1a9b2d5f
limitinteger- Number of fine-tunes to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last fine-tune on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: fine_tune_4c7e1a9b2d5f
cartesia_metric_getGet one LLM-as-a-judge metric.Read-onlyGet Metric
Get one LLM-as-a-judge metric. Returns id, name, display_name, the judge prompt and created_at. Use this to read how a metric scores calls. Use cartesia_metric_results_list for its results.
Inputs
metric_idstringrequired- ID of the metric. Get it from cartesia_metrics_list. Example: metric_5e8b2c1a9d7f
cartesia_metric_results_listList metric results, the scores LLM-as-a-judge metrics gave to agent calls, filtered by agent, metric, call, deployment or date.Read-onlyList Metric Results
List metric results, the scores LLM-as-a-judge metrics gave to agent calls, filtered by agent, metric, call, deployment or date. Returns data (results with id, metric, call and agent IDs, the value and created_at), has_more and next_page. Use this to analyze call quality over time. Use cartesia_call_get to read the call behind a result.
Inputs
agent_idstring- Return only results for this agent. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
call_idstring- Return only results for this call. Example: call_2b7e4f9a1c0d
deployment_idstring- Return only results for this agent deployment. Example: dep_4b8e2a6c1f9d
end_datestring- Only results created at or before this RFC 3339 datetime. Example: 2026-10-21T23:59:59Z
ending_beforestring- Pagination cursor: the ID of the first metric result on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: metric_result_3f9a2c7e1b5d
limitinteger- Number of metric results to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
metric_idstring- Return only results of this metric, from cartesia_metrics_list. Example: metric_5e8b2c1a9d7f
start_datestring- Only results created at or after this RFC 3339 datetime. Example: 2026-10-01T00:00:00Z
starting_afterstring- Pagination cursor: the ID of the last metric result on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: metric_result_3f9a2c7e1b5d
cartesia_metrics_listList the LLM-as-a-judge metrics in your account that score agent calls.Read-onlyList Metrics
List the LLM-as-a-judge metrics in your account that score agent calls. Returns data (metrics with id, name, display_name, prompt and created_at), has_more and next_page. Use this to find a metric_id. Use cartesia_metric_results_list for the scores a metric gave to calls.
Inputs
limitinteger- Number of metrics to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last metric on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: metric_5e8b2c1a9d7f
cartesia_models_listList the Sonic text-to-speech and Ink speech-to-text model IDs your Cartesia key can call.Read-onlyList Models
List the Sonic text-to-speech and Ink speech-to-text model IDs your Cartesia key can call. Returns data, an array of models with id, capability (tts or stt) and, for STT models, the supported modes. Use this to pick a model_id for speech or transcription settings. Use cartesia_agent_models_list for the LLMs that power Managed Agents.
Inputs
capabilitystring- Return only text-to-speech (tts) or speech-to-text (stt) models. Omit to return both. Example: ttsone of
ttsstt
cartesia_phone_number_getGet one phone number in your Cartesia account.Read-onlyGet Phone Number
Get one phone number in your Cartesia account. Returns the number's id, phone number, label, provider type and the agent it routes to. Use this to check how a number is set up. Use cartesia_phone_numbers_list to find number IDs.
Inputs
phone_number_idstringrequired- ID of the phone number. Get it from cartesia_phone_numbers_list. Example: pn_7f3a9c2e1b4d
cartesia_phone_numbers_listList the phone numbers in your Cartesia account, optionally filtered by assigned agent, telephony provider or search text.Read-onlyList Phone Numbers
List the phone numbers in your Cartesia account, optionally filtered by assigned agent, telephony provider or search text. Returns data (numbers with id, the phone number, label, provider type and assigned agent) and has_more. Use this to see which number routes to which agent. Use cartesia_phone_number_get for one number's details.
Inputs
agent_idstring- Return only numbers assigned to this agent. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
ending_beforestring- Pagination cursor: the ID of the first phone number on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: pn_7f3a9c2e1b4d
limitinteger- Number of phone numbers to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
provider_idstring- Return only numbers from this linked telephony provider account. Example: prov_2d8f1a7c9e3b
qstring- Text to match against the phone number, its label or the agent name. Example: +1415
starting_afterstring- Pagination cursor: the ID of the last phone number on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: pn_7f3a9c2e1b4d
typestring- Return only numbers of this provider type: twilio, cartesia or sip_trunk. Example: cartesiaone of
twiliocartesiasip_trunk
cartesia_pronunciation_dict_getGet one pronunciation dictionary with its entries.Read-onlyGet Pronunciation Dictionary
Get one pronunciation dictionary with its entries. Returns id, name, description, access, pinned, created_at and items (each word with the pronunciation to use). Use this to see how a dictionary changes pronunciation. Use cartesia_pronunciation_dicts_list to find dictionary IDs.
Inputs
dict_idstringrequired- ID of the pronunciation dictionary. Get it from cartesia_pronunciation_dicts_list. Example: dict_6a1f3c8e2b9d
cartesia_pronunciation_dicts_listList the pronunciation dictionaries in your Cartesia account.Read-onlyList Pronunciation Dictionaries
List the pronunciation dictionaries in your Cartesia account. They tell Cartesia how to say specific words, names or acronyms. Returns data (dictionaries with id, name, description, access, pinned and created_at), has_more and next_page. Use this to find a dictionary ID for an agent's config.audio.output.pronunciation_dictionary_id. Use cartesia_pronunciation_dict_get for its entries.
Inputs
ending_beforestring- Pagination cursor: the ID of the first dictionary on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: dict_6a1f3c8e2b9d
limitinteger- Number of dictionaries to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
starting_afterstring- Pagination cursor: the ID of the last dictionary on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: dict_6a1f3c8e2b9d
cartesia_voice_getGet one Cartesia voice by its ID.Read-onlyGet Voice
Get one Cartesia voice by its ID. Returns the voice's id, name, tagline, description, language, gender, accents, country, is_pro, is_owner, access, status and created_at, plus preview_file_url when expanded. Use this to check a voice before using it in an agent or updating it. Use cartesia_voices_list to search when you do not have the ID.
Inputs
voice_idstringrequired- ID of the voice. Get it from cartesia_voices_list. Example: a0e99841-438c-4a64-b679-ae501e7d6091
expandarray- Extra fields to include. The only value is preview_file_url, which adds a URL to download a short preview clip of each voice (downloading it does not use credits). Example: ["preview_file_url"]
cartesia_voices_listList or search Cartesia voices, including the public voice library and voices your organization owns.Read-onlyList Voices
List or search Cartesia voices, including the public voice library and voices your organization owns. Returns data (each voice's id, name, tagline, description, language, gender, accents, is_owner, access, status and created_at), has_more and next_page. Use this to find a voice ID by name, language or gender. Use cartesia_voice_get for one voice you already have the ID of.
Inputs
ending_beforestring- Pagination cursor: the ID of the first voice on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: a0e99841-438c-4a64-b679-ae501e7d6091
expandarray- Extra fields to include. The only value is preview_file_url, which adds a URL to download a short preview clip of each voice (downloading it does not use credits). Example: ["preview_file_url"]
genderstring- Return only voices with this gender presentation: masculine, feminine or gender_neutral. Example: feminineone of
masculinefemininegender_neutral include_archivedboolean- Set to true to also return archived voices. Defaults to false. Example: true
is_ownerboolean- Set to true to return only voices your organization owns (clones, localized voices). Example: true
languagestring- Return only voices for a language (en) or a language-locale pair (en-GB). Example: en
limitinteger- Number of voices to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
qstring- Text to match against voice name, description or voice ID. Example: narrator
starting_afterstring- Pagination cursor: the ID of the last voice on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: a0e99841-438c-4a64-b679-ae501e7d6091
cartesia_agent_createCreate a Cartesia Managed Agent (a hosted voice agent) and its first configuration version.WriteCreate Agent
Create a Cartesia Managed Agent (a hosted voice agent) and its first configuration version. Returns the new agent's id, name, description, version and full config. Use this to set up a new voice agent. Set instructions, voice_id and model_id for a working agent; get IDs from cartesia_voices_list and cartesia_agent_models_list. Use cartesia_agent_update to change an existing agent.
Inputs
namestringrequired- Name shown for the agent. It does not need to be unique. Example: Acme Dental Receptionist
configobject- Advanced agent configuration, sent as the config object. Use it for settings not covered by the fields above: audio (input keyterms and noise_suppression; output speed, volume, emotion, pronunciation_dictionary_id and background_sound), model (fallback_strategy, temperature, max_output_tokens), system_tools (end_call, send_dtmf, transfer_to_number), tools (references to tool IDs from cartesia_agent_tools_list), turn (inactivity timeouts), timezone, prompt_optimization, speculative_generation and dynamic_variable_placeholders. The instructions, initial_message, voice_id, model_id and language fields above are merged into this object and win on conflict. Example: {"audio": {"output": {"speed": 1.1}}, "model": {"temperature": 0.4}, "timezone": "America/New_York", "system_tools": {"end_call": {"pre_tool_speech": "auto"}}}
descriptionstring- Description of the agent. Example: Books and reschedules dental appointments.
initial_messagestring- What the agent says when the call starts. Sent as config.initial_message. Example: Hi, thanks for calling Acme Dental. How can I help?
instructionsstring- System prompt that defines how the agent behaves. Supports dynamic variables such as {{customer_name}}. Sent as config.instructions. Example: You are a friendly receptionist for Acme Dental. Help callers book appointments.
languagestring- ISO 639-1 code of the language the agent hears and speaks. Sent as config.language.primary. Example: enone of
endeptzhjafreshiitkonlplrusvtrtlbgroarcselfihrmsskdataukhunovibnthhekaidteguknmlmrpaorur model_idstring- LLM that powers the agent, from cartesia_agent_models_list. Sent as config.model.id. Example: gpt-5.4-mini
voice_idstring- Voice the agent speaks with, from cartesia_voices_list. Sent as config.audio.output.voice_id. Example: a0e99841-438c-4a64-b679-ae501e7d6091
cartesia_agent_updateUpdate a Managed Agent's name, description or configuration.WriteUpdate Agent
Update a Managed Agent's name, description or configuration. Only the fields you set change; any configuration change creates a new immutable version. Returns the updated agent with its new version and full config. Use this to change an agent's prompt, voice, model or language. Read the current config first with cartesia_agent_get. To roll back, pass the config of a version from cartesia_agent_version_get.
- Idempotent
Inputs
agent_idstringrequired- ID of the agent to update. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
configobject- Advanced agent configuration, sent as the config object. Use it for settings not covered by the fields above: audio (input keyterms and noise_suppression; output speed, volume, emotion, pronunciation_dictionary_id and background_sound), model (fallback_strategy, temperature, max_output_tokens), system_tools (end_call, send_dtmf, transfer_to_number), tools (references to tool IDs from cartesia_agent_tools_list), turn (inactivity timeouts), timezone, prompt_optimization, speculative_generation and dynamic_variable_placeholders. The instructions, initial_message, voice_id, model_id and language fields above are merged into this object and win on conflict. Example: {"audio": {"output": {"speed": 1.1}}, "model": {"temperature": 0.4}, "timezone": "America/New_York", "system_tools": {"end_call": {"pre_tool_speech": "auto"}}}
descriptionstring- New agent description. Example: Books, moves and cancels dental appointments.
initial_messagestring- What the agent says when the call starts. Sent as config.initial_message. Example: Hi, thanks for calling Acme Dental. How can I help?
instructionsstring- System prompt that defines how the agent behaves. Supports dynamic variables such as {{customer_name}}. Sent as config.instructions. Example: You are a friendly receptionist for Acme Dental. Help callers book appointments.
languagestring- ISO 639-1 code of the language the agent hears and speaks. Sent as config.language.primary. Example: enone of
endeptzhjafreshiitkonlplrusvtrtlbgroarcselfihrmsskdataukhunovibnthhekaidteguknmlmrpaorur model_idstring- LLM that powers the agent, from cartesia_agent_models_list. Sent as config.model.id. Example: gpt-5.4-mini
namestring- New agent name. Example: Acme Dental Receptionist v2
version_descriptionstring- Note to attach to the new configuration version. Only allowed when this request changes the configuration. Example: Shorter greeting
voice_idstring- Voice the agent speaks with, from cartesia_voices_list. Sent as config.audio.output.voice_id. Example: a0e99841-438c-4a64-b679-ae501e7d6091
cartesia_dataset_createCreate an empty dataset to hold audio files for fine-tuning a voice.WriteCreate Dataset
Create an empty dataset to hold audio files for fine-tuning a voice. Returns the new dataset's id, name, description and created_at. Use this as the first step of a fine-tune. Audio files are added outside this connector (file upload is not supported). Use cartesia_dataset_update to rename it.
Inputs
namestringrequired- Name for the new dataset. Example: Support voice recordings
descriptionstring- Description of the dataset. Sent as an empty string when left empty. Example: Studio recordings of our support voice actor.
cartesia_dataset_updateReplace a dataset's name and description.WriteUpdate Dataset
Replace a dataset's name and description. Both are required; pass the current value for the one you keep. Returns an empty object on success. Use this to rename or redescribe a dataset. Read the current values with cartesia_dataset_get first.
- Idempotent
Inputs
dataset_idstringrequired- ID of the dataset to update. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d
descriptionstringrequired- New description for the dataset. Example: Cleaned studio recordings of our support voice actor.
namestringrequired- New name for the dataset. Example: Support voice recordings v2
cartesia_voice_localizeCreate a new voice that sounds like an existing voice speaking natively in another accent.WriteLocalize Voice
Create a new voice that sounds like an existing voice speaking natively in another accent. The original voice is not changed. Returns the new voice's id, name, tagline, description, language, access and created_at. Use this to get a speaker in another accent or language. Use cartesia_accents_list with is_localizable true to pick the accent. Use cartesia_voice_update to only relabel a voice.
Inputs
accentstringrequired- Accent to localize into, as an accent id from cartesia_accents_list with is_localizable true. The accent decides the new voice's language. Example: mexicanone of
australianbrazilian-portuguesebritishbulgariancanadian-frenchcastiliancentral-tamilcentral-thaiczechdanisheuropean-portuguesegeneral-americanindian-englishindian-urduisraeliistanbulkonkanikoreanmandarinmanilamexicanmodern-standard-arabicnorth-keralaodiaosloparisianparsipolishpowadhirandstadrussianslovaksouthern-karnatakasouthern-usstandard-germanstandard-hindistandard-indonesianstandard-italianstandard-japanesestockholmtaiwanese-mandarintelangana namestringrequired- Name for the new localized voice. Example: Support Narrator (Mexican Spanish)
voice_idstringrequired- ID of the existing voice to localize. Get it from cartesia_voices_list. Example: a0e99841-438c-4a64-b679-ae501e7d6091
accessstring- Who can use the new voice: private (your organization only) or public. Example: privateone of
privatepublic descriptionstring- Description for the new voice. Example: Mexican Spanish version of our support voice.
taglinestring- Short tagline for the new voice, at most 32 characters. Example: Warm and steady
cartesia_voice_updateUpdate the name, tagline, description, gender, accent or access of a voice your organization owns.WriteUpdate Voice
Update the name, tagline, description, gender, accent or access of a voice your organization owns. Only the fields you set change. Returns the updated voice. Use this to rename or relabel your own voice. Use cartesia_voice_localize to make a new voice in another accent instead of relabeling this one.
- Idempotent
Inputs
voice_idstringrequired- ID of the voice to update (it must be one your organization owns). Get it from cartesia_voices_list with is_owner true. Example: a0e99841-438c-4a64-b679-ae501e7d6091
accentstring- Accent label for the voice, as an accent id from cartesia_accents_list. It must be valid for the voice's language. Example: britishone of
abruzzo-italianafrican-americanafrican-frencharabic-englishargentinianaustralianaustrian-germanbaghelibelgian-dutchbelgian-frenchbrazilian-portuguesebritishbudapestbulgariancaliforniacambacampaniacanadian-englishcanadian-frenchcastiliancentral-tamilcentral-thaicentral-vietnamesechileancolombianczechdanishdominicanemirati-arabiceuropean-portuguesefinnishgeneral-americanindian-bengaliindian-englishindian-urduirishisraeliistanbuljessorekhaleejikonkanikoreankyivmalaymandarinmanilamexicanmiddle-eastern-arabicmidwestern-americanmodern-standard-arabicmoldovannew-yorknew-zealandnorth-keralaodiaoslopanamanianparisianparsiperuvianphilippine-englishpolishpowadhipuerto-ricanrandstadromanianrussiansingaporeanslovaksouth-africansouthern-karnatakasouthern-ussouthern-vietnamesestandard-germanstandard-hindistandard-indonesianstandard-italianstandard-japanesestockholmswiss-standardtaiwanese-mandarintbilisitelanganathessalonikiunited-states-spanishurduzagreb accessstring- Who can use the voice: private (your organization only) or public (any Cartesia user with the voice ID). Example: privateone of
privatepublic descriptionstring- Longer description of the voice. Example: Calm mid-pitch voice for customer support calls.
genderstring- Gender presentation label: masculine, feminine or gender_neutral. Leave empty to keep the current value. Example: feminineone of
masculinefemininegender_neutral namestring- New display name for the voice. Example: Support Narrator
taglinestring- A few words describing the voice, at most 32 characters. Example: Warm and steady
cartesia_agent_deletePermanently delete a Managed Agent.DestructiveDelete Agent
Permanently delete a Managed Agent. Later reads fail and the agent takes no new calls; phone numbers assigned to it stop reaching it. Returns an empty object on success. Use this only to remove an agent for good. Use cartesia_agent_update to change an agent instead.
- Idempotent
Inputs
agent_idstringrequired- ID of the agent to delete. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
cartesia_dataset_deletePermanently delete a dataset.DestructiveDelete Dataset
Permanently delete a dataset. Returns an empty object on success. Use this to remove a dataset you no longer need for fine-tuning. Use cartesia_dataset_update to rename it instead.
- Idempotent
Inputs
dataset_idstringrequired- ID of the dataset to delete. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d
cartesia_voice_deletePermanently delete a voice your organization owns.DestructiveDelete Voice
Permanently delete a voice your organization owns. Agents or apps that use this voice ID stop working with it. Returns an empty object on success. Use this only to remove your own cloned or localized voices. Use cartesia_voice_update to rename or relabel a voice instead.
- Idempotent
Inputs
voice_idstringrequired- ID of the voice to delete (it must be one your organization owns). Get it from cartesia_voices_list with is_owner true. Example: a0e99841-438c-4a64-b679-ae501e7d6091
No tools match.