curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/hold-audio' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F 'hold_audio_file=@sample.bin'

# POST /v1/convai/agents/{agent_id}/hold-audio (ElevenLabs API)
Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20

> Post Agent Hold Audio

## Critical Gotchas
* Authentication uses the non-standard `xi-api-key` header, not `Authorization: Bearer`. Sending a Bearer token returns HTTP 401.
* Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (`--output speech.mp3`) rather than parsing it.

## cURL
curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/hold-audio' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F 'hold_audio_file=@sample.bin'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| agent_id | path | string | Yes | The id of an agent. This is returned on agent creation. |
| hold_audio_file | body | string | Yes | An MP3 or WAV file played on loop to callers waiting in t... |

## Response (200 OK)
{"agent_id":"string","hold_audio":{"audio_path":"string","audio_url":"string"}}

---
Need an API key? Get one at https://elevenlabs.io/app/sign-up

POST

POST /v1/convai/agents/{agent_id}/hold-audio — ElevenLabs API

ElevenLabs API

Post Agent Hold Audio

Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 202 tokens · Vary: Accept

Critical gotchas

Authentication uses the non-standard xi-api-key header, not Authorization: Bearer. Sending a Bearer token returns HTTP 401.

Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (--output speech.mp3) rather than parsing it.

cURL

curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/hold-audio' \  -H "xi-api-key: $ELEVENLABS_API_KEY" \  -F '[email protected]'

Parameters

Name	In	Type	Required	Description
agent_id	path	string	Yes	The id of an agent. This is returned on agent creation.
hold_audio_file	body	string	Yes	An MP3 or WAV file played on loop to callers waiting in the agent's concurrency wait queue. Maximum size 40 MB, maximum duration 180 seconds.

Response 200 OK

{
  "agent_id": "string",
  "hold_audio": {
    "audio_path": "string",
    "audio_url": "string",
    "original_filename": "string",
    "duration_secs": 0,
    "size_bytes": 0
  }
}

Get a free ElevenLabs API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.