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

CRUD Operations

Create Agent

POST /api/v1/agents

name

string

required

Agent display name

type

string

default:"custom"

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

model

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. Optional — defaults to claude-sonnet-4-6 when omitted.

system_prompt

string

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

tools

object[]

Tool definitions the agent can invoke

Show child attributes

tools[].name

string

required

Tool name

tools[].description

string

What the tool does

tools[].parameters

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.

guardrails

object

Guardrail configuration for output validation (input/output checks run inside Orbit’s agent runtime).

Show child attributes

guardrails.input_checks

string[]

Input validation rules

guardrails.output_checks

string[]

Output validation rules

knowledge_base_ids

string[]

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

temperature

number

default:"0.7"

LLM temperature (0.0–2.0)

max_tokens

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"]
        }
      }
    ],
    "guardrails": {
      "output_checks": ["no_pii", "no_profanity", "brand_voice"]
    },
    "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.

cursor

string

Cursor for pagination

limit

integer

default:"20"

Results per page (max 100)

status

string

Filter by status: draft, active, paused, archived

Get Agent

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

Update Agent

PUT /api/v1/agents/{id} Update an agent’s configuration. Changes take effect for new conversations immediately.

Delete Agent

DELETE /api/v1/agents/{id} Delete an agent. Active conversations are terminated gracefully. 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 and at least one channel configured.

string

required

Agent ID

channel

string

required

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

webhook_url

string

HTTPS callback URL for the webhook channel. Must be a valid HTTPS URL; an empty string clears it.

phone_number

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"
  }
}

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" }. 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

message

string

required

User message text

conversationId

string

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

history

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.

sandbox

boolean

default:"false"

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

contactId

string

Associate the conversation with a contact record.

channel

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": { "input": 245, "output": 62 },
    "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). Each chunk is a JSON object:

event: chunk
data: {"content": "Hi Jane! I found your "}

event: chunk
data: {"content": "order ORD-12345. "}

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

event: tool_result
data: {"tool": "lookup_order", "output": {"status": "shipped"}}

event: chunk
data: {"content": "It was shipped yesterday..."}

event: done
data: {"conversation_id": "conv_abc123", "tokens_used": {"input": 245, "output": 62}}

Conversations

List Conversations

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

cursor

string

Cursor for pagination

limit

integer

default:"20"

Results per page (max 100)

status

string

Filter: active, completed, abandoned

Get Conversation Messages

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

{
  "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
    }
  }
}

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.
await orbit.agents.deploy(agent.data.id, {
  channels: ['web', 'whatsapp'],
})

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.

​Agents API

​CRUD Operations

​Create Agent

​List Agents

​Get Agent

​Update Agent

​Delete Agent

​Deploy

​Deploy Agent

​Pause / Resume Agent

​Chat

​Send Chat Message

​Streaming Responses

​Conversations

​List Conversations

​Get Conversation Messages

​Agent Statuses

​Examples

​Node.js

Agents API

CRUD Operations

Create Agent

List Agents

Get Agent

Update Agent

Delete Agent

Deploy

Deploy Agent

Pause / Resume Agent

Chat

Send Chat Message

Streaming Responses

Conversations

List Conversations

Get Conversation Messages

Agent Statuses

Examples

Node.js