Agents API

Build AI-powered conversational and task agents. Create agents with custom tools and guardrails, deploy them to messaging and voice channels, run conversations programmatically, and access interaction history. Base path: /api/v1/agents

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.agents.list();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/agents")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

CRUD Operations

Create Agent

POST /api/v1/agents

string

required

Agent display name

string

default:"custom"

Agent type. One of custom, chatbot, router, voice, workflow. Optional — defaults to custom when omitted.

string

default:"claude-sonnet-4-6"

Anthropic Claude model id. Orbit is Anthropic-only. Supported values: claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-fable-5. Note: claude-fable-5 is temporarily unavailable (export-suspended); requests pinned to it fall back to claude-opus-4-7. This list can change as models are added or availability shifts — call GET /api/v1/agents/models for the live, authoritative set.Optional. When you omit model, the agent record is created with claude-sonnet-4-6 stored as its model — this is the create-time field default, and it is the model that agent runs on.Do not confuse this with the platform default model, which the runtime resolves separately (admin pin → auto-discovery → boot fallback) for agents left on the platform default rather than pinned here. That chain can settle on a different id, so the model serving a platform-default agent need not match this field’s default. See Agent model selection.

string

System instructions that define the agent’s behavior and personality. Optional.

object[]

Tool definitions the agent can invoke

Show child attributes

string

required

Tool name

string

What the tool does

object

JSON Schema of input parameters

Channel binding is not set at create time. POST /api/v1/agents does not accept a channels field — pass it and it is silently ignored. Bind an agent to channels when you activate it via Deploy Agent.

object

Guardrail configuration enforced by Orbit’s agent runtime. There is no separate guardrails endpoint — send this on create or update.

Show child attributes

boolean

Redact detected PII from agent output

boolean

Flag inbound messages containing PII

boolean

Filter profane or unsafe content

boolean

Block harmful-content responses

boolean

Screen inbound messages for prompt-injection attempts

boolean

Require human approval before responses are sent

string[]

Topics the agent must refuse to discuss

string

Free-text content policy appended to the system guardrails

integer

Maximum characters per agent response

object[]

Conditions that hand a conversation off to a human. Each entry is one of { "type": "keyword", "value": "<string>" }, { "type": "sentiment_below", "value": <0–1> }, or { "type": "turn_count_above", "value": <positive integer> }.

string[]

IDs of knowledge bases (Qdrant collections) to attach for RAG

number

default:"0.7"

LLM temperature (0.0–2.0)

integer

default:"4096"

Maximum tokens per LLM response

curl -X POST https://api.orbit.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "type": "chatbot",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are a helpful customer support agent for Acme Corp.",
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up order details by order ID",
        "parameters": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    ],
    "safety_config": {
      "pii_redaction": true,
      "content_filter": true,
      "blocked_topics": ["competitor pricing"]
    },
    "temperature": 0.5
  }'

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "type": "chatbot",
    "model": "claude-sonnet-4-6",
    "status": "draft",
    "tools_count": 1,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_agt_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Agents

GET /api/v1/agents Retrieve all agents with cursor-based pagination.

string

Cursor for pagination

integer

default:"25"

Results per page (max 200)

string

Filter by status: draft, active, paused, archived

curl "https://api.orbit.devotel.io/api/v1/agents?limit=2&status=active" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "agt_abc123",
      "name": "Support Bot",
      "description": "Tier-1 support automation",
      "type": "chatbot",
      "status": "active",
      "system_prompt": "You are a helpful customer support agent for Acme Corp.",
      "model": "claude-sonnet-4-6",
      "temperature": 0.5,
      "max_tokens": 4096,
      "tools": [
        {
          "name": "lookup_order",
          "description": "Look up order details by order ID",
          "parameters": {
            "type": "object",
            "properties": { "order_id": { "type": "string" } },
            "required": ["order_id"]
          }
        }
      ],
      "knowledge_base_ids": ["kb_acme_faq"],
      "config": {
        "deployment": {
          "channel": "voice",
          "phone_number": "+14155550100",
          "deployed_at": "2026-03-08T12:00:00Z"
        }
      },
      "safety_config": {
        "pii_redaction": true,
        "content_filter": true,
        "blocked_topics": ["competitor pricing"]
      },
      "version": 3,
      "created_at": "2026-03-08T12:00:00Z",
      "updated_at": "2026-03-08T12:30:00Z"
    }
  ],
  "meta": {
    "request_id": "req_agt_list_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "2026-03-08T12:00:00Z|agt_abc123",
      "has_more": true,
      "total": 7
    }
  }
}

