Legs

Last updated April 16, 2026

Voice call legs (SIP or WebRTC)

# GET /legs

List all active legs

Responses

200 Array of legs

# POST /legs

Originate an outbound SIP call

Request Body

Field	Type		Description
`type`	enum	required	Leg type Values: `sip`
`uri`	string	required	SIP URI to dial
`from`	string	optional	Caller ID — sets the user part of the SIP From header (e.g. "+15551234567", "alice")
`privacy`	string	optional	SIP Privacy header value (e.g. "id", "none")
`ring_timeout`	integer	optional	Seconds to wait for answer; 0 = no timeout `0`
`max_duration`	integer	optional	Maximum call duration in seconds after connect. Automatically hung up when reached. 0 or omitted = no limit. `0`
`codecs`	array[enum]	optional	Codec preference order
`headers`	object	optional	Custom SIP headers to include in the outbound INVITE (e.g. X-Correlation-ID)
`room_id`	string	optional	Room ID to auto-add the leg to once media is ready (early_media or connected). If the room does not exist, it is automatically created.
`auth`	any	optional	SIP digest authentication credentials. If the remote challenges with 401/407, sipgo will retry with these credentials.
`webhook_url`	string(uri)	optional	Route all events for this leg exclusively to this URL instead of global webhooks.
`webhook_secret`	string	optional	HMAC-SHA256 signing secret for the per-leg webhook.
`amd`	any	optional	Enable Answering Machine Detection on outbound calls. Include the object (even empty) to enable with defaults; omit to disable.
`accept_dtmf`	boolean	optional	If false, this leg will not receive DTMF digits broadcast from other legs in the same room. Defaults to true. `true`

Responses

201 Leg created

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`id`	string	required	Unique leg identifier (UUID)
`type`	enum	required	Leg type Values: `sip_inbound`, `sip_outbound`, `webrtc`
`state`	enum	required	Leg state Values: `ringing`, `early_media`, `connected`, `held`, `hung_up`
`room_id`	string	optional	Room ID if the leg is in a room, empty otherwise
`muted`	boolean	required	Whether the leg is muted (cannot be heard by others)
`deaf`	boolean	required	Whether the leg is deaf (cannot hear others)
`accept_dtmf`	boolean	required	Whether the leg receives DTMF digits broadcast from other legs in the same room. Defaults to true.
`held`	boolean	required	Whether the call is on hold (SIP legs only)
`sip_headers`	object	optional	X-* headers from the inbound INVITE. Only present on sip_inbound legs.

400 Invalid JSON, bad SIP URI, unknown codec, or unsupported type

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# GET /legs/{id}

Get a single leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Leg details

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`id`	string	required	Unique leg identifier (UUID)
`type`	enum	required	Leg type Values: `sip_inbound`, `sip_outbound`, `webrtc`
`state`	enum	required	Leg state Values: `ringing`, `early_media`, `connected`, `held`, `hung_up`
`room_id`	string	optional	Room ID if the leg is in a room, empty otherwise
`muted`	boolean	required	Whether the leg is muted (cannot be heard by others)
`deaf`	boolean	required	Whether the leg is deaf (cannot hear others)
`accept_dtmf`	boolean	required	Whether the leg receives DTMF digits broadcast from other legs in the same room. Defaults to true.
`held`	boolean	required	Whether the call is on hold (SIP legs only)
`sip_headers`	object	optional	X-* headers from the inbound INVITE. Only present on sip_inbound legs.

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}

Hang up a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Leg hung up

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/answer

Answer a ringing or early-media inbound SIP leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Answer initiated

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Not a SIP inbound leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg is not in ringing or early_media state

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/early-media

Enable early media on a ringing inbound SIP leg

Sends SIP 183 Session Progress with SDP and sets up the media pipeline. The leg transitions to early_media state, allowing audio playback and room participation before the call is answered.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Early media enabled

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Not a SIP inbound leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg is not in ringing state

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

500 Media setup failed

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/mute

Mute a leg

