Agents

Create and manage voice agents over REST: configure prompts, engines, voices, languages, tools, and knowledge, then deploy, duplicate, transfer, or version them.

An agent is the configuration that drives every ThunderPhone call — the product tier, the voice, the languages, the system prompt, the acknowledgement behavior, silence/voicemail handling, the attached tools and knowledge, and whether the agent is reachable from the web widget. Phone numbers assign an inbound and/or outbound agent; outbound calls and mic sessions can target an agent directly.

Agents use a draft / deploy workflow: edits made via PATCH/PUT are saved as a draft and do not affect production calls until you POST /deploy. Test calls and mic sessions run against the draft (when one exists) so you can try changes before shipping them.

For dashboard setup, see Voice agent settings. For prompt-callable actions, see Built-in tools and Transfer calls.

Endpoints#

Related agent-scoped surfaces documented on their own pages: test scenarios & suites, split testing (A/B variants).

Agent object#

{
  "id": 12,
  "name": "Customer Support Agent",
  "prompt": "You are a helpful support agent for Acme Ops…",
  "voice": "john",
  "primary_language": "en",
  "additional_languages": [],
  "native_voice_switching": false,
  "language_switching": "ask_first",
  "product": "spark",
  "thinking_level": "base",
  "background_track": "NONE",
  "acknowledgement_prompt_mode": "auto",
  "acknowledgement_prompt": "",
  "acknowledgement_feedback_mode": "acknowledgement",
  "inbound_speak_order": "agent_first",
  "outbound_speak_order": "caller_first",
  "voicemail_action": "prompt",
  "voicemail_message": "",
  "silence_interval_seconds": 15,
  "silence_max_checkins": 3,
  "silence_checkins_enabled": true,
  "silence_hangup_seconds": 600,
  "max_call_duration_seconds": 3600,
  "ring_duration_seconds": null,
  "connect_tone_enabled": false,
  "typing_sounds_enabled": false,
  "typing_sound": "keys_and_mouse",
  "filler_phrases_enabled": true,
  "tool_start_line": "always",
  "play_sound_asset": "",
  "intro_clip": "none",
  "intro_clip_artifact_path": "",
  "intro_clip_sha256": "",
  "intro_ring_count": 1,
  "speak_uninterruptible_enabled": false,
  "send_email_enabled": false,
  "send_email_recipient": "",
  "calculator_enabled": false,
  "transfer_destinations": [
    {"name": "Billing", "number": "+14155552671", "platform_ok": true},
    {"name": "Assigned rep", "number": "{{rep_phone}}", "platform_ok": null}
  ],
  "warm_transfer_style": "introduce",
  "warm_transfer_briefing": "",
  "consent_announcement_enabled": true,
  "consent_announcement_text": "This call may be recorded…",
  "consent_disabled_reason": "",
  "audio_context_mode": "full",
  "watchdog_enabled": false,
  "additional_audio_context": null,
  "extraction_fields": [
    {
      "key": "insurance_type",
      "type": "enum",
      "description": "Insurance type requested by the caller",
      "options": ["term", "whole"],
      "required": false,
      "ask": true
    }
  ],
  "extraction_blocks_completion": "except_transfers",
  "call_summary_enabled": false,
  "outcome_labels": [],
  "report_instructions": "",
  "timezone": "America/New_York",
  "business_hours": null,
  "reusable_instructions": [],
  "integrations": [],
  "knowledge_bases": [],
  "knowledge_documents": [],
  "mcp_servers": [],
  "tool_collision_warnings": [],
  "widget_enabled": true,
  "split_testing_enabled": false,
  "steps": null,
  "handoffs": [],
  "warnings": [],
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "draft_prompt": null,
  "draft_voice": null,
  "draft_consent_announcement_enabled": null,
  "draft_updated_at": null,
  "has_draft": false
}

Deployed fields#

Draft fields#