Get Agent

GET /api/v1/agents/{id} Retrieve full configuration of an agent including tools, guardrails, and deployment status.

curl https://api.orbit.devotel.io/api/v1/agents/agt_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "description": "Tier-1 support automation",
    "type": "chatbot",
    "status": "active",
    "system_prompt": "You are a helpful customer support agent for Acme Corp.",
    "model": "claude-sonnet-4-6",
    "temperature": 0.5,
    "max_tokens": 4096,
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up order details by order ID",
        "parameters": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    ],
    "knowledge_base_ids": ["kb_acme_faq"],
    "config": {
      "deployment": {
        "channel": "voice",
        "phone_number": "+14155550100",
        "deployed_at": "2026-03-08T12:00:00Z"
      }
    },
    "safety_config": {
      "pii_redaction": true,
      "content_filter": true,
      "blocked_topics": ["competitor pricing"]
    },
    "version": 3,
    "created_at": "2026-03-08T12:00:00Z",
    "updated_at": "2026-03-08T12:30:00Z"
  },
  "meta": {
    "request_id": "req_agt_get_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Update Agent

PUT /api/v1/agents/{id} Update an agent’s configuration. Changes take effect for new conversations immediately. The body is a partial update: send only the fields you are changing — omitted fields are left exactly as persisted. The same fields as Create Agent are accepted, including status (used to pause and resume an agent), tools, safety_config, and knowledge_base_ids. The response is the full updated agent record.

curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agt_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a helpful customer support agent for Acme Corp. Always confirm the order ID before looking anything up.",
    "temperature": 0.3,
    "safety_config": {
      "pii_redaction": true,
      "content_filter": true,
      "blocked_topics": ["competitor pricing"]
    }
  }'

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "type": "chatbot",
    "status": "active",
    "system_prompt": "You are a helpful customer support agent for Acme Corp. Always confirm the order ID before looking anything up.",
    "model": "claude-sonnet-4-6",
    "temperature": 0.3,
    "max_tokens": 4096,
    "knowledge_base_ids": ["kb_acme_faq"],
    "safety_config": {
      "pii_redaction": true,
      "content_filter": true,
      "blocked_topics": ["competitor pricing"]
    },
    "version": 4,
    "created_at": "2026-03-08T12:00:00Z",
    "updated_at": "2026-03-08T12:45:00Z"
  },
  "meta": {
    "request_id": "req_agt_upd_001",
    "timestamp": "2026-03-08T12:45:00Z"
  }
}

Delete Agent

DELETE /api/v1/agents/{id} Delete an agent. Active conversations are terminated gracefully.

curl -X DELETE https://api.orbit.devotel.io/api/v1/agents/agt_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

Response: 204 No Content

Deploy

Deploy Agent

POST /api/v1/agents/{id}/deploy Activate an agent and make it available on its configured channels. The agent must have a valid system_prompt.

string

required

Agent ID

string

required

The channel to deploy the agent to. One of webhook, sms, whatsapp, voice, rcs.

string

HTTPS callback URL for the webhook channel. Must be a valid HTTPS URL. An empty string is ignored and leaves any previously set URL unchanged.

string

E.164 phone number to bind the agent to. Required when channel is voice.

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/deploy \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "voice",
    "phone_number": "+14155550100"
  }'