A muted leg's audio is excluded from the room mix and speaking events are suppressed. Taps (recording/STT) still receive the muted leg's own audio.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Leg muted

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}/mute

Unmute a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Leg unmuted

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/hold

Put a SIP call on hold

Sends a re-INVITE with sendonly SDP direction. The RTP timeout is paused while held, and a 2-hour auto-hangup timer starts.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Call held

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Not a SIP leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg is not in connected state, or already held

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}/hold

Resume a held SIP call

Sends a re-INVITE with sendrecv SDP direction.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Call resumed

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Not a SIP leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg is not held

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/transfer

Transfer a SIP leg via REFER (asynchronous)

Asynchronously transfers a SIP leg. The HTTP call returns 202 as soon as the request is validated; the REFER is sent in the background and its outcome is surfaced through leg.transfer_initiated / leg.transfer_progress / leg.transfer_completed / leg.transfer_failed events. Blind transfer when replaces_leg_id is omitted; attended transfer when present (the named leg's dialog identity is embedded as a Replaces parameter per RFC 3891). On terminal 2xx the leg (and the replaces leg, if any) is hung up automatically.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`target`	string	required	SIP URI to transfer the call to (e.g. "sip:bob@example.com").
`replaces_leg_id`	string	optional	ID of an existing connected SIP leg whose dialog should be replaced (attended transfer). Omit for blind transfer.

Responses

202 Transfer request accepted for processing

400 Missing or invalid target URI (including URIs without a host such as sip:)

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg not connected, not a SIP leg, or replaces_leg_id is invalid

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/dtmf

Send DTMF digits on a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`digits`	string	required	DTMF digits to send (0-9, *, #)

Responses

200 Digits sent

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or empty digits

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

500 DTMF writer unavailable

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/dtmf/accept

Enable DTMF reception on a leg

Allow this leg to receive DTMF digits broadcast from other legs in the same room. This is the default state for new legs.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 DTMF reception enabled

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/dtmf/reject

Disable DTMF reception on a leg

Block this leg from receiving DTMF digits broadcast from other legs in the same room. DTMF received from this leg's own far end is still emitted as a leg.dtmf event.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 DTMF reception disabled

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/play

Start audio playback to a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`url`	string(uri)	required	URL of the audio file (mutually exclusive with tone)
`tone`	string	required	Built-in telephone tone name. Format: {country}_{type} or bare {type} (defaults to US). Types: ringback, busy, dial, congestion. Countries: us, gb, de, fr, au, jp, it, in, br, pl, ru. Examples: us_ringback, gb_busy, dial.
`mime_type`	string	required	MIME type (e.g. audio/wav). Required when using url.
`repeat`	integer	required	Number of times to repeat playback (url only) `0`
`volume`	integer	required	Volume adjustment in dB (-8 to 8) `0`

Responses

200 Playback started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or volume out of range

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg has no audio writer

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# PATCH /legs/{id}/play/{playbackID}

Change the volume of an active leg playback

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID
`playbackID`	path	string	required	Playback ID

Request Body

Field	Type		Description
`volume`	integer	required	Volume adjustment (-8 to 8, ~3dB per step, 0 = unchanged)

Responses

200 Volume updated

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or volume out of range

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Playback not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}/play/{playbackID}

Stop audio playback on a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID
`playbackID`	path	string	required	Playback ID

Responses

200 Playback stopped

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 No playback in progress

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/tts

Synthesize speech and play it on a leg

Synthesizes the provided text using the configured TTS provider and plays the audio on the leg. When TTS_CACHE_ENABLED=true, identical requests (same text, voice, model, language, and prompt) are stored on disk in TTS_CACHE_DIR and persist across restarts, without calling the external provider.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`text`	string	required	Text to synthesize
`voice`	string	required	Provider-specific voice identifier. ElevenLabs: voice name or ID. AWS Polly: voice ID (e.g. Joanna, Matthew). Google Cloud: voice name — either full format (e.g. en-US-Neural2-F) or short name for Gemini models (e.g. Achernar, Kore). Deepgram: model name (e.g. aura-2-asteria-en).
`model_id`	string	required	Provider-specific model/engine. ElevenLabs: model ID. AWS Polly: engine (standard, neural, long-form, generative; default neural). Google Cloud: model name (e.g. gemini-2.5-pro-tts, chirp3-hd).
`language`	string	optional	Language code (e.g. "en-US", "pl-pl"). Required for Google Gemini TTS voices that use short names (e.g. Achernar). Auto-extracted from full voice names like en-US-Neural2-F.
`prompt`	string	optional	Style/tone instruction for promptable voice models (Google Gemini TTS only). E.g. "Read aloud in a warm, welcoming tone."
`volume`	integer	required	Volume adjustment in dB (-8 to 8) `0`
`provider`	enum	optional	TTS provider: "elevenlabs" (default), "aws", "google", or "deepgram" Values: `elevenlabs`, `aws`, `google`, `deepgram`
`api_key`	string	optional	ElevenLabs: API key override (falls back to ELEVENLABS_API_KEY env var). AWS: optional ACCESS_KEY:SECRET_KEY override (falls back to default AWS credential chain). Google Cloud: optional API key override (falls back to Application Default Credentials). Deepgram: API key override (falls back to DEEPGRAM_API_KEY env var).

Responses

200 TTS playback started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON, missing text/voice, or volume out of range

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg has no audio writer

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

503 No API key provided for the selected provider

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/record

Start recording a leg to a WAV file

For SIP legs, recording is stereo (left=incoming, right=outgoing). For legs in a room, stereo at 16kHz (left=participant audio, right=mixed-minus-self).

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`storage`	enum	required	"file" (default) — local disk, "s3" — upload to S3 after recording stops Values: `file`, `s3`
`multi_channel`	boolean	required	When true, record each participant to a separate mono WAV file in addition to the full mix. Only applies to room recordings. `false`
`s3_bucket`	string	required	S3 bucket name. Overrides S3_BUCKET env var. Required if env var is not set.
`s3_region`	string	required	AWS region. Overrides S3_REGION env var. Default us-east-1.
`s3_endpoint`	string	required	Custom S3 endpoint (MinIO, etc.). Overrides S3_ENDPOINT env var.
`s3_prefix`	string	required	Key prefix (e.g. recordings/). Overrides S3_PREFIX env var.
`s3_access_key`	string	required	AWS access key ID. Overrides default credential chain.
`s3_secret_key`	string	required	AWS secret access key. Must be set together with s3_access_key.

Responses

200 Recording started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid storage type, S3 not configured, or invalid S3 credentials

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg has no audio reader or room not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

500 Failed to create recording file

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}/record