Every configurable field above has a draft_* mirror in the response (draft_name, draft_prompt, draft_voice, draft_primary_language, draft_additional_languages, draft_native_voice_switching, draft_language_switching, draft_product, draft_background_track, draft_thinking_level, draft_acknowledgement_prompt_mode, draft_acknowledgement_prompt, draft_acknowledgement_feedback_mode, draft_inbound_speak_order, draft_outbound_speak_order, draft_voicemail_action, draft_voicemail_message, draft_silence_interval_seconds, draft_silence_max_checkins, draft_silence_checkins_enabled, draft_silence_hangup_seconds, draft_max_call_duration_seconds, draft_ring_duration_seconds, draft_connect_tone_enabled, draft_typing_sounds_enabled, draft_typing_sound, draft_filler_phrases_enabled, draft_tool_start_line, draft_play_sound_asset, draft_intro_clip, draft_intro_clip_artifact_path, draft_intro_clip_sha256, draft_intro_ring_count, draft_speak_uninterruptible_enabled, draft_send_email_enabled, draft_send_email_recipient, draft_calculator_enabled, draft_send_sms_enabled, draft_sms_from_number, draft_sms_allow_other_recipients, draft_sms_allowed_recipients, draft_transfer_destinations, draft_warm_transfer_style, draft_warm_transfer_briefing, draft_sms_followup_enabled, draft_sms_followup_template, draft_consent_announcement_enabled, draft_consent_announcement_text, draft_audio_context_mode, draft_watchdog_enabled, draft_additional_audio_context, draft_extraction_fields, draft_extraction_blocks_completion, draft_call_summary_enabled, draft_outcome_labels, draft_report_instructions, draft_timezone, draft_business_hours, draft_reusable_instruction_ids, draft_widget_enabled, draft_split_testing_enabled, draft_steps, draft_handoffs), plus draft id lists for attachments (draft_integration_ids, draft_knowledge_base_ids, draft_knowledge_document_ids, draft_mcp_server_ids) and two read-only markers:

draft_max_call_duration_seconds is read-only: null means unchanged, and 0 means a pending removal of the cap. Stage removal by sending "max_call_duration_seconds": null; deployment restores the live value to null.

draft_ring_duration_seconds follows the same read-only draft convention: null means unchanged and 0 stages clearing the setting. Write "ring_duration_seconds": null to restore platform defaults on deployment. Public writes must be null or 5–120.

To turn a stepped agent back into a single-prompt agent, send "steps": null. While that change is pending the response shows "draft_steps": {}, which means "no steps on deploy". Send the text from steps/flatten as prompt in the same request to keep the steps' instructions.

To restore the organization's business hours, send "business_hours": null. When this clears an existing override, the response shows "draft_business_hours": {"__inherit__": true} until deployment. That marker means "inherit on deploy"; it is not a weekday schedule. Send "timezone": "" too to go back to the automatic time zone.

Production call paths (inbound, outbound, widget) always read the deployed fields. Mic sessions and simulations read the draft with fallback to the deployed value.

Transfer numbers#

transfer_destinations lists the numbers the agent may transfer calls to. The prompt refers to each entry by name; the model sees the names and never the numbers. See Transfer calls for prompting and runtime behavior.

Writes replace the whole list. Sending null is rejected; send [] to remove every entry. The same validation runs on create, update, deploy, and every other write path:

• At most 50 entries.
• Only name and number are allowed. Other keys return Unknown field(s): … on that entry.
• A number must be a valid phone number without an extension. Numbers in the fictional range 555-0100 through 555-0199 are refused.
• If the organization has no number on its own carrier, a number that a ThunderPhone number can't reach (outside the US, premium-rate, shared-cost, personal-number, and similar types) is refused with a message that says why.
• A variable must be one placeholder on its own, such as {{rep_phone}}. {{rep_phone|+14155552671}} and text around the placeholder are refused.

Entry errors come back as a list with one object per submitted entry, in order, and {} for entries that passed:

{
  "transfer_destinations": [
    {},
    {"number": ["(415) 555-0134 is a fictional number: 555-0100 through 555-0199 are reserved for examples. Enter a real number."]},
    {"number": ["+44 20 7123 4567 is outside the US, and calls on ThunderPhone numbers can only transfer to US numbers. To transfer there, connect your own carrier under Phone Numbers."]}
  ]
}

Deploying re-checks the deployed list against the organization, so a non-US entry saved while the organization had a number on its own carrier blocks the deploy once it has none.

Configuration warnings#