{
  "data": {
    "id": "agt_abc123",
    "status": "active",
    "config": {
      "deployment": {
        "channel": "voice",
        "phone_number": "+14155550100",
        "deployed_at": "2026-03-08T12:00:00Z"
      }
    }
  },
  "meta": {
    "request_id": "req_deploy_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Undeploy Agent

POST /api/v1/agents/{id}/undeploy Remove an agent’s channel deployment. This clears the config.deployment metadata and sets the agent’s status to paused. For a voice deployment it also releases the bound phone number, so that number becomes available to deploy to another agent. No request body is required. To bring the agent back, call Deploy Agent again — redeploying flips the status back to active regardless of its previous state. This is distinct from pausing an agent: pausing stops new conversations but keeps the channel binding, whereas undeploying removes the binding entirely. This endpoint is rate limited to 5 requests per minute per API key, the same budget as Deploy Agent.

string

required

Agent ID

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/undeploy \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "agt_abc123",
    "status": "paused",
    "config": {}
  },
  "meta": {
    "request_id": "req_undeploy_001",
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

Pause / Resume Agent

There are no dedicated pause or resume endpoints. An agent’s lifecycle is controlled through its status field via Update Agent. To pause an agent, send PUT /api/v1/agents/{id} with { "status": "paused" }. Existing conversations are completed but no new ones are started. To resume a paused agent, send PUT /api/v1/agents/{id} with { "status": "active" }. To fully remove an agent’s channel deployment (rather than just pause it), use Undeploy Agent above. Valid status values are draft, active, paused, and archived.

curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agt_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

Chat

Send Chat Message

POST /api/v1/agents/{id}/chat Send a message to an agent and receive a response. Supports both stateless single-turn and stateful multi-turn conversations.

string

required

Agent ID

string

required

User message text

string

Existing conversation ID to append onto, for multi-turn. Omit to start a new conversation.

object[]

Optional conversation history to seed the agent, additive on top of any persisted state. Each item is { "role": "user" | "assistant" | "system", "content": string }. Use this to inject prior turns or context instead of a separate context field.

boolean

default:"false"

Run the message in sandbox mode (does not persist the conversation).

string

Associate the conversation with a contact record.

string

Channel the message originates from (e.g., whatsapp, sms, web).

Streaming is a separate endpoint — POST /api/v1/agents/{id}/chat/stream — not a stream: true flag on this request. See Streaming Responses below.

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/chat \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the status of order ORD-12345?",
    "history": [
      { "role": "user", "content": "Hi, my name is Jane Doe (customer cust_xyz)." },
      { "role": "assistant", "content": "Hi Jane! How can I help you today?" }
    ]
  }'

{
  "data": {
    "conversation_id": "conv_abc123",
    "response": "Hi Jane! I found your order ORD-12345. It was shipped yesterday via FedEx and is expected to arrive by March 10th. The tracking number is FX-987654321.",
    "detected_language": null,
    "tool_calls": [
      {
        "tool": "lookup_order",
        "input": { "order_id": "ORD-12345" },
        "output": { "status": "shipped", "carrier": "FedEx", "eta": "2026-03-10" }
      }
    ],
    "tokens_used": 307,
    "latency_ms": 1840
  },
  "meta": {
    "request_id": "req_chat_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Streaming Responses

POST /api/v1/agents/{id}/chat/stream Streaming uses a dedicated endpoint rather than a flag on the chat request. It accepts the same request body as POST /api/v1/agents/{id}/chat (message, conversationId, history, sandbox, contactId, channel) and returns the response as Server-Sent Events (SSE) with Content-Type: text/event-stream. The runtime emits six event types as the turn progresses, each carrying a single JSON data payload:

event: status — a progress update while the turn runs (for example, retrieval or routing). data is { "status": "...", "detail": "..." }; detail may be omitted.
event: token — one incremental fragment of the assistant response. data is { "content": "..." }. Concatenate every content value in order to reconstruct the streamed reply.
event: tool_start — the agent invoked a tool. data is { "tool": "...", "input": { ... } }.
event: tool_end — a tool returned. data is { "tool": "...", "input": { ... }, "output": ... }, where output is the tool result (a string or JSON value).
event: response — the completed turn. data is { "response": "...", "tokensUsed": <number>, "promptTokensUsed": <number>, "completionTokensUsed": <number>, "apiCallsUsed": <number>, "escalated": <boolean>, "conversation_id": "..." }. tokensUsed is the scalar total token count for the turn; promptTokensUsed and completionTokensUsed split it, and conversation_id is the id to reuse for follow-up turns.
event: error — a terminal failure (upstream reset, timeout, provider error). data is { "code": "...", "message": "..." }. Treat this as stream completion.

The status, token, tool_start, and tool_end events are progress frames and may arrive zero or more times in any order as the turn runs. The stream terminates with exactly one response (success) or error (failure) event, after which the connection closes.

event: status
data: {"status": "retrieving", "detail": "Looking up order history"}

event: tool_start
data: {"tool": "lookup_order", "input": {"order_id": "ORD-12345"}}

event: tool_end
data: {"tool": "lookup_order", "input": {"order_id": "ORD-12345"}, "output": {"status": "shipped", "carrier": "FedEx", "eta": "2026-03-10"}}

event: token
data: {"content": "Hi Jane! "}

event: token
data: {"content": "I found your order ORD-12345."}

event: response
data: {"response": "Hi Jane! I found your order ORD-12345. It was shipped yesterday via FedEx and is expected to arrive by March 10th.", "tokensUsed": 307, "promptTokensUsed": 210, "completionTokensUsed": 97, "apiCallsUsed": 1, "escalated": false, "conversation_id": "conv_abc123"}

On failure:

event: error
data: {"code": "UPSTREAM_RESET", "message": "Agent stream was interrupted. Please try again."}

curl -N -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/chat/stream \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What is the status of order ORD-12345?" }'

Node.js consumer (no SDK required — fetch + a line splitter over the ReadableStream):

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/agents/agt_abc123/chat/stream",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "What is the status of order ORD-12345?" }),
  },
);

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // SSE frames are separated by a blank line; each frame is one or more
  // `event:` / `data:` lines.
  const frames = buffer.split("\n\n");
  buffer = frames.pop(); // keep any partial frame for the next chunk

  for (const frame of frames) {
    const eventLine = frame.split("\n").find((l) => l.startsWith("event:"));
    const dataLine = frame.split("\n").find((l) => l.startsWith("data:"));
    const event = eventLine?.slice(6).trim();
    const data = dataLine ? JSON.parse(dataLine.slice(5).trim()) : null;

    if (event === "token") process.stdout.write(data.content);
    if (event === "tool_start") console.log(`\n[tool] ${data.tool}`);
    if (event === "response") {
      console.log(`\nconversation: ${data.conversation_id}, tokens: ${data.tokensUsed}`);
    }
    if (event === "error") throw new Error(`${data.code}: ${data.message}`);
  }
}

