> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.phonic.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.phonic.ai/_mcp/server. # List GET https://api.phonic.ai/v1/agents Returns all agents in a project. Reference: https://docs.phonic.ai/api-reference/agents/list ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication header of the form `Bearer `. Manage your API keys [here](https://phonic.co/api-keys). ## Request ### Query parameters - `project` (string, optional, default: main) — The name of the project to list agents for. ## Response ### 200 Success response - `agents` (list of Agent, required) ## Errors ### 404 Not Found Error Project not found - `error` (BasicErrorError, optional) ### 500 Internal Server Error Internal server error - `error` (BasicErrorError, optional) ## Types ### Agent - `id` (string, required) — The ID of the agent. - `name` (string, required) — The name of the agent. - `phone_numbers` (list of string, required) — Array of phone numbers that the agent uses to accept phone calls. - `project` (AgentProject, required) — The project the agent belongs to. - `timezone` (string, required) — The timezone of the agent. Used to format system variables like `{{system_time}}`. - `voice_id` (string, required) — The voice ID of the agent. - `audio_format` (enum, required) — The audio format of the agent. If the agent has a phone number, the audio format will be `mulaw_8000`. - Allowed values: `pcm_44100`, `pcm_24000`, `pcm_16000`, `pcm_8000`, `mulaw_8000` - `audio_speed` (double, required) — The audio speed of the agent. Must be a multiple of 0.1. - `background_noise_level` (double, required) — The background noise level of the agent. Must be between 0 and 1. - `background_noise` (enum, required) — The background noise type. Can be "office", "call-center", "coffee-shop", or null. - Allowed values: `office`, `call-center`, `coffee-shop` - `generate_welcome_message` (boolean, required) — When `true`, the welcome message will be automatically generated and the `welcome_message` field will be ignored. - `is_welcome_message_interruptible` (boolean, required) — When `false`, the welcome message will not be interruptible by the user. - `listen_only_inbound_enabled` (boolean, required) — Play an uninterruptible welcome message on incoming calls, then transcribe the caller without responding. Silence timeout and call duration limits still apply. - `listen_only_inbound_message` (string, required, nullable) — Welcome message for listen-only incoming calls. Can contain template variables like `{{customer_name}}`. Must be nonempty when `listen_only_inbound_enabled` is `true`. Replaces `welcome_message` for these calls, regardless of `generate_welcome_message`. - `welcome_message` (string, required, nullable) — Message to play when the conversation starts. Ignored when `generate_welcome_message` is `true`. - `system_prompt` (string, required) — Instructions for the conversation. - `template_variables` (map from string to AgentTemplateVariables, required) — Template variables that the agent can use in the welcome message and the system prompt. - `tools` (list of AgentToolsItems, required) — List of tools available to the agent. - `built_in_tool_configs` (BuiltInToolConfigs, required) — Configuration overrides for built-in tools, keyed by built-in tool ID. - `tasks` (list of Task, required) — Tasks for the agent to complete during the conversation. - `generate_no_input_poke_text` (boolean, required, default: false) — Whether to have the no-input poke text be generated by AI. - `no_input_poke_sec` (integer, required, nullable) — Number of seconds of silence before sending a poke message. `null` disables the poke message. - `no_input_poke_text` (string, required) — The message to send after the specified silence. Ignored when generate_no_input_poke_text is true. - `no_input_end_conversation_sec` (integer, required) — Seconds of silence before ending the conversation. - `default_language` (enum, required) — ISO 639-1 language code that sets the agent's default language to recognize and speak. Welcome message and no input poke text should be in this language. - Allowed values: `ar`, `az`, `bg`, `bn`, `cs`, `da`, `de`, `el`, `en`, `es`, `fa`, `fi`, `fil`, `fr`, `gu`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `ka`, `km`, `kn`, `ko`, `lt`, `lv`, `ml`, `mr`, `ms`, `ne`, `nl`, `no`, `pa`, `pl`, `pt`, `ro`, `ru`, `si`, `sk`, `sq`, `sv`, `sw`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `yue`, `zh` - `additional_languages` (list of enum, required) — Array of additional ISO 639-1 language codes that the agent should be able to recognize and speak. Should not include `default_language`. When `multilingual_mode` is `"auto"`, a maximum of 2 additional languages is allowed. - Allowed values: `ar`, `az`, `bg`, `bn`, `cs`, `da`, `de`, `el`, `en`, `es`, `fa`, `fi`, `fil`, `fr`, `gu`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `ka`, `km`, `kn`, `ko`, `lt`, `lv`, `ml`, `mr`, `ms`, `ne`, `nl`, `no`, `pa`, `pl`, `pt`, `ro`, `ru`, `si`, `sk`, `sq`, `sv`, `sw`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `yue`, `zh` - `multilingual_mode` (enum, required, default: request) — If `"auto"`, each user audio is automatically identified for the language to respond in. If `"request"`, user must request to change language (recommended). If `"initial"` the first turn user audio determines the language for the rest of the conversation. - Allowed values: `auto`, `request`, `initial` - `push_to_talk` (boolean, required, default: false) — Push to talk mode. User must send mute/unmute messages to turn on/off listening to audio. Defaults to false. - `intelligence_level` (enum, required, default: standard) — The intelligence level of the agent. `high` uses a more capable model for more complex reasoning, while `standard` is optimized for lower latency. - Allowed values: `standard`, `high` - `boosted_keywords` (list of string, required) — These words, or short phrases, will be more accurately recognized by the agent. - `pronunciation_dictionary` (list of AgentPronunciationDictionaryItems, required) — Array of `{ word, pronunciation }` entries. Words must be unique. - `min_words_to_interrupt` (integer, required, default: 1) — Minimum number of words required to interrupt the assistant. - `configuration_endpoint` (AgentConfigurationEndpoint, required, nullable) — When not `null`, the agent will call this endpoint to get configuration options. - `is_disabled` (boolean, required) — When `true`, the agent is disabled. A disabled agent cannot start conversations or be updated, except to release its phone numbers. - `phone_number` (string, required, nullable, deprecated) — The phone number that the agent uses to accept calls. `null` if the agent is not associated with a phone number, in which can the agent can be used via WebSockets. This field is deprecated. Use `phone_numbers` instead. - `websocket_timeout_sec` (integer, optional, default: 60) — Number of seconds of inactivity before the conversation WebSocket is closed. - `phonic_model` (enum, optional) — The Phonic speech-to-speech model to generate with. Omit it to use the current default model. - Allowed values: `phonic_v0_5`, `phonic_v1`, `phonic_v1_1` - `observability_integrations` (list of enum, optional) — Names of observability integrations enabled for the agent. Each must be one of the supported providers. - Allowed values: `braintrust` - `external_storage_policy` (string, optional, nullable) — Name of the external storage policy that conversation artifacts are delivered to. `null` when the agent doesn't deliver artifacts to external storage. - `inbound_rollout` (double, optional) — Float between 0.0 and 1.0 representing the percentage of inbound calls handled by Agent. Requires `phone_number` to be set when less than 1.0. - `inbound_rollout_forward_phone_number` (string, optional, nullable) — E.164 formatted phone number where non-agent calls will be forwarded. Required when `inbound_rollout < 1.0`, must be `null` when `inbound_rollout = 1.0`. - `vad_prebuffer_duration_ms` (integer, optional, default: 500) — Voice activity detection prebuffer duration in milliseconds. - `vad_min_speech_duration_ms` (integer, optional, default: 50) — Minimum speech duration for voice activity detection in milliseconds. - `vad_min_silence_duration_ms` (integer, optional, default: 800) — Minimum silence duration for voice activity detection in milliseconds. - `vad_threshold` (double, optional, default: 0.38) — Voice activity detection threshold. - `enable_redaction` (boolean, optional, default: false) — When `true`, PII and PHI are redacted from text transcripts (e.g. replaced with tags like `[PHONE]`) and bleeped from audio recordings after the conversation ends. - `enable_watermarking` (boolean, optional, default: false) — When `true`, an inaudible watermark is embedded in the audio the agent generates. - `slug` (string, optional) — The URL-friendly slug of the agent. - `enable_assistant_backchannel` (boolean, optional, default: false) — When `true`, the assistant emits backchannel cues (e.g. "mm-hmm") while the user is speaking. - `assistant_backchannel_aggressiveness` (double, optional, default: 0.1) — How aggressively the assistant backchannels, from 0 to 1. - `integrations` (list of AgentIntegration, optional) — Third-party integrations enabled for the agent. - `data_retention_policy` (DataRetentionPolicy, optional) — Controls how long transcripts and audio recordings are retained before deletion. When `zero_data_retention` is `true`, nothing is retained and `transcripts`/`audio_recordings` are omitted. - `languages` (list of enum, optional, default: ["en"], deprecated) — Array of ISO 639-1 language codes that the agent should be able to recognize. This field is deprecated. Use `default_language` and `additional_languages` instead. - Allowed values: `ar`, `az`, `bg`, `bn`, `cs`, `da`, `de`, `el`, `en`, `es`, `fa`, `fi`, `fil`, `fr`, `gu`, `he`, `hi`, `hu`, `id`, `it`, `ja`, `ka`, `km`, `kn`, `ko`, `lt`, `lv`, `ml`, `mr`, `ms`, `ne`, `nl`, `no`, `pa`, `pl`, `pt`, `ro`, `ru`, `si`, `sk`, `sq`, `sv`, `sw`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`, `yue`, `zh` ### BasicErrorError - `message` (string, required) — Error message - `code` (string, optional) — Error code ### AgentProject The project the agent belongs to. - `id` (string, required) - `name` (string, required) ### AgentTemplateVariables - `default_value` (string, required, nullable) ### AgentToolsItems ### BuiltInToolConfigs ### Task - `name` (string, required) — The name of the task. - `description` (string, required) — The description of the task. ### AgentPronunciationDictionaryItems - `word` (string, required) - `pronunciation` (string, required) ### AgentConfigurationEndpoint When not `null`, the agent will call this endpoint to get configuration options. - `url` (string, required) - `headers` (map from string to string, required) - `timeout_ms` (integer, required) — The timeout for the configuration endpoint in milliseconds. ### AgentIntegration A third-party integration enabled for an agent. - `account_id` (string, required) — The connected account ID. - `account_name` (string, required, nullable) — The connected account name. - `action_names` (list of string, required) — The integration actions available to the agent. - `app_slug` (string, required) — The slug identifying the integration app. ### DataRetentionPolicy Controls how long transcripts and audio recordings are retained before deletion. When `zero_data_retention` is `true`, nothing is retained and `transcripts`/`audio_recordings` are omitted. ### BuiltInToolConfig Configuration for a simple built-in tool (`keypad_input` or `natural_conversation_ending`). - `speech_before_tool_call` (enum, required) — Controls whether the assistant speaks before the tool is called. `required`: the assistant must speak first. `optional`: the model decides. `suppressed`: the assistant is strongly instructed to stay silent before the call (best effort). - Allowed values: `required`, `optional`, `suppressed` ### ChooseNotToRespondToolConfig Configuration for the `choose_not_to_respond` built-in tool. - `respond_after_sec` (double, optional, nullable) — Number of seconds to wait after the tool fires before the assistant speaks a follow-up if the user stays silent. When null, the assistant stays silent (default). ### DataRetentionPolicy0 Zero data retention mode. No transcripts or audio recordings are retained. - `zero_data_retention` (boolean, required) — When `true`, no transcripts or audio recordings are retained. ### DataRetentionPolicy1 Standard data retention with configurable deletion windows. - `zero_data_retention` (boolean, required) — Must be `false` for standard data retention. - `transcripts` (DataRetentionPolicyOneOf1Transcripts, required) - `audio_recordings` (DataRetentionPolicyOneOf1AudioRecordings, required) ### DataRetentionPolicyOneOf1Transcripts - `delete_after_hours` (integer, required, nullable) — Number of hours after which transcripts are deleted. Null means transcripts are retained indefinitely. ### DataRetentionPolicyOneOf1AudioRecordings - `delete_after_hours` (integer, required, nullable) — Number of hours after which audio recordings are deleted. Null means audio recordings are retained indefinitely. ## Examples **Response** ```json { "agents": [ { "id": "agent_12cf6e88-c254-4d3e-a149-a7f1bdd22783", "name": "support-agent", "phone_numbers": [ "+1234567890" ], "project": { "id": "proj_ad0334f1-2487-4155-9df3-abd8129b29ad", "name": "customer-support" }, "timezone": "America/Los_Angeles", "voice_id": "sabrina", "audio_format": "pcm_44100", "audio_speed": 1, "background_noise_level": 0, "background_noise": null, "generate_welcome_message": false, "is_welcome_message_interruptible": true, "listen_only_inbound_enabled": false, "listen_only_inbound_message": null, "welcome_message": "Hi {{customer_name}}. How can I help you today?", "system_prompt": "You are an expert in {{subject}}. Be friendly, helpful and concise.", "template_variables": { "customer_name": { "default_value": "Sean" }, "subject": { "default_value": "Chess" } }, "tools": [ "keypad_input" ], "built_in_tool_configs": { "tool_natural_conversation_ending": { "speech_before_tool_call": "suppressed" }, "tool_choose_not_to_respond": { "respond_after_sec": 5 } }, "tasks": [ { "name": "Check Availability", "description": "Check if the appointment is available" }, { "name": "Book Appointment", "description": "Book the appointment" } ], "generate_no_input_poke_text": false, "no_input_poke_sec": 30, "no_input_poke_text": "Are you still there?", "no_input_end_conversation_sec": 180, "default_language": "en", "additional_languages": [ "es" ], "multilingual_mode": "request", "push_to_talk": false, "intelligence_level": "standard", "boosted_keywords": [ "Load ID", "dispatch" ], "pronunciation_dictionary": [ { "word": "Phuket", "pronunciation": "Poo-ket" } ], "min_words_to_interrupt": 1, "configuration_endpoint": { "url": "https://api.example.com/config", "headers": { "Authorization": "Bearer token123" }, "timeout_ms": 7000 }, "is_disabled": true, "phone_number": "+1234567890" } ] } ``` **SDK Code** ```python List of agents import requests url = "https://api.phonic.ai/v1/agents" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript List of agents const url = 'https://api.phonic.ai/v1/agents'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go List of agents package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.phonic.ai/v1/agents" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby List of agents require 'uri' require 'net/http' url = URI("https://api.phonic.ai/v1/agents") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java List of agents import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.phonic.ai/v1/agents") .header("Authorization", "Bearer ") .asString(); ``` ```php List of agents request('GET', 'https://api.phonic.ai/v1/agents', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp List of agents using RestSharp; var client = new RestClient("https://api.phonic.ai/v1/agents"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift List of agents import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.phonic.ai/v1/agents")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```