warnings flags settings worth a second look. Every entry has a code and a human-readable message; other keys depend on the code. Create, update and retrieve responses all carry it. The older tool_collision_warnings field carries the same entries except timezone_not_set; it is deprecated.

Reading the agent never runs a prompt analysis. tool_arguments_not_declared comes from the last analysis of the current prompt, by the dashboard builder or by POST /v1/agents/{id}/prompt-analysis. To get it after changing a prompt over the API, call that endpoint with the agent's draft_prompt (or prompt when there is no draft) exactly as the agent response returns it, then read the agent again. A prompt that differs by so much as a trailing newline is analyzed separately.

"warnings": [
  {
    "code": "tool_has_no_inputs",
    "tool_name": "create_ticket",
    "integration_id": "6f1c2a9e-1b7d-4c55-9a0e-3f2d8b7c4e10",
    "message": "The tool 'create_ticket' declares no inputs, so the agent may call it without the data your endpoint needs. Add the fields it expects to spec.function.parameters.properties. Ignore this only if the endpoint really needs no data."
  }
]

Product tiers at a glance#

Steps and handoffs#

Split an agent into steps when its calls move through phases, such as greeting, identity checks and booking. Each step has its own instructions, tools, an optional word-for-word line and values to collect. The agent moves on by calling the built-in go_to_step tool, or when a code-checked condition on the collected values holds. When steps is set, prompt holds the shared instructions that apply in every step.

A handoff passes the call to another agent in the same organization. That agent brings its own prompt, steps, tools and voice, and the transcript carries over. Every other call setting (product, languages, speaking order, voicemail, consent) comes from the agent the call started on.

Agents without steps or handoffs ("steps": null, "handoffs": []) work exactly as before.

steps#

{
  "start_step": "greet",
  "steps": [
    {
      "id": "greet",
      "name": "Greeting",
      "instructions": "Greet the caller and ask how you can help.",
      "say": "Thanks for calling Acme Dental, this is Ava.",
      "transitions": [
        {"to": "verify", "when": "The caller wants to book, move or cancel an appointment"}
      ]
    },
    {
      "id": "verify",
      "name": "Verify identity",
      "instructions": "Ask for the caller's full name and date of birth.",
      "tools": ["lookup_patient"],
      "collect": [
        {"name": "full_name", "type": "string", "description": "Caller's full name"},
        {"name": "dob", "type": "date", "description": "Date of birth"}
      ],
      "transitions": [
        {"to": "minor", "condition": {"value": "age", "op": "lt", "target": 18}},
        {"to": "book", "when": "Identity is confirmed"}
      ]
    },
    {"id": "minor", "name": "Minor", "instructions": "Ask for a parent or guardian."},
    {"id": "book", "name": "Book", "instructions": "Offer open slots and book one."},
    {
      "id": "billing",
      "name": "Billing questions",
      "instructions": "Answer questions about bills and payments.",
      "global_when": "The caller asks about a bill or payment",
      "transitions": [{"to": "__previous__", "always": true}]
    }
  ]
}

start_step names the step the call begins in. Each step takes:

A condition is {"value", "op", "target"}. value names a collected value or a dotted path into a tool result, such as lookup_patient_result.response.found (a field of the response body) or lookup_patient_result.status (its HTTP status code). op is one of eq, ne, lt, lte, gt, gte, in, not_in, exists or missing:

• eq and ne take a string, number or boolean; in and not_in take a list of 1–50 of them. Strings compare case-insensitively after trimming.
• lt, lte, gt and gte take a number or a YYYY-MM-DD date.
• exists and missing take no target.

A value that was never collected makes every op false except missing. Conditions are checked in order when the agent moves on, and the first match wins.

Limits: 100 steps and 200 KB of JSON per agent. Step tools and on_enter_tool must name tools the agent has when you save. On an agent with steps or handoffs, no tool may be named go_to_step or hand_off.

handoffs#

[{"agent_id": 13, "when": "The caller asks about billing or a refund"}]

Up to 8 entries. agent_id must be another agent in the same organization; when (1–1,000 characters) tells the agent when to hand off. A call includes at most 8 agents, counted breadth-first from the agent it started on. The agent's warnings lists handoff_graph_truncated when handoffs further out are left out, handoff_target_missing when a handoff names an agent that no longer exists (calls skip it), and handoff_tool_name_collision when a handed-to agent has a different tool with the same name as an earlier agent's (that tool is left out of the call).