Python consumer (httpx — works with the async client too):

import httpx, os

url = "https://api.orbit.devotel.io/api/v1/agents/agt_abc123/chat/stream"
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
body = {"message": "What is the status of order ORD-12345?"}

with httpx.stream("POST", url, headers=headers, json=body) as res:
    event, data_lines = None, []
    for line in res.iter_lines():
        if not line:  # blank line = end of one SSE frame
            if data_lines:
                import json
                payload = json.loads(" ".join(data_lines))
                if event == "token":
                    print(payload["content"], end="", flush=True)
                elif event == "response":
                    print(f"\nconversation: {payload['conversation_id']}, tokens: {payload['tokensUsed']}")
                elif event == "error":
                    raise RuntimeError(f"{payload['code']}: {payload['message']}")
            event, data_lines = None, []
        elif line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data_lines.append(line[5:].strip())

Legacy streaming (POST //stream)

POST /api/v1/agents/{id}/stream A compatibility shim for SDK runtimes that cannot consume the preferred POST /api/v1/agents/{id}/chat/stream endpoint. It runs the same blocking turn as POST /api/v1/agents/{id}/chat, then replays the completed response over Server-Sent Events word by word, with a short gap between words, so a client gets a token-by-token render without the runtime producing true incremental tokens. Prefer chat/stream for new integrations; reach for this endpoint only when your client already expects a token / done SSE shape. It accepts the same request body as POST /api/v1/agents/{id}/chat (message, conversationId, history, sandbox, contactId, channel) and returns Content-Type: text/event-stream. The endpoint is rate limited to 20 requests per minute per tenant, the same budget as chat/stream. Three event types are emitted:

event: token — one fragment of the response. data is { "text": "..." }. The response is split on whitespace and each word and each run of whitespace is sent as its own token event, so concatenating every text value in order reconstructs the original response, spacing included.
event: done — the turn completed. data is { "totalTokens": <number>, "costCents": <number>, "conversationId": "..." }. Read conversationId to continue a multi-turn conversation.
event: error — a terminal failure. data is { "code": "...", "message": "..." }. No further events follow.

Every successful stream ends with a single done event after the last token; a failed stream ends with one error event instead. The connection then closes. If the client disconnects mid-stream, the server stops sending tokens.

event: token
data: {"text": "Hi"}

event: token
data: {"text": " "}

event: token
data: {"text": "Jane!"}

event: done
data: {"totalTokens": 307, "costCents": 4, "conversationId": "conv_abc123"}

On failure:

event: error
data: {"code": "STREAM_ERROR", "message": "Stream failed"}

curl -N -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/stream \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What is the status of order ORD-12345?" }'

Consume it with any SSE client: concatenate every token event’s data.text and stop on done (or error). The simple line-splitting consumers shown for Streaming Responses above work here unchanged.

Agent Connect (AI ↔ human voice handoff)

Agent Connect is the Node SDK’s typed surface for embedding the AI↔human voice-agent bridge — attach an AI agent to a live conference, hand a live session to a human agent with full context, and watch the session’s turns, tool calls, and handoff in real time — without hand-rolling the underlying route strings.

Connect an AI agent to a live call

POST /api/v1/voice/conferences/{conferenceId}/ai-agent Attaches agentId to a live conference as a participant. The agent leg is dialed back into the tenant’s own conference bridge — this never opens a new outbound leg.

const { data } = await orbit.agents.connect("agt_123", "conf_abcdef0123456789abcdef0123456789", {
  from: "+15551234567", // optional caller-ID override for the agent's leg
});
// data.ai_agent_row_id, data.call_sid

Call orbit.agents.disconnect(conferenceId) to remove the AI agent from the conference (DELETE /api/v1/voice/conferences/{conferenceId}/ai-agent).

Hand a live AI session to a human

POST /api/v1/voice/calls/{callId}/ai-handoff Warm-transfers a live call from an AI voice agent to a human agent: generates (or reuses) an AI call summary, persists a context packet (summary, sentiment, topics, action items, and any structured fields the agent collected) for the human agent’s screen-pop, bridges the caller into an ACD queue, then drops the AI leg once the caller is safely queued. The caller is never dropped and never dialed out — it’s routed back into the tenant’s own queueing infrastructure.

const { data } = await orbit.agents.takeover("call_789", {
  queueId: "queue_support",
  reason: "Caller asked for a refund outside policy",
  collectedSlots: { order_id: "ORD-12345", account_verified: true },
  aiAgentId: "agt_123",
});
// data.queue_position, data.summary_generated, data.bot_dropped, data.handoff

Read the persisted packet back at any time (for example, to render the screen-pop before the call is answered) with orbit.agents.getHandoff(callId) (GET /api/v1/voice/calls/{callId}/ai-handoff). handoff is null when the call was never escalated.

Watch a session in real time

orbit.agents.session.attach(callId) returns an async iterator of typed session events, merging the call’s live transcript with its assist feed:

turn — a caller/agent speech turn (partial or final).
tool-call — a one-click-executable action the agent’s assist loop proposed.
handoff — the session was just handed off to a human; carries the same packet takeover() persists.
status / end / error — stream lifecycle.

for await (const event of orbit.agents.session.attach("call_789")) {
  if (event.type === "turn") console.log(`${event.speaker}: ${event.text}`);
  if (event.type === "tool-call") console.log("tool call:", event.tool, event.args);
  if (event.type === "handoff") console.log("handed off:", event.packet.reason);
  if (event.type === "end") break;
}

Break out of the loop (or call .return() on the iterator) to close both underlying connections.

Conversations

List Conversations

GET /api/v1/agents/{id}/conversations Retrieve conversation history for an agent.

string

Cursor for pagination

integer

default:"25"

Results per page (max 200)

string

Search conversations by message content (case-insensitive substring match, max 200 characters)

curl "https://api.orbit.devotel.io/api/v1/agents/agt_abc123/conversations?limit=2&q=ORD-12345" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "conv_abc123",
      "agent_id": "agt_abc123",
      "contact_id": "cnt_jane_doe",
      "channel": "chat",
      "status": "open",
      "message_count": 3,
      "total_tokens": 307,
      "total_cost": 0.0012,
      "started_at": "2026-03-08T12:00:00Z",
      "ended_at": null,
      "updated_at": "2026-03-08T12:00:15Z"
    }
  ],
  "meta": {
    "request_id": "req_convs_001",
    "timestamp": "2026-03-08T12:01:00Z",
    "pagination": {
      "cursor": "cur_conv_started_001",
      "has_more": true
    }
  }
}

