API Getting Started
Create, activate, and test an agent with complete REST API requests.
The public REST API manages agents, custom tools, knowledge, phone assignments, connected MCP tool selections, sessions, and call history. Use the production base URL:
https://api.orbitali.ai/public/v1
This walkthrough needs an Orbitali organization, an API key, curl, and jq to extract response fields. Set ORBITALI_API_KEY in your shell from your secret manager. Examples use fictional business data and do not require a phone number or external webhook.
1. Verify access
curl --fail-with-body https://api.orbitali.ai/public/v1/agents \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Expect 200 with an array of agents, possibly []. Resolve a 401 using Authentication before continuing.
2. Create a draft agent
Choose the integration before creating the agent:
agentType | Prompt mode | Custom actions |
|---|---|---|
static | Saved | No custom HTTP/webhook tools |
http | Saved | Direct HTTP endpoint per tool |
webhook | Saved or dynamic | Events delivered to one Server URL |
Agent type is fixed after creation. The API defaults to webhook when omitted, so always set it explicitly. This example creates a static business-hours assistant:
curl --fail-with-body https://api.orbitali.ai/public/v1/agents \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Store Assistant",
"agentType": "static",
"language": "en-US",
"voiceName": "eve",
"phoneNumberAssignments": [],
"serverUrl": null,
"serverHeaders": {},
"serverSecret": null,
"handoffPhoneNumber": null,
"promptType": "static",
"identity": "You are a helpful receptionist for Example Store.",
"instructions": "Our opening hours are Monday to Friday, 9 AM to 5 PM. Answer questions about these hours. Say when you do not know an answer. Do not claim to make bookings.",
"greetingType": "static",
"staticGreeting": "Hello! How can I help you today?"
}'
Expect 201:
{ "id": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9" }
Set the ID returned by your request:
export AGENT_ID="paste-your-returned-agent-uuid"
Nullable required fields, such as serverUrl and serverSecret, must still be present in a create request. Use null when unused. See Agent request fields for required fields and defaults.
For HTTP or webhook actions, follow HTTP agents or Webhook agents before activating.
3. Activate the agent
New agents start as drafts. Read the current revision, then send it with a partial update:
AGENT_UPDATED_AT=$(curl --fail-with-body \
"https://api.orbitali.ai/public/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $ORBITALI_API_KEY" | jq -er '.agent.updatedAt')
jq -n --arg revision "$AGENT_UPDATED_AT" \
'{expectedUpdatedAt: $revision, status: "active"}' | \
curl --fail-with-body "https://api.orbitali.ai/public/v1/agents/$AGENT_ID" \
-X PATCH \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-
Expect 200 with { "id": "<your agent UUID>" }. Read the agent again to confirm agent.status is active.
expectedUpdatedAt prevents overwriting concurrent edits. Fetch a fresh revision for each PATCH. If you receive 409, inspect the body: an update conflict requires refetching and reviewing changes; AGENT_LIMIT_EXCEEDED requires freeing an active-agent slot or changing your plan.
4. Start a conversation
Create a browser session from your backend:
curl --fail-with-body "https://api.orbitali.ai/public/v1/agents/$AGENT_ID/realtime-sessions" \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Expect 200 containing token, expiresAt, websocketUrl, and the input/output audio protocol. Connect to the returned URL within 60 seconds. Creating the session alone does not make a call or stream audio; follow Browser Sessions to connect a microphone and play the response.
For a phone test, connect your carrier in the dashboard, assign a claimed number, and dial it. Agent activation and number assignment are both required for inbound calls.
5. Inspect results
curl --fail-with-body "https://api.orbitali.ai/public/v1/calls?agentId=$AGENT_ID&limit=10" \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Use a returned call ID with Get call detail for transcripts and tool activity. If a session fails before a call is available, inspect agent logs.
Request conventions
- Send JSON with
Content-Type: application/json, except multipart knowledge uploads. Letcurl -Fset the multipart boundary. - IDs are UUID strings. Timestamps are ISO 8601 UTC strings. Use returned IDs and revision timestamps rather than the illustrative values in the reference.
- List endpoints return arrays unless their reference shows an envelope. Calls support
limitand optionalagentId; logs support offset pagination. Do not assume other endpoints accept pagination parameters. PUTreplaces configuration;PATCHchanges supplied agent fields and requiresexpectedUpdatedAt. Send the full desired assignment list when updating array fields.- A timed-out create request may have succeeded. Read the relevant resource list before retrying to avoid duplicates. Do not assume an idempotency header deduplicates requests.
Find an endpoint
| Task | Reference |
|---|---|
| Create, inspect, update, activate, or delete agents | Agents |
| Configure custom tools, knowledge, or voice sessions | Agents |
| List and assign carrier numbers | Phone Numbers |
| Read call history, transcripts, and runtime logs | Calls & Logs |
| Select tools from connected MCP servers | MCP Integrations |
| Manage inbound SIP when enabled | Inbound SIP API |
| Diagnose failed requests | Errors & Troubleshooting |
Carrier account connection and MCP server connection happen in the dashboard. Dashboard billing and organization webhook settings use session authentication and are outside the public API. To receive asynchronous call start, end, and summary events for any agent type, configure Call Lifecycle Webhooks in Settings → Webhooks.