Skip to main content

​
Agents API

Build, configure, and deploy AI agents. Each agent can be a conversational assistant or a task-execution agent. Manage their lifecycle, invoke them programmatically, and access conversation logs. Base path: /v1/agents

​
Create Agent

POST /v1/agents Create a new AI agent.
​
name
string
required
Agent display name
​
type
string
required
Agent type: conversational or task
​
model
string
required
LLM model to use (e.g., gpt-4o, claude-sonnet-4-20250514)
​
system_prompt
string
required
System instructions that define the agent’s behavior and personality
​
tools
object[]
Array of tool definitions the agent can invoke
​
channels
string[]
Channels this agent is available on: whatsapp, sms, voice, web
​
guardrails
object
Portkey guardrail configuration for output validation
curl -X POST https://orbit-api.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": "conversational",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful customer support agent for Acme Corp.",
    "channels": ["whatsapp", "web"],
    "tools": [
      {
        "name": "lookup_order",
        "description": "Look up order details by order ID",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          },
          "required": ["order_id"]
        }
      }
    ]
  }'

{
  "data": {
    "id": "agt_abc123",
    "name": "Support Bot",
    "type": "conversational",
    "model": "gpt-4o",
    "status": "active",
    "channels": ["whatsapp", "web"],
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_agt_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
List Agents

GET /v1/agents Retrieve all agents with cursor-based pagination.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
curl "https://orbit-api.devotel.io/api/v1/agents?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​
Get Agent

GET /v1/agents/{id} Retrieve a single agent and its full configuration.
​
id
string
required
Agent ID (e.g., agt_abc123)

​
Update Agent

PUT /v1/agents/{id} Update an agent’s configuration. Changes take effect for new conversations immediately.
​
id
string
required
Agent ID
​
name
string
Updated display name
​
system_prompt
string
Updated system instructions
​
model
string
Updated LLM model
​
tools
object[]
Updated tool definitions (replaces existing tools)
​
channels
string[]
Updated channel list

​
Delete Agent

DELETE /v1/agents/{id} Delete an agent. Active conversations are terminated gracefully.
​
id
string
required
Agent ID
Response: 204 No Content

​
List Conversations

GET /v1/agents/{id}/conversations Retrieve conversation logs for a specific agent, ordered by most recent.
​
id
string
required
Agent ID
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
curl "https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "conv_001",
      "agent_id": "agt_abc123",
      "channel": "whatsapp",
      "contact_id": "con_xyz789",
      "status": "completed",
      "message_count": 12,
      "started_at": "2026-03-08T10:00:00Z",
      "ended_at": "2026-03-08T10:15:00Z"
    },
    {
      "id": "conv_002",
      "agent_id": "agt_abc123",
      "channel": "web",
      "contact_id": "con_def456",
      "status": "active",
      "message_count": 4,
      "started_at": "2026-03-08T11:30:00Z"
    }
  ],
  "meta": {
    "request_id": "req_conv_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_conv_abc",
      "has_more": true
    }
  }
}