Get Conversation Messages

GET /api/v1/agents/{id}/conversations/{conversationId}/messages Retrieve the full message history of a specific conversation.

curl "https://api.orbit.devotel.io/api/v1/agents/agt_abc123/conversations/conv_abc123/messages" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "amsg_001",
      "role": "user",
      "content": "What is the status of order ORD-12345?",
      "created_at": "2026-03-08T12:00:00Z"
    },
    {
      "id": "amsg_002",
      "role": "assistant",
      "content": "Hi Jane! Your order ORD-12345 was shipped yesterday via FedEx.",
      "tool_calls": [
        { "tool": "lookup_order", "input": { "order_id": "ORD-12345" } }
      ],
      "created_at": "2026-03-08T12:00:02Z"
    },
    {
      "id": "amsg_003",
      "role": "user",
      "content": "Great, thanks!",
      "created_at": "2026-03-08T12:00:15Z"
    }
  ],
  "meta": {
    "request_id": "req_msgs_001",
    "timestamp": "2026-03-08T12:01:00Z",
    "pagination": {
      "cursor": "cur_amsg_003",
      "has_more": false,
      "total": 3
    }
  }
}

Rate Limits

Bound how often an agent can be invoked — independent of the cost controls that bound spend. Configure an agent-wide ceiling plus a separate ceiling for a single caller, so one caller looping or retrying can’t use up the invocation budget meant for everyone else. Management requires the owner or admin role; writes are audit-logged.

