Skip to main content
Use the Agents REST API to save a voice agent’s instructions and settings. Use Omni to run its conversations. Both this API and the console edit the same profile; see Settings and customization for the field-to-UI map. You need: a key with omni:session from the intended project. An instant sandbox key belongs to its own isolated project and does not place agents in an existing console project.

Which API to use

Create the profile

Expected: 201 Created with agent_id (agent_...). Save that ID. Recording is off by default. The profile appears in the console under the project associated with the key. GET /v1/agents lists active profiles across the key’s organization; the console filters to the selected project.

Read or update settings

Partial updates use POST, not PATCH. Omitted fields stay unchanged; null clears fields that permit it. Read the response to confirm the stored values. New sessions load the update; an active call keeps its configuration.

Add custom vocabulary

Use Agent-owned vocabulary for distinctive names and phrases. See Conversation behavior and vocabulary for limits, lifetime, and controls that are stored but inactive.

Bind a hosted knowledge base

Follow Knowledge bases to create content, wait for indexing, and bind it to this agent. Knowledge writes require kb:manage; agent binding requires omni:session. Ordinary sandbox keys omit kb:manage. The guide also explains organization defaults and how to disable inheritance.

Bind tools

Follow Tools and actions to select a hosted tool or register a signed server webhook, then bind it to the agent. Do not put endpoint or webhook_url in inline Omni configure.tools; that transport is rejected.

Open a session

Pass the saved ID as session_label:
Use the Omni connection guide for authentication and the configured acknowledgement. Browser clients need an ephemeral token from your server or the hosted widget; never put a secret key in browser code. Supported inline configure fields override the saved profile for that session. REST uses persona_system_prompt; realtime uses persona.

Website or phone

Publish the website widget, build a custom browser client, or connect Twilio / FreeSWITCH. Phone actions require a transport that handles the relevant control frames.

Next