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., claude-opus-4-7, claude-sonnet-4-6, gpt-4o)

system_prompt

string

required

System instructions that define the agent’s behavior and personality

tools

object[]

Array of tool definitions the agent can invoke

Show child attributes

tools[].name

string

required

Tool name

tools[].description

string

Human-readable description of what the tool does

tools[].parameters

object

JSON Schema of the tool’s input parameters

channels

string[]

Channels this agent is available on: whatsapp, sms, voice, web

guardrails

object

Portkey guardrail configuration for output validation

cURL

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

Node.js

import { Orbit } from '@devotel/orbit-sdk'

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

const res = await fetch('https://orbit-api.devotel.io/api/v1/agents', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "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"
        ]
      }
    }
  ]
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://orbit-api.devotel.io/api/v1/agents", headers=headers, json={
  "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"
        ]
      }
    }
  ]
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://orbit-api.devotel.io/api/v1/agents", bytes.NewBuffer([]byte(`{
  "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"
        ]
      }
    }
  ]
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/agents')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "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"
        ]
      }
    }
  ]
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/agents');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "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"
        ]
      }
    }
  ]
}
JSON);
echo curl_exec($ch);

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

curl -X GET "https://orbit-api.devotel.io/api/v1/agents?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel/orbit-sdk'

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

const res = await fetch('https://orbit-api.devotel.io/api/v1/agents?limit=10', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://orbit-api.devotel.io/api/v1/agents?limit=10", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://orbit-api.devotel.io/api/v1/agents?limit=10", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/agents?limit=10')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/agents?limit=10');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

Get Agent

GET /v1/agents/{id} Retrieve a single agent and its full configuration.

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.

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.

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.

string

required

Agent ID

cursor

string

Cursor for pagination

limit

integer

default:"20"

Number of results per page (max 100)

cURL

curl -X GET "https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel/orbit-sdk'

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

const res = await fetch('https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/agents/agt_abc123/conversations?limit=5');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

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

Documentation Index

​Agents API

​Create Agent

​List Agents

​Get Agent

​Update Agent

​Delete Agent

​List Conversations

Agents API

Create Agent

List Agents

Get Agent

Update Agent

Delete Agent

List Conversations