Get Rate Limits

GET /api/v1/agents/{id}/rate-limits Resolve an agent’s current rate-limit configuration together with live usage counters. Pass caller_id to also get that caller’s live usage and remaining headroom.

string

required

Agent ID

string

Caller/end-user identity to report live per-caller usage for (the caller number on voice, or the widget session’s contact ID on chat).

curl "https://api.orbit.devotel.io/api/v1/agents/agt_abc123/rate-limits?caller_id=%2B14155550199" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "agent_id": "agt_abc123",
    "limits": {
      "max_requests_per_minute": 60,
      "daily_quota": 5000,
      "monthly_quota": 100000,
      "rpm_per_caller": 10,
      "invocation_quota_per_caller_per_day": 200
    },
    "usage": {
      "requests_this_minute": 4,
      "used_today": 812,
      "used_this_month": 15300,
      "caller": {
        "caller_id": "+14155550199",
        "requests_this_minute": 2,
        "used_today": 35
      }
    },
    "remaining": {
      "this_minute": 56,
      "today": 4188,
      "this_month": 84700,
      "caller_this_minute": 8,
      "caller_today": 165
    }
  },
  "meta": {
    "request_id": "req_ratelimits_001",
    "timestamp": "2026-08-11T12:00:00Z"
  }
}

Set Rate Limits

PUT /api/v1/agents/{id}/rate-limits Set or clear one or more rate-limit axes. Only the fields present in the request body change — an omitted field is left untouched, and an explicit null clears that axis back to unlimited. Provide at least one field.

string

required

Agent ID

integer

Agent-wide short-burst requests-per-minute ceiling across all callers. 0 blocks all invocations; null clears the limit.

integer

Agent-wide invocations allowed per UTC calendar day.

integer

Agent-wide invocations allowed per UTC calendar month.

integer

Short-burst requests-per-minute ceiling for a single caller/end-user identity, so one abusive caller doesn’t throttle everyone else.

integer

Invocations allowed per UTC calendar day for a single caller/end-user identity.

curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agt_abc123/rate-limits \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rpm_per_caller": 10,
    "invocation_quota_per_caller_per_day": 200
  }'

MCP Servers

Register your own Model Context Protocol (MCP) servers so an agent can discover and call tools you host, without Devotel adding a built-in integration for each one. At inference time the agent runtime fetches each enabled server, lists its tools, and adds them to the agent’s tool catalog alongside built-in tools. Servers are scoped to a single agent and to your organization. Management endpoints require the owner, admin, or developer role; listing a server’s configuration is available to any authenticated member.

Register MCP Server

POST /api/v1/agents/{agentId}/mcp-servers

string

required

Agent ID the server is registered against.

string

required

Display name for the server. Must be unique within the agent — registering a second server with the same name returns 409 MCP_SERVER_NAME_CONFLICT.

string

required

The server’s endpoint. Must be a public https:// URL. URLs that resolve to private, loopback, link-local, or cloud-metadata addresses are rejected with 422 INVALID_MCP_SERVER_URL.

string

required

Transport. Only http_sse is supported.

string

A static bearer token or API key sent to your server, stored encrypted at rest. Mutually exclusive with oauth2.

object

An OAuth2 grant the runtime exchanges for a live access token before calling your server. Mutually exclusive with auth_credentials. The interactive authorization-code (browser redirect) flow is not supported.

Show child attributes

string

required

One of client_credentials or refresh_token.

string

required

Token endpoint. Same https://-only, public-address validation as server_url.

string

required

OAuth2 client id.

string

required

OAuth2 client secret (stored encrypted at rest).

string

Refresh token. Required when grant_type is refresh_token.

string

Space-separated scopes to request.

string[]

Restrict which of the server’s tools the agent can see and call. Omit to expose every discovered tool. Pass an array to expose only those tool names. Pass [] to expose none without removing the server.

object

Free-form key/value metadata stored with the server.

boolean

default:"true"