Validation errors#

Invalid steps or handoffs return 400 with one key per field path:

{
  "steps.steps[1].transitions[0].to": ["Unknown step id \"booking\"."],
  "handoffs[0].agent_id": ["No agent with this id in the organization."]
}

Example#

Stage steps and a handoff on the draft, then deploy:

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are Ava, the front desk for Acme Dental. Be brief and friendly.",
    "steps": {
      "start_step": "greet",
      "steps": [
        {
          "id": "greet",
          "name": "Greeting",
          "instructions": "Ask how you can help.",
          "transitions": [{"to": "book", "when": "The caller wants an appointment"}]
        },
        {"id": "book", "name": "Book", "instructions": "Offer open slots and book one."}
      ]
    },
    "handoffs": [{"agent_id": 13, "when": "The caller asks about billing"}]
  }'
 
curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

List agents#

curl https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

agents = requests.get(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()

const agents = await fetch("https://api.thunderphone.com/v1/agents", {
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` },
}).then((r) => r.json());

Returns an array of Agent objects, sorted by created_at descending.

Create an agent#

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "prompt": "You are a helpful support agent for Acme Ops…",
    "voice": "john",
    "product": "spark",
    "widget_enabled": true
  }'

agent = requests.post(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "name": "Customer Support Agent",
        "prompt": "You are a helpful support agent for Acme Ops…",
        "voice": "john",
        "product": "spark",
        "widget_enabled": True,
    },
).json()

Returns 201 Created with the new Agent object. A create deploys immediately (there is no draft yet) and records revision 1 in the version history.

Retrieve an agent#

curl https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

agent = requests.get(
    f"https://api.thunderphone.com/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()

Returns 200 OK with an Agent object, or 404 if not found.

Update an agent (writes the draft)#

PATCH and PUT do not modify the deployed configuration. Every field you send is staged into the corresponding draft_* column; production calls keep using the deployed values until you deploy. Sending a value identical to the deployed value clears that field's draft (so manually reverting an edit removes the pending change).

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "You are a refined support agent…"}'

agent = requests.patch(
    f"https://api.thunderphone.com/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"prompt": "You are a refined support agent…"},
).json()

Accepts the same fields as create, including the integration_ids / knowledge_base_ids / knowledge_document_ids / mcp_server_ids / reusable_instruction_ids lists (staged as draft attachment lists). Returns 200 OK with the Agent object — inspect the draft_* fields and has_draft to see what is pending.

Optimistic concurrency#

To safely make edits from a UI, include if_updated_at (or updated_at) with the last updated_at you observed:

{
  "prompt": "Newer prompt",
  "if_updated_at": "2026-04-20T18:24:10.113Z"
}

If the server-side updated_at differs, the API returns 409 Conflict with {"detail": "Agent was modified by another user. Please refresh and try again."} so you can refresh and retry.

Deploy the draft#

Promotes every pending draft_* value to the deployed configuration, clears the draft, and records a new revision in the version history.

curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

agent = requests.post(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/deploy",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()

Returns 200 OK with the updated Agent object (has_draft is now false). Deploying with no pending draft is a no-op that still returns 200 with the current agent.

Discard the draft#

Clears every pending draft field, reverting the editor state to the deployed configuration.

curl -X POST https://api.thunderphone.com/v1/agents/12/discard-draft \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 200 OK with the Agent object.

Intro clip#

GET /v1/agents/{agent_id}/intro-clip · POST /v1/agents/{agent_id}/intro-clip · DELETE /v1/agents/{agent_id}/intro-clip

Manage the agent's custom intro clip (intro_clip: "custom"). Like every agent edit, an upload or removal changes the draft; it reaches live calls when you deploy.

Upload with a multipart audio field. The file must be a PCM WAV, 48,000 Hz, mono, 16-bit, 0.5–15 seconds long and at most 2 MB; anything else is refused with 400 and an audio error. (The dashboard converts any file or browser recording to this format for you.) The upload sets draft_intro_clip to custom along with draft_intro_clip_artifact_path and draft_intro_clip_sha256.

curl -X POST https://api.thunderphone.com/v1/agents/12/intro-clip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "audio=@intro.wav;type=audio/wav"

Returns 201 Created:

{
  "artifact_path": "agents/intro-clips/7/12/3f5a…c9.wav",
  "sha256": "3f5a…c9",
  "duration_seconds": 4.2,
  "updated_at": "2026-10-13T18:02:11.482913Z"
}

updated_at is the agent's new value, for optimistic concurrency.

Download returns the clip the draft would play (the draft's clip if one is staged, otherwise the deployed one) as audio/wav, or 404 when there is none.

Remove stages removal of the custom clip; if intro_clip was custom, the draft also switches it to none. Returns 200 OK with the draft's resulting intro_clip and updated_at:

{ "intro_clip": "none", "updated_at": "2026-10-13T18:05:40.120004Z" }

Consent attestations#

GET /v1/agents/{agent_id}/consent-attestations · POST /v1/agents/{agent_id}/consent-attestations

Every agent plays a call-start consent announcement (recording and AI disclosure) by default. Disabling it on a non-grandfathered agent requires an active attestation: an admin's recorded affirmation that your organization will provide any legally required notice and obtain any legally required consent for its calls while the announcement stays off (see the call recording consent laws guide for what that involves). Without one, staging or deploying consent_announcement_enabled: false returns 400.

Attestations are single-use per disable cycle: re-enabling the announcement retires the active attestation (recorded with status_reason: "superseded-by-reenable"), so the next disable needs a fresh affirmation. ThunderPhone may also suspend or revoke attestations, which restores the announcement at runtime. New attestations are recorded only under the current attestation_text_version, but an active attestation recorded under an earlier accepted version stays valid — a statement-copy revision never re-prompts an organization that already attested.

GET lists the agent's attestations (newest first) and returns the current attestation_text_version and the server-owned canonical statement package — statement_text, its statement_sha256, and the statement_locale it resolved for your ?locale= (English until a locale is registered). Display statement_text verbatim to the admin, then POST with affirmed: true, the exact version, your locale, and assent to the package: echo statement_sha256, or send the displayed text as rendered_text (it must hash to the canonical value). The server stores its canonical hash — blank or mismatched statement evidence is rejected.

Step 1 — fetch the canonical statement:

curl https://api.thunderphone.com/v1/agents/12/consent-attestations?locale=en \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "attestation_text_version": "consent-disable-v4-2026-08-03",
  "statement_locale": "en",
  "statement_text": "Turn off the call-recording announcement?\n…",
  "statement_sha256": "7a284954b61b6610d1f9fb43ec05e82e6aec4362956fa5409deb3375cfc99035",
  "results": []
}

Step 2 — display the statement, collect the affirmation, and record it:

curl -X POST https://api.thunderphone.com/v1/agents/12/consent-attestations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"affirmed": true, "attestation_text_version": "consent-disable-v4-2026-08-03", "statement_sha256": "7a284954b61b6610d1f9fb43ec05e82e6aec4362956fa5409deb3375cfc99035", "locale": "en"}'

{
  "id": 91,
  "organization_id": 7,
  "agent_id": 12,
  "user_id": 3,
  "attestation_text_version": "consent-disable-v4-2026-08-03",
  "status": "active",
  "attested_at": "2026-08-03T23:02:11.480Z",
  "status_updated_at": null,
  "affirmed": true,
  "attestation_text_sha256": "7a284954b61b6610d1f9fb43ec05e82e6aec4362956fa5409deb3375cfc99035",
  "locale": "en",
  "user_role": "admin",
  "status_reason": ""
}

PHI designation attestation#

GET /v1/phi-designation-attestation?agent_id={agent_id} · POST /v1/phi-designation-attestation

Only organizations whose BAA includes the PHI designation clause (baa_status: "executed_with_designation") use this endpoint. In such an organization every agent processes PHI by default. Before an agent's phi_processing_override can be set to no_phi, an organization admin must record an attestation for that agent; without one, saving or deploying the override returns 400.

GET returns the current text_version, the canonical English statement (statement_en) and its statement_sha256, the organization's baa_status and phi_processing, and designation_available. With agent_id, it also reports whether that agent has an active attestation (attested, attestation).

POST takes agent_id, accepted: true, the text_version and the statement_sha256 from GET, and an optional display locale (default en; the English statement governs). It returns 201 with the attestation, or 200 with the existing one if the agent already has an active attestation.

curl "https://api.thunderphone.com/v1/phi-designation-attestation?agent_id=12" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "text_version": "phi-designation-no-phi-v1-2026-09-24",
  "statement_en": "I am authorized to designate this agent as not processing protected health information (PHI). …",
  "statement_sha256": "7776b7852f41e777eac228bfd5abdc4df5c958752b39ea032c86f14b02a892da",
  "baa_status": "executed_with_designation",
  "phi_processing": "phi",
  "designation_available": true,
  "attested": false,
  "attestation": null
}

Delete an agent#

curl -X DELETE https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

requests.delete(
    f"https://api.thunderphone.com/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
)

Returns 204 No Content. Phone numbers that reference the deleted agent have their inbound/outbound assignment cleared.

An agent that other agents hand off to, in their deployed or draft handoffs, cannot be deleted. The request returns 409 Conflict with "code": "agent_is_handoff_target" and the referencing agents in agents ([{"id", "name"}]). Remove those handoffs first.

Duplicate an agent#

Creates a new agent in the same org with everything configured for the source agent: all settings, both deployed and pending drafts, the same attached integrations, knowledge bases/documents, MCP servers and reusable instructions, and new copies of its agent-scoped webhook endpoints (same URL, events and signing secret), calendar/CRM connections, split-testing variants, test scenarios and suites (with schedules), and client portal listings. The name defaults to <name> (Copy) and can be overridden. If the source has a pending draft, the copy has one too (has_draft: true), and deploying it ships those edits.

A few settings are reset rather than copied:

• A consent announcement turned off by attestation stays off, and the copy gets its own attestation record carrying the original's. A copy of an agent exempted without an attestation starts with the announcement on.
• A live-processing disclosure set to off goes back to the org default.
• A PHI override the org doesn't allow goes back to the org default.

Phone numbers, SIP addresses, widget publishable keys, campaigns and call history stay with the source agent. Move a number to the copy separately. Steps and handoffs are copied as they are, so the copy hands off to the same agents.

curl -X POST https://api.thunderphone.com/v1/agents/12/duplicate \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Support Agent (clone)"}'

clone = requests.post(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/duplicate",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={"name": "Customer Support Agent (clone)"},
).json()

Returns 201 Created with the new Agent object.

Transfer an agent to another org#

Copy or move an agent to a different organization. admin+ role is required on both orgs.

An sk_live_ API key is limited to its own organization: with a key, target_org_id must be the key's organization, and any other target returns 403. Copy or move between organizations from a signed-in session (Authorization: Token <session-token> plus X-ThunderPhone-Org for the source org), as below.

curl -X POST https://api.thunderphone.com/v1/agents/12/transfer \
  -H "Authorization: Token YOUR_SESSION_TOKEN" \
  -H "X-ThunderPhone-Org: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "target_org_id": 77,
    "mode": "copy"
  }'

result = requests.post(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/transfer",
    headers={"Authorization": "Token YOUR_SESSION_TOKEN", "X-ThunderPhone-Org": "42"},
    json={"target_org_id": 77, "mode": "copy"},
).json()

copy makes the same copy as Duplicate, with the target org's rules applied: integrations, knowledge, MCP servers and reusable instructions attach only if the same record belongs to the target org; webhook endpoints, calendar/CRM connections, client portal listings, legacy inline tools, and test scenarios created from real calls are not copied and are named in not_copied; copied test-suite schedules start disabled; SMS sending is off until the target org picks one of its own numbers; transfer numbers the target org could not save (numbers a ThunderPhone number can't reach, when the target org has no number on its own carrier) are left behind and reported as transfer_destinations in not_copied; and the consent announcement starts on, because another org's attestation does not cover the target org.

Returns 201 Created for copy (with not_copied, a list such as ["webhook_endpoints"]) / 200 OK for move:

{
  "mode": "move",
  "source_org_id": 42,
  "target_org_id": 77,
  "agent": { /* Agent object in the target org */ },
  "detached": {
    "publishable_keys": 1,
    "webhook_endpoints": 0,
    "provider_connections": 1,
    "client_portals": 0,
    "transfer_destinations": 0
  }
}

Version history#

Deploys (and creates/duplicates/transfers) record an AgentConfigVersion snapshot of the deployed configuration. Draft autosaves are not versioned — the history reflects what actually shipped to production.

curl 'https://api.thunderphone.com/v1/agents/12/versions?limit=20' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

versions = requests.get(
    f"https://api.thunderphone.com/v1/agents/{agent_id}/versions",
    params={"limit": 20},
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
).json()

Response:

{
  "count": 3,
  "results": [
    {
      "id": 501,
      "revision": 3,
      "created_by_id": 7,
      "created_at": "2026-04-20T18:24:10.113Z",
      "snapshot": { /* Deployed agent config at this revision */ },
      "changed_fields": ["prompt", "voice"]
    }
  ]
}

Prompt helpers#

These endpoints are convenience wrappers that call the same underlying models we use in the dashboard. All of them take and return JSON; none change your agents or any other resource you manage.

Detect prompt language#

curl -X POST https://api.thunderphone.com/v1/agents/prompt-language-check \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hola, gracias por llamar..."}'

{
  "detected_language_code": "es",
  "detected_language_name": "Spanish",
  "mismatch": true,
  "provider": "<provider id>"
}

Translate prompt#

curl -X POST https://api.thunderphone.com/v1/agents/translate-prompt \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hola, gracias por llamar…",
    "target_locale": "en-US"
  }'

{
  "translated_prompt": "Hello, thank you for calling…",
  "source_language_code": "es",
  "source_language_name": "Spanish",
  "provider": "<provider id>",
  "used_fallback": false
}

Generate acknowledgement prompt#

Produces a short "filler while thinking" phrase appropriate for Storm-with-ack products.

curl -X POST https://api.thunderphone.com/v1/agents/generate-acknowledgement-prompt \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are a friendly receptionist for a dental office.",
    "target_locale": "en-US"
  }'

{
  "acknowledgement_prompt": "Sure, let me take a quick look…",
  "provider": "<provider id>",
  "used_fallback": false
}

Render steps as one prompt#

Returns the shared instructions and steps as one prompt, in the form a stepped agent falls back to when steps cannot run. Use it to turn a stepped agent back into a single-prompt agent: send the result as prompt together with "steps": null. steps is checked for shape only, and nothing is saved. With "steps": null, prompt comes back unchanged.

curl -X POST https://api.thunderphone.com/v1/agents/steps/flatten \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are Ava, the front desk for Acme Dental.",
    "steps": {
      "start_step": "greet",
      "steps": [
        {
          "id": "greet",
          "name": "Greeting",
          "instructions": "Ask how you can help.",
          "transitions": [{"to": "book", "when": "The caller wants an appointment"}]
        },
        {"id": "book", "name": "Book", "instructions": "Offer open slots and book one."}
      ]
    }
  }'

{
  "prompt": "You are Ava, the front desk for Acme Dental.\n\n## Conversation flow\n1. Greeting (start here): Ask how you can help.\n   - If The caller wants an appointment → go to Book\n2. Book: Offer open slots and book one.\n"
}

Analyze a prompt#

Runs the same advisory checks the agent builder shows under the prompt editor. A model extracts facts from the prompt text (languages, tools it mentions, escalation and consent guidance), and the API compares them with the agent's configuration. Nothing is saved to the agent, so you can send an unsaved draft. Requires the member role or higher.

curl -X POST https://api.thunderphone.com/v1/agents/123/prompt-analysis \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Eres la recepcionista de una clínica dental. Usa book_appointment para agendar citas.",
    "primary_language": "en",
    "additional_languages": [],
    "voice": "john",
    "integration_ids": [],
    "mcp_server_ids": []
  }'

Every field except prompt is optional. An omitted field uses the agent's draft value, or the deployed value when the draft has none, so the findings depend on the agent unless you send every field, as the example does.

{
  "facts": {
    "languages": {
      "declared": [],
      "written_in": [{"code": "es", "share": 1.0}]
    },
    "tools": {
      "referenced": [
        {"name": "book_appointment", "kind": "identifier", "evidence": "Usa book_appointment para agendar citas"}
      ]
    },
    "escalation": {"present": false, "kind": "none", "evidence": ""},
    "compliance": {"present": false, "evidence": ""}
  },
  "findings": [
    {
      "id": "languages-not-configured",
      "severity": "warning",
      "params": {"languages": [{"code": "es", "supported_by_voice": true}]}
    },
    {
      "id": "primary-language-mismatch",
      "severity": "warning",
      "params": {"detected": "es", "primary": "en"}
    },
    {
      "id": "tool-actions-without-tools",
      "severity": "warning",
      "params": {"tools": ["book_appointment"]}
    },
    {"id": "missing-escalation-guidance", "severity": "warning", "params": {}},
    {"id": "missing-consent-or-privacy-guidance", "severity": "info", "params": {}}
  ]
}

facts is what the model extracted; findings are computed from the facts and the configuration on every request. New finding ids and fact keys may be added, so ignore ones you don't recognize.

The analysis is advisory and never fails the request because the model did:

• If the model is unavailable or returns something unusable, you get 200 with {"findings": [], "facts": null, "error": "unavailable"}.
• Facts are cached per agent and prompt text. Repeating a prompt returns instantly, with findings recomputed against the current configuration.
• Uncached requests are throttled per agent. A new model request starts no sooner than two seconds after the previous one started, and while one is still running it holds a 20-second lease. A request inside either window returns the last good result with "stale": true and retry_after_ms. If there is no earlier result it returns 202 with only retry_after_ms. Either way, retry after that many milliseconds.

Voices#

List the supported voices and languages — or browse the voice gallery with playable samples:

curl 'https://api.thunderphone.com/v1/voices?languages=en,es' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "voices": [
    {
      "name": "john",
      "display_name": "John",
      "gender": "male",
      "category": "multilingual",
      "accent": "american",
      "languages": ["en", "es", "fr", "…"],
      "sample_url": "https://…/john.mp3?v=3"
    }
  ],
  "languages": [ /* language catalog entries */ ],
  "elevenlabs": {
    "provider": "ElevenLabs",
    "model": "eleven_v4_turbo",
    "model_label": "Eleven v4 Turbo",
    "surcharge_cents": 5,
    "hipaa_eligible": false,
    "available": true,
    "unavailable_reason": null,
    "languages": ["ar", "bn", "…"],
    "voices": [
      {
        "name": "elevenlabs:UgBBYS2sOqTuMpoF3BR0",
        "display_name": "Mark",
        "tagline": "Natural Conversations",
        "description": "A casual, young-adult speaking in a natural manner. Perfect for Conversational AI.",
        "gender": "male",
        "age": "young",
        "accent": "american",
        "native_language": "en",
        "use_case": "conversational",
        "sample_url": "https://storage.googleapis.com/eleven-public-prod/…/0Oc7jiXwWN9kRTXfQsmw.mp3"
      }
    ]
  }
}

The name is what you set on an agent's voice field.

ElevenLabs voices#

The elevenlabs block lists voices from ElevenLabs under ElevenLabs' own names, on the Eleven v4 Turbo model. Every voice speaks every code in its languages, which is the whole language catalog, and costs surcharge_cents per minute in every language, in place of any language or premium-voice surcharge. The gender filter applies to this block too; languages and category keep it only when every requested language is covered or the category is elevenlabs.

ElevenLabs voices are not HIPAA eligible yet (hipaa_eligible: false):

• An agent, draft, step, split-test variant or realtime session whose PHI designation resolves to PHI cannot select one. The request fails with "ElevenLabs voices are not HIPAA eligible yet. Ask us to enable HIPAA for them, or pick another voice.", as does switching an agent that uses one to processing PHI.
• available is false with unavailable_reason: "phi" when your whole organization resolves to PHI. Individual agents may still be designated as not processing PHI; the check above is per agent.
• If a call to an agent with an ElevenLabs voice runs as a PHI call anyway, it uses a standard voice for the call language and carries no ElevenLabs charge.

Related#