Stop recording a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Recording stopped

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 No recording in progress

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/record/pause

Pause a leg recording

Replaces incoming audio with silence on the active recording until /record/resume is called. The WAV's timeline is preserved (silent gap where audio was paused), so reviewers can see exactly when sensitive data was excluded. Idempotent: calling while already paused returns status: already_paused.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Recording paused (or already paused)

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 No recording in progress

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/record/resume

Resume a paused leg recording

Resumes writing real audio after a prior /record/pause. Idempotent: calling while not paused returns status: not_paused.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Recording resumed (or was not paused)

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 No recording in progress

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/stt

Start real-time speech-to-text on a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`language`	string	required	Language code (e.g. "en", "es")
`partial`	boolean	required	Emit partial (non-final) transcripts `false`
`provider`	enum	optional	STT provider: "elevenlabs" (default) or "deepgram" Values: `elevenlabs`, `deepgram`
`api_key`	string	optional	API key override (falls back to ELEVENLABS_API_KEY or DEEPGRAM_API_KEY env var depending on provider)

Responses

200 STT started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg not connected, STT already running, or no audio reader

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

503 No ElevenLabs API key provided

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}/stt

Stop speech-to-text on a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 STT stopped

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 No STT in progress

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/agent/elevenlabs

Attach an ElevenLabs ConvAI agent to a leg