Whether the agent loads tools from this server.

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/mcp-servers \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Tools",
    "server_url": "https://mcp.acme.com/sse",
    "server_type": "http_sse",
    "auth_credentials": "secret-bearer-token",
    "tool_allowlist": ["lookup_order", "create_ticket"]
  }'

{
  "data": {
    "id": "mcpsrv_abc123",
    "organization_id": "org_abc123",
    "agent_id": "agt_abc123",
    "name": "Acme Tools",
    "server_url": "https://mcp.acme.com/sse",
    "server_type": "http_sse",
    "metadata": { "tool_allowlist": ["lookup_order", "create_ticket"] },
    "enabled": true,
    "has_auth_credentials": true,
    "auth_type": "bearer",
    "tool_allowlist": ["lookup_order", "create_ticket"]
  },
  "meta": {
    "request_id": "req_mcp_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Credentials are never returned over the wire. Responses expose only a has_auth_credentials boolean and auth_type (bearer, oauth2, or none).

List MCP Servers

GET /api/v1/agents/{agentId}/mcp-servers

string

required

Agent ID.

string

Cursor for the next page. Pass back the meta.pagination.cursor value from the previous response; omit for the first page.

integer

default:"100"

Results per page (max 200).

Returns the servers registered for the agent, newest first, with cursor-based pagination. Each entry carries id, organization_id, agent_id, name, server_url, server_type, metadata, enabled, created_at, updated_at, has_auth_credentials, and tool_allowlist (null when no allowlist is set). Use meta.pagination.cursor with has_more: true to fetch the next page.

curl "https://api.orbit.devotel.io/api/v1/agents/agt_abc123/mcp-servers?limit=100" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "mcpsrv_abc123",
      "organization_id": "org_abc123",
      "agent_id": "agt_abc123",
      "name": "Acme Tools",
      "server_url": "https://mcp.acme.com/sse",
      "server_type": "http_sse",
      "metadata": { "tool_allowlist": ["lookup_order", "create_ticket"] },
      "enabled": true,
      "created_at": "2026-03-08T12:00:00Z",
      "updated_at": "2026-03-08T12:00:00Z",
      "has_auth_credentials": true,
      "tool_allowlist": ["lookup_order", "create_ticket"]
    }
  ],
  "meta": {
    "request_id": "req_mcp_002",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "2026-03-08T12:00:00Z|mcpsrv_abc123",
      "has_more": false
    }
  }
}

Update MCP Server

PATCH /api/v1/agents/{agentId}/mcp-servers/{id} Change a registered server’s tool allowlist and/or enabled state. Send at least one field.

string

required

Agent ID.

string

required

MCP server ID.

string[] | null

An array replaces the allowlist ([] exposes no tools); null clears it so every discovered tool is exposed again; omit to leave it unchanged.

boolean

Toggle the server on or off without deleting it.

curl -X PATCH https://api.orbit.devotel.io/api/v1/agents/agt_abc123/mcp-servers/mcpsrv_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

