Agents
Public API endpoints for configuring realtime voice agents.
Agents define prompt behavior, tool execution, voice settings, and phone number routing. For your first integration, follow API Getting Started, then use this page as the endpoint reference. Choose an Agent Type explains static, HTTP, and webhook agents.
All endpoints on this page use API key authentication:
Authorization: Bearer $ORBITALI_API_KEY
Public agent endpoints
| Method | Path | Description |
|---|---|---|
GET | /public/v1/agents | List agents |
GET | /public/v1/agents/{agent_id} | Get agent settings and prompt configuration |
POST | /public/v1/agents | Create an agent |
PUT | /public/v1/agents/{agent_id} | Replace an agent |
DELETE | /public/v1/agents/{agent_id} | Delete an agent |
PATCH | /public/v1/agents/{agent_id} | Partially update an agent |
GET | /public/v1/agents/{agent_id}/tools | List custom tools |
POST | /public/v1/agents/{agent_id}/tools | Create a custom tool |
PUT | /public/v1/agents/{agent_id}/tools/{tool_id} | Replace a custom tool |
DELETE | /public/v1/agents/{agent_id}/tools/{tool_id} | Delete a custom tool |
GET | /public/v1/agents/{agent_id}/mcp-tools | List connected MCP tool selections |
PUT | /public/v1/agents/{agent_id}/mcp-tools | Replace connected MCP tool selections |
GET | /public/v1/agents/{agent_id}/knowledge | List knowledge documents |
POST | /public/v1/agents/{agent_id}/knowledge | Upload a knowledge document |
DELETE | /public/v1/agents/{agent_id}/knowledge/{document_id} | Delete a knowledge document |
POST | /public/v1/agents/{agent_id}/realtime-sessions | Create a short-lived WebSocket voice session |
Phone number listing and assignment endpoints are documented in Phone Numbers, and call history and agent log endpoints in Calls & Logs. Connected MCP server discovery and tool assignment are documented in MCP Integrations.
Active-agent limits
Agent limits apply to active agents only. Draft and inactive agents can be saved without consuming the active-agent allowance, but only active agents can receive calls or start realtime sessions.
The trial allowance is 1 active agent. Paid plan allowances are controlled by the account's current plan; current defaults are Launch: 2 active agents, Studio: 10 active agents, and Agency: unlimited active agents. If an activation would exceed the current allowance, PUT and PATCH return 409 with code: "AGENT_LIMIT_EXCEEDED".
Create an agent
Creates a draft static, webhook, or http agent and its prompt configuration.
The create endpoint always creates a draft agent. To make an agent available for calls or realtime sessions, update it later with status: "active" using PUT /public/v1/agents/{agent_id} or PATCH /public/v1/agents/{agent_id}.
curl https://api.orbitali.ai/public/v1/agents \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Receptionist",
"agentType": "static",
"language": "en-US",
"aiIdentityDisclosureTemplateId": "named_agent",
"voiceName": "eve",
"phoneNumberAssignments": [],
"serverUrl": null,
"serverHeaders": {},
"serverSecret": null,
"handoffPhoneNumber": null,
"backgroundSound": "none",
"ambientSound": "none",
"ambientSoundVolume": 0.25,
"ambientSoundDucking": true,
"promptType": "static",
"identity": "You are the front desk receptionist for Acme Clinic.",
"instructions": "Answer caller questions clearly and offer to take a message.",
"greetingType": "static",
"staticGreeting": "Thanks for calling Acme Clinic. How can I help?"
}'
Response:
{
"id": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9"
}
Agent request fields
For POST, the required fields are name, language, voiceName, serverUrl, serverHeaders, serverSecret, handoffPhoneNumber, promptType, identity, instructions, greetingType, and staticGreeting. Nullable does not mean optional: send null for unused nullable fields, {} for unused headers, and strings for identity/instructions.
agentType is optional at creation but defaults to webhook; set it explicitly. It is immutable and is not an update field. phoneNumberAssignments defaults to []; audio settings default to no sound. The example above requires neither an assigned number nor a paid ambient-sound feature.
| Field | Type | Description |
|---|---|---|
name | string | Display name, 1–120 characters |
agentType | static | webhook | http | Agent integration mode. Defaults to webhook when omitted |
language | string | Realtime language variant. es-ES requests Castilian Spanish with Spain vocabulary; es-US requests US Spanish with a neutral Latin-American accent and US-Spanish usage. |
aiIdentityDisclosureTemplateId | standard | assistant_of | named_agent | virtual_assistant | named_virtual_assistant | Approved mandatory AI identity sentence. Named templates interpolate the agent's name; defaults to standard |
voiceName | string | Orbitali voice profile used for generated speech. Built-ins are eve (warm female), ara (gentle female), rex (friendly male), sal (casual male), and leo (smooth male). |
phoneNumberAssignments | object[] | Claimed phone number assignments. Each item includes phoneNumberId and optional handoffPhoneNumber used when that inbound number transfers to a human |
phoneNumberIds | string[] | Legacy-compatible claimed phone number IDs assigned to the agent. New integrations should use phoneNumberAssignments |
serverUrl | string | null | Webhook agent endpoint. Required for dynamic prompts and webhook tools. Use null for static and HTTP agents |
serverHeaders | object | Extra string headers sent to the Server URL |
serverSecret | string | null | Secret used to sign Server URL webhook requests. When present, Orbitali sends x-orbitali-signature as sha256= plus the lowercase hex HMAC-SHA256 digest of the raw JSON body |
handoffPhoneNumber | string | null | Legacy fallback phone number used by transfer_call when no per-number handoff applies |
backgroundSound | none | keyboard | Optional sound played while a tool runs. Defaults to none |
ambientSound | none | office1 | office2 | Optional low-volume sound loop mixed throughout the session. Ambient sounds are available only on Studio and Agency plans |
ambientSoundVolume | number, 0 to 1 | Ambient amplitude. Defaults to 0.25; 0 mutes it. |
ambientSoundDucking | boolean | Defaults to true; reduces ambience to 35% of the selected volume during speech. |
promptType | static | dynamic | Whether instructions are stored directly or fetched from the Server URL. Dynamic prompts are only supported by webhook agents |
identity | string | Who the agent is and what role it should play; up to 12,000 characters |
instructions | string | Saved instructions, up to 24,000 characters; the field is required in full requests even in dynamic mode |
greetingType | static | dynamic | none | How the first assistant message is selected |
staticGreeting | string | null | Required field, nullable; nonempty when greetingType is static, up to 1,000 characters |
Full PUT and partial PATCH updates also accept status, which can be draft, active, or inactive. Activating an agent counts against the account's active-agent allowance.
backgroundSound and ambientSound are independent and can be enabled together. An account without Studio or Agency access receives 403 with code: "FEATURE_NOT_AVAILABLE" when it tries to select a new non-none ambient sound. After a downgrade, an existing selection remains saved but runtime playback is disabled. Unrelated edits preserve it, and upgrading restores playback. PATCH preserves omitted audio settings.
The legacy office value remains accepted and resolves to office2.
Agent types:
static: saved identity, instructions, and greeting, with optional knowledge. Static agents do not support custom HTTP/webhook tools.webhook: saved or dynamic prompt config. Dynamic prompts useserverUrlandagent:assistant-request. Custom tools useserverUrlandagent:tool-callevents.http: saved prompt config. Custom tools call their owntoolUrlwithtoolMethodandtoolHeaders.
Mandatory AI identity disclosure is spoken only for agents running in the EU. Agents inherit their organization’s region unless overridden; legacy routing with no configured region retains disclosure. Non-EU agents keep their selected template in storage, but the editor hides it and voice sessions ignore it. Separate organization notices still apply.
AI identity disclosure templates are maintained and versioned by Orbitali. Templates follow the agent's language, with US English (en-US), Spain Spanish (es-ES), US Spanish (es-US), and Italian (it-IT) supported; other languages fall back to English. Customers can select an approved template but cannot provide arbitrary mandatory wording. Recording, transcription, privacy, organization, and purpose notices remain separately configurable.
Dynamic prompts require serverUrl and agentType: "webhook". Dynamic greetings require promptType to be dynamic.
Verify signed Server URL requests with the raw request body. Re-serialized or parsed JSON can produce a different HMAC.
Partially update an agent
Updates only the supplied fields and keeps the current phone assignments, prompt fields, greeting fields, and server config unless they are included in the request.
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9 \
-X PATCH \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expectedUpdatedAt": "2026-05-14T12:00:00.000Z",
"instructions": "Answer questions about our opening hours. Say when you do not know an answer."
}'
The Server URL signing secret can also be updated without resending the full agent:
{
"expectedUpdatedAt": "2026-05-14T12:00:00.000Z",
"serverSecret": "..."
}
Response:
{
"id": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9"
}
PATCH accepts the same fields as a full update, but every field except expectedUpdatedAt is optional. Use agent.updatedAt from GET /public/v1/agents/{agent_id} (or updatedAt from the list response) as expectedUpdatedAt. If the agent changed after that timestamp, PATCH returns 409 so the client can refetch and retry. The merged result must still be valid. For example, promptType: "dynamic" still requires an existing or supplied serverUrl, and greetingType: "dynamic" still requires dynamic prompt mode.
If the update changes a draft agent to status: "active" and the account is already at its active-agent limit, the API returns 409:
{
"error": "Active agent limit exceeded",
"code": "AGENT_LIMIT_EXCEEDED",
"maxAgents": 2
}
Deactivate another active agent or upgrade the account plan before retrying. maxAgents is the active-agent cap for the current plan or trial.
Delete an agent
DELETE /public/v1/agents/{agent_id} permanently deletes an agent owned by the
API key's organization. No request body is required.
curl -X DELETE https://api.orbitali.ai/public/v1/agents/$AGENT_ID \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Returns 200 OK:
{
"id": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9"
}
Deletion uses the same behavior as the dashboard: it removes the agent's prompt configuration, custom tools, knowledge documents, MCP tool selections, runtime logs, and web-chat settings and conversations. Phone numbers remain in the account but are unassigned from the deleted agent. Historical voice calls and their transcripts remain subject to the account's retention settings; deleting an agent is not a caller-data erasure request.
To stop new calls without deleting the configuration, update the agent's status
to inactive instead.
| Status | Meaning |
|---|---|
400 | agent_id is not a valid UUID |
401 | Missing or invalid API key |
404 | Agent does not exist, was already deleted, or belongs to another organization |
Get an agent
GET /public/v1/agents/{agent_id} returns 200 with { agent, promptConfig }. Use this endpoint to inspect saved instructions and obtain a fresh revision before PATCH.
curl --fail-with-body "https://api.orbitali.ai/public/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $ORBITALI_API_KEY"
agent contains the agent settings, including id, agentType, status, and updatedAt. serverHeaders and serverSecret are omitted from this detail response. promptConfig contains promptType, identity, instructions, greetingType, and staticGreeting, or is null if no configuration exists. Dynamic prompts are returned as saved configuration; this read does not invoke your webhook.
Replace an agent
PUT /public/v1/agents/{agent_id} replaces editable configuration and returns 200 with { "id": "<agent UUID>" }. Send the full create configuration plus status, excluding agentType. serverSecret may be omitted to preserve it; null clears it. Never send the masked value ******** as a secret.
PUT does not use expectedUpdatedAt. Prefer PATCH for isolated edits or concurrent writers. With PUT, include the complete phone assignment list you want to retain; omitted assignments default to an empty list. Neither method can change agent type. Static and HTTP agents retain static prompt mode.
List agents
Returns 200 with an array (empty when there are no agents). This endpoint has no pagination parameters. The example below shows selected fields; use the detail endpoint for saved prompt configuration.
curl https://api.orbitali.ai/public/v1/agents \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
[
{
"id": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9",
"name": "Receptionist",
"status": "draft",
"agentType": "webhook",
"language": "en-US",
"voiceName": "eve",
"serverUrl": "https://example.com/orbitali/webhook",
"serverHeaders": {},
"serverSecret": null,
"handoffPhoneNumber": null,
"phoneNumber": null,
"toolCount": 1,
"knowledgeDocumentCount": 0,
"callsToday": 0,
"successRate": 0,
"updatedAt": "2026-05-14T12:00:00.000Z"
}
]
Create a tool
Creates a custom tool for an existing webhook or HTTP agent. Static agents do not support custom tools.
For webhook agents, the agent must have a saved serverUrl. Tool executions are delivered to that Server URL as agent:tool-call events.
For HTTP agents, each tool must include toolUrl. Tool executions call that URL with toolMethod and toolHeaders. See the complete HTTP tool example. The example below is for a webhook agent with a saved Server URL. Creation returns 201 with the tool ID.
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/tools \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "lookup_customer",
"description": "Find a customer record by phone number.",
"parameterSchema": {
"type": "object",
"properties": {
"phone": { "type": "string" }
},
"required": ["phone"]
},
"responseSchema": null,
"timeoutMs": 5000,
"onError": "return_error",
"enabled": true,
"toolUrl": null,
"toolMethod": "POST",
"toolHeaders": {}
}'
Response:
{
"id": "df0ee766-7903-4c13-8547-f6bd65de392a"
}
Update a tool
Replaces an existing custom tool definition. Send the full tool object without the id field.
Static agents do not support custom tools. For HTTP agents, toolUrl is required. For webhook agents, enabling a tool requires a saved serverUrl.
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/tools/df0ee766-7903-4c13-8547-f6bd65de392a \
-X PUT \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "lookup_customer",
"description": "Find a customer record by phone number.",
"parameterSchema": {
"type": "object",
"properties": {
"phone": { "type": "string" }
},
"required": ["phone"]
},
"responseSchema": null,
"timeoutMs": 5000,
"onError": "return_error",
"enabled": true,
"toolUrl": null,
"toolMethod": "POST",
"toolHeaders": {}
}'
Response:
{
"id": "df0ee766-7903-4c13-8547-f6bd65de392a"
}
Delete a tool
Deletes an existing custom tool from an agent.
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/tools/df0ee766-7903-4c13-8547-f6bd65de392a \
-X DELETE \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
{
"id": "df0ee766-7903-4c13-8547-f6bd65de392a"
}
Tool request fields
POST and PUT require name, description, parameterSchema, responseSchema (nullable), timeoutMs, onError, and enabled. Other fields have the defaults below. PUT replaces the definition, so include optional settings you want to retain.
| Field | Type | Description |
|---|---|---|
name | string | Tool name exposed to the model |
description | string | What the tool does and when to call it |
parameterSchema | object | JSON Schema object for tool arguments |
responseSchema | object | null | Optional JSON Schema object for the tool response |
timeoutMs | number | Timeout from 1000 to 30000 milliseconds |
onError | return_error | return_empty | Behavior when tool execution fails |
enabled | boolean | Whether the tool is available during calls |
toolUrl | string | null | Required for HTTP agents. Use null for webhook tools |
toolMethod | GET | POST | PUT | DELETE | PATCH | HEAD | OPTIONS | HTTP method used with toolUrl; defaults to POST |
toolHeaders | object | String headers sent to toolUrl; defaults to {} |
toolStaticParams | object | Defaults to {}. Fixed parameters merged over model arguments; fixed values win on key collisions. |
toolContentType | application/json | null | Defaults to application/json. Applied to non-GET requests; null suppresses this default header. |
toolRuntimeMetadata | string[] | Defaults to []. Explicitly select metadata keys to forward to HTTP tools. |
HTTP GET requests encode parameters in the query string. Other methods send a JSON body. Successful HTTP responses must be 2xx and at most 256 KiB. Use concise JSON or text. Tool endpoints must use HTTPS and resolve to public addresses. Custom headers belong in toolHeaders; Orbitali sets reserved call/agent/tool headers itself.
Runtime metadata choices are callId, sessionId, agentId, toolName, fromNumber, toNumber, direction, startedAt, and providerCallId. Selected metadata is sent in _orbitali in JSON bodies or _orbitali.<key> query parameters for GET. These names are reserved when metadata is selected. Forward only the fields your endpoint needs, particularly caller phone numbers.
Webhook tool executions are delivered to the agent's Server URL as agent:tool-call events. HTTP tool executions call the tool's own toolUrl without that event envelope. responseSchema describes the response contract; your endpoint remains responsible for returning a useful result.
List tools
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/tools \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
[
{
"id": "df0ee766-7903-4c13-8547-f6bd65de392a",
"name": "lookup_customer",
"description": "Find a customer record by phone number.",
"parameterSchema": {},
"responseSchema": null,
"timeoutMs": 5000,
"onError": "return_error",
"enabled": true,
"toolUrl": null,
"toolMethod": "POST",
"toolHeaders": {}
}
]
Upload a knowledge document
Adds a document to an agent's knowledge base. The text is chunked and embedded so the agent can retrieve it during calls through the native search_knowledge tool. See the Knowledge Base guide for how retrieval works.
The endpoint accepts two content types.
JSON with text — ideal for coding agents that generate or read document text:
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/knowledge \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Refund policy",
"description": "How refunds are handled, including timelines and exceptions.",
"content": "# Refund policy\n\nRefunds are processed within 5 business days..."
}'
Multipart file upload — supports PDF in addition to text and Markdown:
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/knowledge \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-F "file=@refund-policy.pdf" \
-F "name=Refund policy"
Response:
{
"id": "b8e2c1a0-4f3d-4c7a-9e21-2f6d0a9b1c3e",
"name": "Refund policy",
"description": "How refunds are handled, including timelines and exceptions."
}
Knowledge request fields
| Field | Type | Description |
|---|---|---|
content | string | JSON mode only. The document text or Markdown, 1–1,000,000 characters. Required when not sending a file |
file | file | Multipart mode only. A .txt, .md, or .pdf upload. Required when not sending content |
name | string | Optional display title. When omitted, a title is suggested from the document content |
description | string | null | Optional one-sentence summary. When omitted, a description is suggested from the document content |
List knowledge documents
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/knowledge \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
[
{
"id": "b8e2c1a0-4f3d-4c7a-9e21-2f6d0a9b1c3e",
"name": "Refund policy",
"description": "How refunds are handled, including timelines and exceptions.",
"type": "markdown",
"sizeBytes": 1840,
"status": "ready",
"error": null,
"chunkCount": 2,
"createdAt": "2026-05-15T12:00:00.000Z"
}
]
Delete a knowledge document
Removes a document and all of its indexed chunks from the agent.
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/knowledge/b8e2c1a0-4f3d-4c7a-9e21-2f6d0a9b1c3e \
-X DELETE \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
{
"id": "b8e2c1a0-4f3d-4c7a-9e21-2f6d0a9b1c3e"
}
WebSocket voice sessions
Use WebSocket sessions when a website needs to talk to an active agent directly instead of calling through a phone number. Create the session from your backend with an Orbitali API key, then pass the returned websocketUrl to browser code. Do not expose long-lived API keys in the browser.
curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/realtime-sessions \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Response:
{
"token": "eyJ...signature",
"expiresAt": "2026-05-15T12:00:00.000Z",
"websocketUrl": "wss://agent.orbitali.ai/ws/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9?token=eyJ...signature",
"protocol": {
"inputAudio": { "encoding": "pcm16", "sampleRate": 16000 },
"outputAudio": { "encoding": "pcm16", "sampleRate": 24000 }
}
}
The WebSocket accepts JSON messages:
{ "type": "input_audio", "audio": "<base64 pcm16 16kHz mono audio>" }
Close the conversation with:
{ "type": "stop" }
The server sends:
{ "type": "session.started", "callId": "..." }
{ "type": "output_audio", "audio": "<base64 pcm16 24kHz mono audio>", "encoding": "pcm16", "sampleRate": 24000 }
{ "type": "transcript", "role": "assistant", "text": "..." }
{ "type": "clear" }
Session tokens expire after 60 seconds. Once connected, the WebSocket remains active until the conversation ends or the socket closes.
Errors
See Errors & Troubleshooting for response shapes and recovery steps. Successful creates of agents, tools, and knowledge return 201; reads, updates, deletes, and realtime-session creation return 200.
| Status | Code | Meaning |
|---|---|---|
400 | - | Invalid request body, invalid agent ID, unsupported static-agent tool, missing webhook serverUrl, missing HTTP toolUrl, missing knowledge content or file, or text that could not be extracted |
401 | - | Invalid or missing API key |
404 | - | Agent or knowledge document not found |
409 | AGENT_LIMIT_EXCEEDED | Updating an agent to active would exceed the account's active-agent allowance. The response includes maxAgents |
409 | - | Agent update conflict, or agent must be active before creating a realtime session |
500 | - | Realtime WebSocket URL or token signing is not configured |
Knowledge ingestion failures can also return 502. Unavailable ambient sound returns 403 with FEATURE_NOT_AVAILABLE. Tool updates/deletes return 404 if the tool is not found.