Bridges audio bidirectionally with an ElevenLabs conversational AI agent. Standalone legs use direct audio; legs in a room use mixer taps.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`agent_id`	string	required	ElevenLabs agent ID
`first_message`	string	optional	Override the agent's first message
`language`	string	optional	Language code (e.g. "en", "es")
`dynamic_variables`	object	optional	Key-value pairs passed to the agent as dynamic variables
`api_key`	string	optional	API key override (falls back to ELEVENLABS_API_KEY env var)

Responses

200 Agent started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or missing agent_id

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg not connected, agent already attached, or no audio reader/writer

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

503 No ElevenLabs API key provided

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/agent/vapi

Attach a VAPI agent to a leg

Bridges audio bidirectionally with a VAPI conversational AI agent. Standalone legs use direct audio; legs in a room use mixer taps.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`assistant_id`	string	required	VAPI assistant ID
`first_message`	string	optional	Override the agent's first message
`variable_values`	object	optional	Key-value pairs passed as VAPI variable values (assistantOverrides.variableValues)
`api_key`	string	optional	API key override (falls back to VAPI_API_KEY env var)

Responses

200 Agent started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or missing assistant_id

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg not connected, agent already attached, or no audio reader/writer

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

503 No VAPI API key provided

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/agent/pipecat

Attach a Pipecat bot to a leg

Bridges audio bidirectionally with a self-hosted Pipecat bot via WebSocket. Standalone legs use direct audio; legs in a room use mixer taps.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`websocket_url`	string(uri)	required	WebSocket URL of the Pipecat bot (e.g. ws://my-bot:8765)

Responses

200 Agent started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or missing websocket_url

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg not connected, agent already attached, or no audio reader/writer

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/agent/deepgram

Attach a Deepgram Voice Agent to a leg

Bridges audio bidirectionally with a Deepgram Voice Agent. Standalone legs use direct audio; legs in a room use mixer taps.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`settings`	object	optional	Full Deepgram agent settings object (agent.listen, agent.think, agent.speak, etc.). When omitted, sensible defaults are used (nova-3 STT, gpt-4o-mini LLM, aura-2-asteria-en TTS).
`greeting`	string	optional	Agent greeting message
`language`	string	optional	Language code (e.g. "en", "es")
`api_key`	string	optional	API key override (falls back to DEEPGRAM_API_KEY env var)

Responses

200 Agent started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg not connected, agent already attached, or no audio reader/writer

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

503 No Deepgram API key provided

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/agent/message

Inject a message into a running agent session on a leg

Sends a context message or instruction to the running agent. Supported by Deepgram (InjectAgentMessage), Pipecat (TextFrame), and VAPI (control URL). Returns 501 for ElevenLabs.

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`message`	string	required	Context or instruction to inject into the running agent session

Responses

200 Message sent

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid JSON or missing message

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 No agent attached to this leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Agent session not running

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

501 Provider does not support message injection

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# DELETE /legs/{id}/agent

Detach the agent from a leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Responses

200 Agent stopped

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

404 No agent attached to this leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

# POST /legs/{id}/amd

Start answering machine detection on a connected leg

Parameters

Name	In	Type		Description
`id`	path	string	required	Leg ID

Request Body

Field	Type		Description
`initial_silence_timeout`	integer	optional	Max milliseconds of silence before declaring no_speech `2500`
`greeting_duration`	integer	optional	Speech duration threshold (ms) above which answerer is classified as machine `1500`
`after_greeting_silence`	integer	optional	Silence duration (ms) after initial speech to declare human `800`
`total_analysis_time`	integer	optional	Max analysis window in milliseconds `5000`
`minimum_word_length`	integer	optional	Minimum speech burst duration (ms) to count as a word `100`
`beep_timeout`	integer	optional	Max time (ms) to wait for the voicemail beep after machine detection. 0 or omitted = disabled. `0`

Responses

200 AMD started

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`status`	string	required

400 Invalid AMD params or not a SIP leg

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

404 Leg not found

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message

409 Leg is not in connected state

Field	Type		Description
`instance_id`	string	optional	Instance identifier
`error`	string	required	Error message