{
  "data": {
    "id": "mcpsrv_abc123",
    "agent_id": "agt_abc123",
    "metadata": { "tool_allowlist": ["lookup_order", "create_ticket"] },
    "enabled": false,
    "tool_allowlist": ["lookup_order", "create_ticket"]
  },
  "meta": {
    "request_id": "req_mcp_003",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Delete MCP Server

DELETE /api/v1/agents/{agentId}/mcp-servers/{id} Remove a registered server. The call is idempotent: deleting an id that no longer exists returns 200 with deleted: 0 rather than a 404, so retries are safe.

string

required

Agent ID.

string

required

MCP server ID.

curl -X DELETE https://api.orbit.devotel.io/api/v1/agents/agt_abc123/mcp-servers/mcpsrv_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "deleted": 1,
    "id": "mcpsrv_abc123",
    "agent_id": "agt_abc123"
  },
  "meta": {
    "request_id": "req_mcp_004",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Probe MCP Server

POST /api/v1/agents/{agentId}/mcp-servers/probe Test a candidate URL and credentials before registering. The probe runs the same tools/list request the runtime uses at discovery time, so a successful probe predicts the server will register cleanly. Nothing is persisted.

string

required

Agent ID.

string

required

Server endpoint to probe. Same https://-only, public-address validation as on register.

string

Transport. http_sse if provided.

string

Static bearer token to test. Mutually exclusive with oauth2.

object

OAuth2 grant to test (same shape as on register). Mutually exclusive with auth_credentials.

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/mcp-servers/probe \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_url": "https://mcp.acme.com/sse",
    "server_type": "http_sse",
    "auth_credentials": "secret-bearer-token"
  }'

The response reports the outcome. status is one of ok, ssrf_blocked, timeout, unreachable, auth_failed, http_error, or protocol_error. On success tools lists the discovered tool names; otherwise error carries a short, safe explanation.

{
  "data": {
    "ok": true,
    "status": "ok",
    "tool_count": 2,
    "tools": ["lookup_order", "create_ticket"],
    "http_status": 200,
    "error": null,
    "checked_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_mcp_005",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Test MCP Server

POST /api/v1/agents/{agentId}/mcp-servers/{id}/test Health-check an already-registered server using its stored credentials, and save the result so the dashboard can show a health status without re-probing.

string

required

Agent ID.

string

required

MCP server ID.

The response uses the same verdict fields as the probe (ok, status, tool_count, tools, http_status, error, checked_at), plus the server id and agent_id.

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_abc123/mcp-servers/mcpsrv_abc123/test \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "mcpsrv_abc123",
    "agent_id": "agt_abc123",
    "ok": true,
    "status": "ok",
    "tool_count": 2,
    "tools": ["lookup_order", "create_ticket"],
    "http_status": 200,
    "error": null,
    "checked_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_mcp_006",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Agent Statuses

Status	Description
`draft`	Agent created but not yet deployed
`active`	Agent is live and accepting conversations
`paused`	Agent is temporarily deactivated
`archived`	Agent is retired and no longer deployable

Examples

Node.js

const orbit = new Devotel({ apiKey: 'dv_live_sk_xxxx' })

const agent = await orbit.agents.create({
  name: 'Support Bot',
  type: 'chatbot',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You are a helpful support agent.',
})

// Channel binding happens at deploy time, not create time.
// Deploy targets one channel per call; repeat for each channel you need.
await orbit.agents.deploy(agent.data.id, {
  channel: 'whatsapp',
  phone_number: '+15551234567',
})

const response = await orbit.agents.chat(agent.data.id, {
  message: 'Hello, I need help with my order.',
})

console.log(response.data.content)

A first-party Python SDK is on the roadmap but not yet shipped. Call the REST endpoints above with requests / httpx / any HTTP client.

API Reference

All Endpoints

Agents API overview: AI agents on messaging and voice

Agents API

Using the SDKs

CRUD Operations

Create Agent

List Agents

Get Agent

Update Agent

Delete Agent

Deploy

Deploy Agent

Undeploy Agent

Pause / Resume Agent

Chat

Send Chat Message

Streaming Responses

Legacy streaming (POST //stream)

Agent Connect (AI ↔ human voice handoff)

Connect an AI agent to a live call

Hand a live AI session to a human

Watch a session in real time

Conversations

List Conversations

Get Conversation Messages

Rate Limits

Get Rate Limits

Set Rate Limits

MCP Servers

Register MCP Server

List MCP Servers

Update MCP Server

Delete MCP Server

Probe MCP Server

Test MCP Server

Agent Statuses

Examples

Node.js

​Agents API

​Using the SDKs

​CRUD Operations

​Create Agent

​List Agents

​Get Agent

​Update Agent

​Delete Agent

​Deploy

​Deploy Agent

​Undeploy Agent

​Pause / Resume Agent

​Chat

​Send Chat Message

​Streaming Responses

​Legacy streaming (POST //stream)

​Agent Connect (AI ↔ human voice handoff)

​Connect an AI agent to a live call

​Hand a live AI session to a human

​Watch a session in real time

​Conversations

​List Conversations

​Get Conversation Messages

​Rate Limits

​Get Rate Limits

​Set Rate Limits

​MCP Servers

​Register MCP Server

​List MCP Servers

​Update MCP Server

​Delete MCP Server

​Probe MCP Server

​Test MCP Server

​Agent Statuses

​Examples

​Node.js

Agents API

Using the SDKs

CRUD Operations

Create Agent

List Agents

Get Agent

Update Agent

Delete Agent

Deploy

Deploy Agent

Undeploy Agent

Pause / Resume Agent

Chat

Send Chat Message

Streaming Responses

Legacy streaming (POST //stream)

Agent Connect (AI ↔ human voice handoff)

Connect an AI agent to a live call

Hand a live AI session to a human

Watch a session in real time

Conversations

List Conversations

Get Conversation Messages

Rate Limits

Get Rate Limits

Set Rate Limits

MCP Servers

Register MCP Server

List MCP Servers

Update MCP Server

Delete MCP Server

Probe MCP Server

Test MCP Server

Agent Statuses

Examples

Node.js