Agents API

Create and manage AI agents, invoke conversations, and retrieve interaction history Base path: /api/v1/agents Endpoint count: 3

List agents

GET /api/v1/agents/

Retrieve the tenant’s AI agents with cursor-based pagination, status filtering, and free-text name search. Each row carries the agent configuration plus live conversation-derived counters (active_conversations, conversation_count, total_tokens, last_active_at).

string

Opaque cursor for the next page (from previous response meta.pagination.cursor)

integer

Number of items per page (1–200, default 25)

string

Sort field; prefix with ’-’ for descending (e.g. ‘-created_at’). Defaults to newest first.

string (enum: active|draft|paused|archived)

Filter by agent status

string

Free-text search across the agent name

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/" \
  -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://api.orbit.devotel.io/api/v1/agents/', {
  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://api.orbit.devotel.io/api/v1/agents/", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/agents/", 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://api.orbit.devotel.io/api/v1/agents/')
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://api.orbit.devotel.io/api/v1/agents/');
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);

Send a chat message to an agent

POST /api/v1/agents/{id}/chat

Proxy a chat message to the agent runtime, returning the full response in a single 200 reply. The runtime returns { data: { response, conversation_id, tokens_used }, meta }. Use POST /chat/stream for incremental token streaming.

string

required

Agent identifier (Devotel agent_xxx id). Path also accepts the alias :agentId for back-compat.

string

required

User message to send to the agent.

object[]

Optional conversation history to seed the agent (additive on top of any persisted state).

string

Existing conversation id to append onto. When omitted, a new conversation is created.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/chat" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "string"
}'

Node.js

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

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

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

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/agents/{id}/chat", bytes.NewBuffer([]byte(`{
  "message": "string"
}`)))
	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://api.orbit.devotel.io/api/v1/agents/{id}/chat')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "message": "string"
}.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://api.orbit.devotel.io/api/v1/agents/{id}/chat');
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
{
  "message": "string"
}
JSON);
echo curl_exec($ch);

Stream a chat response from an agent (SSE)

POST /api/v1/agents/{id}/chat/stream

Server-Sent Events stream of an agent turn. The response Content-Type is text/event-stream. The runtime emits six event types: status, token, tool_start, and tool_end are progress frames that may arrive zero or more times, and the stream terminates with exactly one response or error frame. The terminal response event carries

data: { "response": "...", "tokensUsed": <number>, "promptTokensUsed": <number>, "completionTokensUsed": <number>, "apiCallsUsed": <number>, "escalated": <boolean>, "conversation_id": "..." }

; a terminal error event carries data: { "code": "...", "message": "..." }. The connection persists until the agent completes or the rate-limit window is exhausted (20/min per tenant). See the API reference for the full per-event payload shapes.

string

required

Agent identifier.

string

required

User message to send to the agent.

object[]

Optional conversation history to seed the agent (additive on top of any persisted state).

string

Existing conversation id to append onto. When omitted, a new conversation is created.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/chat/stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "string"
}'

Node.js

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

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

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

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/agents/{id}/chat/stream", bytes.NewBuffer([]byte(`{
  "message": "string"
}`)))
	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://api.orbit.devotel.io/api/v1/agents/{id}/chat/stream')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "message": "string"
}.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://api.orbit.devotel.io/api/v1/agents/{id}/chat/stream');
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
{
  "message": "string"
}
JSON);
echo curl_exec($ch);

API Reference

All Endpoints

Agents API

Agents API

List agents

Send a chat message to an agent

Stream a chat response from an agent (SSE)

​Agents API

​List agents

​Send a chat message to an agent

​Stream a chat response from an agent (SSE)

Agents API

List agents

Send a chat message to an agent

Stream a chat response from an agent (SSE)