Orbitali Docs

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:

agentTypePrompt modeCustom actions
staticSavedNo custom HTTP/webhook tools
httpSavedDirect HTTP endpoint per tool
webhookSaved or dynamicEvents 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. Let curl -F set 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 limit and optional agentId; logs support offset pagination. Do not assume other endpoints accept pagination parameters.
  • PUT replaces configuration; PATCH changes supplied agent fields and requires expectedUpdatedAt. 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

TaskReference
Create, inspect, update, activate, or delete agentsAgents
Configure custom tools, knowledge, or voice sessionsAgents
List and assign carrier numbersPhone Numbers
Read call history, transcripts, and runtime logsCalls & Logs
Select tools from connected MCP serversMCP Integrations
Manage inbound SIP when enabledInbound SIP API
Diagnose failed requestsErrors & 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.

On this page