Get Agent | Speechify API

{
  "id": "agent_01kxmwcejz05xht5gmej146s6j",
  "name": "Example name",
  "slug": "example",
  "prompt": "example",
  "first_message": "example",
  "language": "en-US",
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "base_url": "example",
    "credential_id": "cred_01jqr8x9zg5k2m3n4p5q6r7s8t",
    "extra_body": {},
    "temperature": 0
  },
  "tts": {
    "voice_id": "voice_01jqr8x9zg5k2m3n4p5q6r7s8t",
    "speed": 0.5
  },
  "stt": {
    "override": "whisper-v3"
  },
  "turn_handling": {
    "response_delay_seconds": 0,
    "inactivity_timeout_seconds": 30
  },
  "memory": {
    "enabled": true,
    "retention_days": 0
  },
  "navigator": {
    "enabled": true,
    "ivr_cache_enabled": true
  },
  "background_noise": {
    "preset": "office",
    "volume": 0
  },
  "is_public": true,
  "allowed_origins": [
    "example"
  ],
  "amd": {
    "enabled": true,
    "on_voicemail": {
      "action": "hangup",
      "message": "example"
    },
    "on_ivr": {
      "action": "proceed"
    },
    "on_unavailable": {
      "action": "hangup"
    },
    "tuning": {
      "human_speech_threshold_seconds": 0.5,
      "no_speech_threshold_seconds": 1,
      "timeout_seconds": 5,
      "classification_prompt": "example"
    }
  },
  "save_audio_recording": true,
  "created_at": "2026-06-24T18:03:11Z",
  "updated_at": "2026-06-24T18:03:11Z",
  "widget_config": {
    "version": 1,
    "style": "pill",
    "theme": "dark",
    "avatar": {
      "type": "orb",
      "image_url": "example",
      "orb_color_1": "example",
      "orb_color_2": "example"
    },
    "text": {
      "start_call": "example",
      "end_call": "example",
      "listening": "example",
      "thinking": "example",
      "speaking": "example"
    },
    "terms": {
      "enabled": true,
      "content": "example"
    },
    "transcript": {
      "enabled": true
    }
  },
  "hostname_allowlist": [
    "example"
  ],
  "webhook_url": "https://example.com/webhook",
  "webhook_secret_set": true
}

Retrieve a voice agent by ID.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

agent_idstringRequired

Agent id (prefixed external id, agent_...).

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The requested agent.

idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (agent_<26 char Crockford base32>). This is the sole customer-facing identifier. URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

namestring

slugstring

promptstring

first_messagestring

Spoken verbatim at session start when present in the customer's flow graph.

languagestring

ISO 639-1 code, e.g. ‘en’.

llmobject

Language-model configuration. Omit the whole block on create to run on the platform default model. On update (merge-patch) send only the sub-fields you want to change: an explicit null clears a nullable field to its default, a value sets it, and anything omitted is left unchanged. provider/model are validated as a pair, inheriting the omitted half from the stored value.

ttsobject

Text-to-speech voice and delivery configuration.

sttobject

Speech-to-text configuration.

turn_handlingobject

Turn-handling and silence-timeout configuration.

memoryobject

Per-caller long-term memory configuration.

navigatorobject

Autonomous IVR-navigation configuration for outbound calls.

background_noiseobject

Optional ambient background-noise bed mixed into the call.

is_publicboolean

When true, the <speechify-agent> web component can start a session against this agent without an API key, subject to the allowed_origins allowlist. When false (default), only authenticated callers can start sessions.

allowed_originslist of strings

Exact Origin header values (e.g. https://example.com) that are allowed to start public sessions. Empty array with is_public = true means any origin is accepted — intended for open demos. No subdomain wildcards.

amdobject

Answering Machine Detection routing config for outbound voice agents. AMD classifies the called party’s first ~3-15 seconds of audio into one of LiveKit’s categories (human, uncertain, machine-vm, machine-ivr, machine-unavailable) and dispatches per category to the configured action. Stored on the agent row; flowed onto outbound dispatch metadata under the amd key.

save_audio_recordingboolean

When true, every conversation produces a room-composite OGG egress uploaded to the recordings bucket. Defaults FALSE for new agents (privacy by default).

created_atdatetime

updated_atdatetime

widget_configobject

Customer-editable appearance + behaviour payload for the embedded <speechify-agent> pill: button text, avatar style, orb colours, terms-and-conditions markdown, transcript display. Every field is optional - empty fields fall back to the widget’s compile-time defaults.

hostname_allowlistlist of strings or null

Optional per-agent hostname allowlist enforced at session-creation time. When set and non-empty, the Origin header’s hostname must be an exact member. Bare hostnames only — no scheme, port, or path. Up to 10 entries. Omit (null) or leave empty for no enforcement (public agents accept any hostname).

webhook_urlstring

Per-agent override of the workspace webhook endpoints for this agent’s post-call event. When non-empty, the control plane POSTs a signed payload (transcript + evals + extractors + recording URL) here once the conversation completes, and the workspace endpoints’ conversation.completed is suppressed for this agent (the override wins, so the two planes no longer both fire). Empty routes conversation.completed to your workspace webhook endpoints instead. conversation.started / conversation.failed always ride the workspace endpoints regardless of this field.

webhook_secret_setboolean

True when an HMAC-SHA256 webhook secret is configured. The secret itself is write-only — supplied on PATCH and never echoed back on reads.

Errors

401

Unauthorized Error

404

Not Found Error

$	curl https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t \
>	-H "Authorization: Bearer <token>"

Authentication

Path parameters

Headers

Response headers

Response

Errors