Languages: every operation supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP. The first 15 operations on this page show all six languages; the remaining 168 show cURL and TypeScript — the two most-used.

Agents API

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

title: “Worked request and response samples” description: “Worked samples for the most-asked agent operations: create an agent with a model and knowledge-base binding, send a user turn, and the error to expect when a knowledge-base id is detached.”

Worked request and response samples

Copy a request body as written, substitute your own ids, and compare the response envelope. Successful writes return { data, meta }; failures return Devotel Orbit’s { error, meta } envelope, shown once below under Error envelope.

Create an agent

POST /api/v1/agents/

Only name is required. Everything else — type, model, system_prompt, generation settings, tools, knowledge_base_ids — falls back to tenant defaults. Bind the agent to one or more knowledge bases with knowledge_base_ids and it grounds its answers on that content; every id is checked against your workspace at create time. Request

{
  "name": "After-hours support",
  "type": "chatbot",
  "model": "claude-sonnet-4-6",
  "system_prompt": "Answer from the knowledge base; escalate billing questions.",
  "knowledge_base_ids": ["kb_7c1f2a9d4b8e4f1a9c3d5e7b0a2c4e6f"]
}

{
  "data": {
    "id": "agt_3f6a81c2d4e5471a9b0c2d5e81c2d4a5",
    "name": "After-hours support",
    "type": "chatbot",
    "status": "draft",
    "model": "claude-sonnet-4-6",
    "knowledge_base_ids": ["kb_7c1f2a9d4b8e4f1a9c3d5e7b0a2c4e6f"]
  },
  "meta": {
    "request_id": "req_agt_create",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Converse with the agent

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

Send a user turn. Only message is required. Pass the conversationId from a previous reply to keep the thread going — omit it and a new conversation is created for you, its id returned on the response. When the agent grounds an answer on a bound knowledge base, the reply carries matching citations naming the documents it quoted. Request

{
  "message": "How do I reset my password?",
  "conversationId": "conv_8b2c4d6e1f3a5b7c9d0e2f4a5b6c7d"
}

{
  "conversationId": "conv_8b2c4d6e1f3a5b7c9d0e2f4a5b6c7d",
  "response": "Open Settings > Security, then choose Reset password.",
  "tokens_used": 412,
  "prompt_tokens": 301,
  "completion_tokens": 111,
  "citations": [
    {
      "document_id": "doc_9a1c3e5b7d2f4a6c8e0b1d3f5a7c9e2b",
      "document_name": "Account security FAQ"
    }
  ],
  "conversation_persisted": true
}

Error envelope

Most write failures return 422 with the offending field named in message. Creating or updating an agent re-checks every knowledge_base_ids entry against your workspace, so a detached id — one that was deleted, or copied from another tenant — fails fast here instead of silently weakening the agent’s answers.

422

{
  "error": {
    "code": "INVALID_KNOWLEDGE_BASE_IDS",
    "status": 422,
    "message": "knowledge_base_ids reference rows that do not exist in this tenant: kb_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

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/node'

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);

{
  "data": [
    {
      "id": "string",
      "name": null,
      "status": null,
      "type": null,
      "model": null,
      "description": null,
      "active_conversations": null,
      "conversation_count": null,
      "total_tokens": null,
      "last_active_at": null,
      "created_at": "1970-01-01T00:00:00.000Z",
      "updated_at": null
    }
  ],
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z",
    "pagination": {
      "cursor": "string",
      "has_more": false,
      "total": 0
    }
  }
}

List eval datasets

GET /api/v1/agents/{agentId}/evals/datasets

List the eval datasets defined for an agent, newest first. Each entry carries the dataset header (name, description, row_count, timestamps) without its rows — fetch a single dataset by id to expand the individual cases. Use this to pick a dataset to launch an eval run against.

string

required

—

integer

Maximum number of datasets to return (1–100, default 50).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/datasets" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/datasets', {
  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/{agentId}/evals/datasets", 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/{agentId}/evals/datasets", 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/{agentId}/evals/datasets')
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/{agentId}/evals/datasets');
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": {
    "agent_id": "string",
    "datasets": [
      {
        "id": "string",
        "name": "string",
        "description": null,
        "row_count": 0,
        "created_at": "1970-01-01T00:00:00.000Z",
        "updated_at": null
      }
    ]
  },
  "meta": "string"
}

Get an eval dataset

GET /api/v1/agents/{agentId}/evals/datasets/{dsId}

Fetch a single eval dataset with its full set of test rows (up to the 1000-row cap). Returns the dataset header plus every { input, expected_output, metadata } case so you can review or edit the golden set. Responds 404 when the dataset does not exist for this agent.

string

required

—

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/datasets/{dsId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/datasets/{dsId}', {
  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/{agentId}/evals/datasets/{dsId}", 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/{agentId}/evals/datasets/{dsId}", 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/{agentId}/evals/datasets/{dsId}')
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/{agentId}/evals/datasets/{dsId}');
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": "string",
    "agent_id": "string",
    "name": "string",
    "description": null,
    "row_count": 0,
    "rows": [
      {
        "id": "string",
        "input": "string",
        "expected_output": null,
        "metadata": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

List eval runs

GET /api/v1/agents/{agentId}/evals/runs

List an agent’s eval runs, newest first, with each run’s aggregate scores (avg score, passed/failed row counts, cost) and status. Optionally filter by status (pending, running, completed, failed). Use this to track regression history or find a completed run to inspect or compare.

string

required

—

string (enum: pending|running|completed|failed)

Filter runs by lifecycle status.

integer

Maximum number of runs to return (1–100, default 50).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs', {
  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/{agentId}/evals/runs", 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/{agentId}/evals/runs", 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/{agentId}/evals/runs')
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/{agentId}/evals/runs');
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": {
    "agent_id": "string",
    "runs": [
      {
        "id": "string",
        "dataset_id": "string",
        "rubric_name": "string",
        "judge_model": "string",
        "status": "string",
        "total_rows": 0,
        "passed_rows": 0,
        "failed_rows": 0,
        "avg_score": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

Get an eval run

GET /api/v1/agents/{agentId}/evals/runs/{runId}

Fetch a single eval run with its aggregate scores plus every per-row result (up to 1000): the agent’s actual output, the judge score, pass/fail, judge reasoning, latency, and cost. Use this to drill into why a run passed or failed after it completes. Responds 404 when the run does not exist for this agent.

string

required

—

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs/{runId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs/{runId}', {
  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/{agentId}/evals/runs/{runId}", 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/{agentId}/evals/runs/{runId}", 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/{agentId}/evals/runs/{runId}')
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/{agentId}/evals/runs/{runId}');
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": "string",
    "agent_id": "string",
    "dataset_id": "string",
    "rubric_name": "string",
    "judge_model": "string",
    "status": "string",
    "total_rows": 0,
    "passed_rows": 0,
    "failed_rows": 0,
    "avg_score": null,
    "results": [
      {
        "id": "string",
        "dataset_row_id": "string",
        "actual_output": null,
        "score": null,
        "passed": null,
        "judge_reasoning": null
      }
    ]
  },
  "meta": "string"
}

Compare two eval runs

GET /api/v1/agents/{agentId}/evals/runs/compare

Compare two of the agent’s eval runs (run_a_id vs run_b_id) that share the same dataset, returning each run’s aggregate scores, the overall score and pass-rate deltas, and a per-row diff of scores and outputs. Use this to confirm a prompt or model change improved quality before shipping it. Both runs must belong to this agent and reference the same dataset.

string

required

—

string

required

Baseline run id.

string

required

Candidate run id compared against the baseline.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs/compare" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs/compare', {
  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/{agentId}/evals/runs/compare", 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/{agentId}/evals/runs/compare", 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/{agentId}/evals/runs/compare')
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/{agentId}/evals/runs/compare');
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": {
    "runA": {
      "id": "string",
      "avgScore": null,
      "passedRows": 0,
      "failedRows": 0,
      "rubric": "string"
    },
    "runB": {
      "id": "string",
      "avgScore": null,
      "passedRows": 0,
      "failedRows": 0,
      "rubric": "string"
    },
    "scoreDelta": null,
    "passRateDelta": 0,
    "rowComparisons": [
      {
        "datasetRowId": "string",
        "input": "string",
        "scoreDelta": null
      }
    ]
  },
  "meta": "string"
}

List fine-tuning jobs

GET /api/v1/agents/{agentId}/fine-tuning/jobs

List an agent’s managed fine-tuning jobs alongside its registered custom models and the id of the model currently deployed for inference (active_custom_model_id, null when none). Use this to track tuning progress and see which custom model, if any, the agent is running.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/jobs" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/jobs', {
  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/{agentId}/fine-tuning/jobs", 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/{agentId}/fine-tuning/jobs", 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/{agentId}/fine-tuning/jobs')
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/{agentId}/fine-tuning/jobs');
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": {
    "agent_id": "string",
    "jobs": [
      {
        "id": "string",
        "provider": "string",
        "base_model": "string",
        "status": "string",
        "eval_run_id": "string",
        "custom_model_id": null
      }
    ],
    "custom_models": [
      {
        "id": "string",
        "provider": "string",
        "model_name": "string",
        "display_name": "string"
      }
    ],
    "active_custom_model_id": null
  },
  "meta": "string"
}

List knowledge-base document chunks

GET /api/v1/agents/{agentId}/knowledge-base/{docId}/chunks

Return a cursor-paginated list of the text chunks a knowledge-base document was split into for retrieval, each with its token count, embedding model, retrieval count, and last-retrieved timestamp — the “show me what the AI sees” inspector view. Use it to audit how a document was chunked and which passages the agent actually retrieves. Documents uploaded through the legacy knowledge-base flow return an empty chunks list with legacy_kb_no_chunks: true.

string

required

—

string

required

—

integer

Opaque page cursor returned as next_cursor by a previous call.

integer

Maximum chunks to return in this page (default 50, capped at 200).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/chunks" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/chunks', {
  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/{agentId}/knowledge-base/{docId}/chunks", 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/{agentId}/knowledge-base/{docId}/chunks", 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/{agentId}/knowledge-base/{docId}/chunks')
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/{agentId}/knowledge-base/{docId}/chunks');
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": {
    "agent_id": "string",
    "document": {},
    "chunks": [
      {}
    ],
    "total": 0,
    "next_cursor": "string",
    "legacy_kb_no_chunks": false
  },
  "meta": "string"
}

List an agent’s MCP servers

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

Return the Model Context Protocol (MCP) servers registered for an agent, keyset-paginated on (created_at, id). Each entry carries its name, URL, transport, enabled flag, tool-visibility allowlist, and a has_auth_credentials boolean — the stored credentials are never returned over the wire. Use it to review which third-party tool servers an agent can reach.

string

required

—

string

Opaque keyset cursor returned as pagination.cursor by a previous call.

integer

Maximum servers to return in this page (default 100, capped at 200).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/mcp-servers" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/mcp-servers', {
  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/{agentId}/mcp-servers", 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/{agentId}/mcp-servers", 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/{agentId}/mcp-servers')
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/{agentId}/mcp-servers');
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": [
    {}
  ],
  "meta": "string"
}

List an agent’s memory facts for a contact

GET /api/v1/agents/{agentId}/memory

Return the memory facts an agent has stored about a specific contact (pass contact_id), newest first. By default only fact-type entries are returned and any phone/email tokens in the fact bodies are PII-masked; owners, admins, and developers can pass reveal=true to unmask (each reveal is audit-logged). When the contact has opted out of memory the response is an empty list with memory_enabled: false.

string

required

—

string

required

Contact whose stored facts to list.

integer

Maximum facts to return (default 20, capped at 50).

boolean

When true (default) only fact-type entries are returned; false also includes summaries/preferences/goals.

string

Set to “true” to unmask PII in fact bodies (honoured only for owner/admin/developer).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/memory" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/memory', {
  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/{agentId}/memory", 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/{agentId}/memory", 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/{agentId}/memory')
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/{agentId}/memory');
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": {
    "items": [
      {}
    ],
    "memory_enabled": false,
    "agent_id": "string",
    "contact_id": "string",
    "facts_only": false
  },
  "meta": "string"
}

List an agent’s outcome rubrics

GET /api/v1/agents/{agentId}/outcomes/rubrics

Return the outcome-scoring rubrics configured on an agent. Each rubric defines the success criteria an LLM judge uses to grade a conversation, along with its scope and optional custom evaluator prompt. Use it to review how an agent’s conversations are being scored.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics', {
  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/{agentId}/outcomes/rubrics", 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/{agentId}/outcomes/rubrics", 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/{agentId}/outcomes/rubrics')
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/{agentId}/outcomes/rubrics');
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": {
    "rubrics": [
      {}
    ]
  },
  "meta": "string"
}

Get outcome pass-rate stats

GET /api/v1/agents/{agentId}/outcomes/stats

Return per-rubric daily pass-rate aggregates for an agent — total evaluations, pass count, and pass-rate percent bucketed by day. Use it to power the Outcomes view and watch quality trend after a prompt or model change. The window defaults to the last 30 days and accepts up to 90 via the days query parameter.

string

required

—

integer

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/stats" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/stats', {
  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/{agentId}/outcomes/stats", 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/{agentId}/outcomes/stats", 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/{agentId}/outcomes/stats')
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/{agentId}/outcomes/stats');
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": {
    "days": 0,
    "stats": [
      {
        "rubric_id": "string",
        "rubric_name": "string",
        "day": "string",
        "total": 0,
        "passed_count": 0,
        "pass_rate": 0
      }
    ]
  },
  "meta": "string"
}

Get agent quality scorecard

GET /api/v1/agents/{agentId}/quality-scorecard

Compute a continuous quality scorecard for an agent by comparing a recent window against the window immediately before it, flagging regressions in rubric pass rate, sentiment, p50/p95 latency, thumbs-down rate, and error rate. Use it right after a prompt or model change to catch silent quality degradation. Each window defaults to 7 days; pass window and min_sample to tune.

string

required

—

integer

—

integer

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/quality-scorecard" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/quality-scorecard', {
  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/{agentId}/quality-scorecard", 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/{agentId}/quality-scorecard", 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/{agentId}/quality-scorecard')
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/{agentId}/quality-scorecard');
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": {
    "agent_id": "string",
    "window_days": 0,
    "min_sample_size": 0,
    "baseline": {},
    "current": {},
    "scorecard": {},
    "canary_rollout": {}
  },
  "meta": "string"
}

Get a studio graph

GET /api/v1/agents/{agentId}/studio/graphs/{graphId}

Fetch a single Agent Studio workflow graph by id, returning its name, full graph_json (nodes and edges), lifecycle status (draft, staging, published, or archived), version, and timestamps. Use it to load a graph into the studio canvas. Returns 404 when the graph does not exist for that agent.

string

required

—

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}', {
  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/{agentId}/studio/graphs/{graphId}", 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/{agentId}/studio/graphs/{graphId}", 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/{agentId}/studio/graphs/{graphId}')
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/{agentId}/studio/graphs/{graphId}');
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": "string",
    "agent_id": "string",
    "name": "string",
    "graph_json": {},
    "status": "string",
    "version": 0,
    "published_at": "1970-01-01T00:00:00.000Z",
    "staged_at": "1970-01-01T00:00:00.000Z",
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Get a studio graph run

GET /api/v1/agents/{agentId}/studio/graphs/{graphId}/runs/{runId}

Fetch the execution trace of a single Agent Studio graph run, including the current node, accumulated state variables, per-node trace, status, and start and end timestamps. Use it to debug how a conversation traversed the workflow. Returns 404 when the graph or run does not exist for that agent.

string

required

—

string

required

—

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/runs/{runId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/runs/{runId}', {
  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/{agentId}/studio/graphs/{graphId}/runs/{runId}", 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/{agentId}/studio/graphs/{graphId}/runs/{runId}", 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/{agentId}/studio/graphs/{graphId}/runs/{runId}')
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/{agentId}/studio/graphs/{graphId}/runs/{runId}');
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": "string",
    "graph_id": "string",
    "conversation_id": "string",
    "current_node_id": "string",
    "state_vars": {},
    "status": "string",
    "trace": [
      {}
    ],
    "started_at": "1970-01-01T00:00:00.000Z",
    "ended_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Get an agent

GET /api/v1/agents/{id}

Fetch a single AI agent by id within the caller’s tenant, returning its full configuration — model, system prompt, temperature, tools, knowledge-base ids, and voice config. Use it to load an agent into an editor or to read its current settings before an update. Returns 404 when no agent with that id exists in the tenant.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": "string",
  "meta": "string"
}

Get an agent’s public A2A Agent Card

GET /api/v1/agents/{id}/.well-known/agent-card.json

Return the public A2A (Agent-to-Agent) Agent Card for an agent at the spec-canonical /.well-known/agent-card.json path. The card advertises the agent’s name, description, skills, accepted input/output modes, and HMAC authentication requirement so federation peers can discover it and delegate tasks. Unauthenticated — the tenant schema is supplied via the required ‘tenant’ query parameter, and the endpoint returns 404 unless the agent’s discovery mode is public.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/.well-known/agent-card.json" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "name": "Support Concierge",
  "description": "Answers billing and account questions and hands off to a human when needed.",
  "url": "https://api.orbit.devotel.io/agents/agent_9f2c/a2a/tasks",
  "version": "0.1.0",
  "protocolVersion": "0.3.0",
  "skills": [
    {
      "id": "chat",
      "name": "Chat",
      "description": "Multi-turn conversation answering questions and providing support.",
      "tags": [
        "chat",
        "support"
      ]
    }
  ],
  "authentication": {
    "type": "api_key",
    "header": "X-A2A-Signature"
  },
  "metadata": {
    "agentId": "agent_9f2c",
    "agentType": "chatbot",
    "provider": {
      "name": "Orbit by Devotel",
      "url": "https://orbit.devotel.io"
    }
  }
}

Get an agent’s public A2A Agent Card (legacy path)

GET /api/v1/agents/{id}/.well-known/agent.json

Legacy A2A v0.2 alias for Agent Card discovery, serving the identical payload as /.well-known/agent-card.json for federation peers that have not migrated to the newer filename. Resolves the tenant from the required ‘tenant’ query parameter and returns 404 unless the agent’s discovery mode is public.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/.well-known/agent.json" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "name": "Support Concierge",
  "description": "Answers billing and account questions and hands off to a human when needed.",
  "url": "https://api.orbit.devotel.io/agents/agent_9f2c/a2a/tasks",
  "version": "0.1.0",
  "protocolVersion": "0.3.0",
  "skills": [
    {
      "id": "chat",
      "name": "Chat",
      "description": "Multi-turn conversation answering questions and providing support.",
      "tags": [
        "chat",
        "support"
      ]
    }
  ],
  "authentication": {
    "type": "api_key",
    "header": "X-A2A-Signature"
  },
  "metadata": {
    "agentId": "agent_9f2c",
    "agentType": "chatbot",
    "provider": {
      "name": "Orbit by Devotel",
      "url": "https://orbit.devotel.io"
    }
  }
}

Get an agent’s A2A card and shareable endpoint

GET /api/v1/agents/{id}/a2a/card

Authenticated dashboard view of an agent’s A2A Agent Card plus the operator-shareable public URL to paste into a peer’s ‘Add A2A peer’ form. Unlike the public /.well-known/ route this surfaces tenant-only metadata and returns a distinct A2A_DISCOVERY_DISABLED (422) error when discovery is turned off so the UI can prompt the operator to enable it.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/card" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "card": {
      "name": "Support Concierge",
      "version": "0.1.0",
      "protocolVersion": "0.3.0"
    },
    "public_share_url": "https://api.orbit.devotel.io/agents/agent_9f2c/.well-known/agent-card.json?tenant=tenant_9f2c"
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

List an agent’s A2A peers

GET /api/v1/agents/{id}/a2a/peers

List the remote A2A peer agents registered for this agent, each with its cached Agent Card, for the dashboard’s ‘Available Peer Agents’ panel. Peers are the endpoints an operator can target with outbound task delegation.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/peers" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "peers": [
      {
        "id": "agentA2aPeer_3b8d",
        "agent_id": "agent_9f2c",
        "peer_url": "https://peer.example.com/agents/billing/a2a",
        "peer_name": "Billing Assistant",
        "created_at": "2026-07-27T12:34:56.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

List an agent’s A2A tasks

GET /api/v1/agents/{id}/a2a/tasks

List recent inbound and outbound A2A tasks for an agent, newest first, for the dashboard’s A2A ‘Task History’ panel. Accepts a ‘limit’ query parameter (1-200, default 50) and returns cursor-style pagination metadata.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/tasks" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": [
    {
      "id": "agentA2aTask_7c1f",
      "agent_id": "agent_9f2c",
      "direction": "inbound",
      "skill_id": "chat",
      "status": "submitted",
      "created_at": "2026-07-27T12:34:56.000Z",
      "updated_at": "2026-07-27T12:34:56.000Z"
    }
  ],
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z",
    "pagination": {
      "cursor": null,
      "has_more": false,
      "total": 1
    }
  }
}

Get an A2A task by id

GET /api/v1/agents/{id}/a2a/tasks/{taskId}

REST shorthand for the A2A tasks/get method — retrieve a single A2A task’s status, input, and output by id. The request must be HMAC-signed (the signature covers an empty body). Returns 404 when no task with that id exists for the agent.

string

required

—

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/tasks/{taskId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "task": {
      "id": "agentA2aTask_7c1f",
      "agent_id": "agent_9f2c",
      "direction": "inbound",
      "skill_id": "chat",
      "status": "completed",
      "output_json": {
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "Your balance is $42.00."
          }
        ]
      },
      "created_at": "2026-07-27T12:34:56.000Z",
      "updated_at": "2026-07-27T12:35:10.000Z"
    }
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

Get A/B experiment lift attribution

GET /api/v1/agents/{id}/ab/{expId}/lift

Return the lift-attribution report for an agent’s A/B experiment: per variant sample size, primary-metric mean, lift versus the control arm, p-value, and 95% confidence interval, plus which variant is leading and whether the result is ready to call. Variant A is the control. Powers the experiment lift dashboard.

string

required

Identifier of the agent running the experiment.

string

required

Identifier of the experiment to report lift for.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/ab/{expId}/lift" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "experiment_id": "string",
    "primary_metric": "string",
    "control_variant": "string",
    "variants": {
      "a": {},
      "b": {}
    },
    "leading_variant": "string",
    "ready_to_call": false,
    "generated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Fetch the agent’s active A/B experiment

GET /api/v1/agents/{id}/active-experiment

Return the currently-running A/B prompt experiment for this agent, if any, together with both variant prompt-version snapshots ready to apply at runtime. Responds with a null data payload when no experiment is active (or a referenced version was deleted), so the runtime falls back to the agent’s live configuration. Used by the agent runtime; authenticated with an internal service token.

string

required

Identifier of the agent whose active experiment to fetch.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/active-experiment" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "experiment": {},
    "variant_a": {},
    "variant_b": {}
  },
  "meta": "string"
}

Get aggregated analytics for an agent

GET /api/v1/agents/{id}/analytics

Return rolled-up performance analytics for an agent: total conversations, average tokens and cost, a tool-usage breakdown, a daily time series, and a summary of quality signals such as deflection, handoff, satisfaction, and error rates. Powers the agent’s analytics tab; a not-yet-provisioned tenant returns a zeroed shape rather than an error.

string

required

Identifier of the agent to report analytics for.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/analytics" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "total_conversations": 0,
    "avg_tokens": 0,
    "avg_cost": 0,
    "tool_usage": [
      {}
    ],
    "summary": {},
    "daily_series": [
      {}
    ]
  },
  "meta": "string"
}

Get First Contact Resolution analytics

GET /api/v1/agents/{id}/analytics/fcr

Return First Contact Resolution (FCR) analytics for an agent over a rolling 7, 30, or 90-day window: the overall FCR rate plus an LLM-clustered breakdown of conversation topics, each with its own FCR rate, satisfaction, average turns, and example messages. Results are cached for one hour per agent and window; topics are omitted until the window has at least five conversations.

string

required

Identifier of the agent to report FCR analytics for.

integer (enum: 7|30|90)

Rolling window length in days (7, 30, or 90).

integer

Maximum number of topics to cluster (1-20).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/analytics/fcr" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agentId": "string",
    "windowDays": 0,
    "totalConversations": 0,
    "overallFcrRate": 0,
    "topics": [
      {
        "topic": "string",
        "conversationCount": 0,
        "fcrRate": 0,
        "avgSatisfactionScore": 0,
        "avgTurnsPerConversation": 0,
        "examples": [
          "string"
        ]
      }
    ]
  },
  "meta": "string"
}

List an agent’s conversations

GET /api/v1/agents/{id}/conversations

Return a paginated list of conversations handled by this agent, newest first, with contact, channel, message count, and status for each. Pass an optional q to search conversation content. Powers the agent’s conversation-history tab; a not-yet-provisioned tenant returns an empty page rather than an error.

string

required

Identifier of the agent whose conversations to list.

integer

Maximum number of conversations to return per page.

string

Opaque pagination cursor from a previous response.

string

Optional case-insensitive substring to search conversation content (max 200 chars).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/conversations" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": [
    {
      "id": "string",
      "contact_phone": "string",
      "contact_email": "string",
      "channel": "string",
      "status": "string",
      "message_count": 0,
      "started_at": "1970-01-01T00:00:00.000Z",
      "last_message_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "meta": "string"
}

List messages in an agent conversation

GET /api/v1/agents/{id}/conversations/{conversationId}/messages

Return the messages of a single conversation belonging to this agent, oldest first, up to the requested limit. Verifies the conversation belongs to the agent and returns 404 when the agent or conversation does not exist. Powers the per-conversation transcript view.

string

required

Identifier of the agent that owns the conversation.

string

required

Identifier of the conversation to read messages from.

integer

Maximum number of messages to return (1-200, default 50).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/conversations/{conversationId}/messages" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "conversation_id": "string",
    "agent_id": "string",
    "messages": [
      {
        "role": "string",
        "content": "string"
      }
    ],
    "total_messages": 0,
    "returned_messages": 0
  },
  "meta": "string"
}

Export an agent’s conversations as CSV

GET /api/v1/agents/{id}/conversations/export

Download this agent’s conversations as a CSV attachment with one row per conversation — conversation id, contact, channel, start and last-message timestamps, message count, and status. Returns up to 10,000 rows for offline analysis and reporting; a not-yet-provisioned tenant returns a header-only CSV rather than an error.

string

required

Identifier of the agent whose conversations to export.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/conversations/export" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Resolve an agent’s conversation cost cap

GET /api/v1/agents/{id}/cost-cap

Resolve the effective per-conversation spend cap (in cents) for an agent by walking the precedence chain agent → organization → platform default, then clamping to the platform hard ceiling. A cap_cents of null means unbounded, and source reports which layer set the value. The agent runtime reads this before every chat turn; authenticated with an internal service token.

string

required

Identifier of the agent whose cost cap to resolve.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/cost-cap" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "cap_cents": 0,
    "source": "agent"
  },
  "meta": "string"
}

List agent A/B experiments

GET /api/v1/agents/{id}/experiments

List the A/B prompt experiments for this agent, newest first, each enriched with per-variant impression and conversion counts. Filter to running or finished experiments with the status query param. Use it to render the experiments panel and pick one to inspect.

string

required

Agent identifier (Devotel agent_xxx id).

string (enum: active|ended|all)

Filter by experiment state (default all).

integer

Maximum number of experiments to return (1–200, default 50).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/experiments" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "experiments": [
      {
        "id": "string",
        "agent_id": "string",
        "name": "string",
        "variant_a_version_id": "string",
        "variant_b_version_id": "string",
        "traffic_split_pct": 0,
        "conversion_metric": "reply_received",
        "started_at": "1970-01-01T00:00:00.000Z",
        "ended_at": null,
        "winner": "a",
        "created_by_user_id": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Get A/B experiment detail

GET /api/v1/agents/{id}/experiments/{expId}

Return the full detail for one experiment: per-variant stats, a two-proportion chi-square significance test, the current adaptive traffic split, a winner recommendation, and a ready_to_call flag (95% significance with at least 30 impressions per arm). This is the read the experiment results view renders.

string

required

Agent identifier (Devotel agent_xxx id).

string

required

Experiment id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/experiments/{expId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "experiment": {
      "id": "string",
      "agent_id": "string",
      "name": "string",
      "variant_a_version_id": "string",
      "variant_b_version_id": "string",
      "traffic_split_pct": 0,
      "conversion_metric": "reply_received",
      "started_at": "1970-01-01T00:00:00.000Z",
      "ended_at": null,
      "winner": "a",
      "created_by_user_id": null,
      "created_at": "1970-01-01T00:00:00.000Z"
    },
    "significance": {},
    "allocation": {},
    "promotion_recommendation": {},
    "ready_to_call": false
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

List an agent’s handoff events

GET /api/v1/agents/{id}/handoffs

Return the cross-agent handoff events in which this agent was the source or the target, newest first. Each entry records the source and target agent, the conversation it happened in, the reason, and a short summary of what was transferred. Pass the optional conversation_id query param to narrow the list to a single conversation. Powers the handoff divider chip in the conversation viewer.

string

required

Identifier of the agent whose handoff events to list.

string

Restrict the list to handoffs that occurred within this conversation.

integer

Maximum number of handoff events to return (1–100, default 50).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/handoffs" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "handoffs": [
      {
        "id": "string",
        "source_agent_id": "string",
        "target_agent_id": "string",
        "conversation_id": "string",
        "reason": "string",
        "summary": "string",
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

List recent agent handoffs

GET /api/v1/agents/{id}/handoffs/recent

Returns the most recent cross-agent handoffs where this agent was the source or target, newest first. This is the activity shown in the Handoff Targets section of the agent detail page.

string

required

Agent identifier (Devotel agent_xxx id).

integer

Maximum number of handoff rows to return (1–100, default 25).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/handoffs/recent" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "handoffs": [
      {
        "id": "string",
        "source_agent_id": "string",
        "target_agent_id": "string",
        "conversation_id": null,
        "reason": null,
        "summary": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

List an agent’s prompt version history

GET /api/v1/agents/{id}/prompt-history

Return the agent’s prompt version rows newest-first, with the distinct branch list and a pagination cursor. This is a friendly alias of GET /agents//versions with an identical response shape, so integrations can read version history without the git-style versions path.

string

required

Agent identifier (Devotel agent_xxx id).

integer

Number of versions per page (1–200, default 50).

integer

Return versions with version_number below this value (for paging).

string

Restrict to a single branch name.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/prompt-history" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "agent_name": null,
    "current_version": 0,
    "versions": [
      {
        "id": "string",
        "version_number": 0,
        "branch": null,
        "label": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ],
    "branches": [
      "string"
    ],
    "next_cursor": null
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Get an agent’s invocation rate limits and live usage

GET /api/v1/agents/{id}/rate-limits

Resolve an agent’s invocation rate limits — agent-wide max_requests_per_minute, daily_quota, monthly_quota and per-caller rpm_per_caller, invocation_quota_per_caller_per_day — together with live usage counters. For every axis, null means unlimited and 0 blocks all invocations. Pass caller_id to also include that caller’s live per-caller usage and remaining headroom (the caller identity is opaque here — the caller number on voice, or the widget session’s contact id on chat). Requires the owner or admin role.

string

required

Identifier of the agent whose rate limits to resolve.

string

Optional caller/end-user identity to also report live per-caller usage and remaining headroom for.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/rate-limits" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "limits": "string",
    "usage": {
      "requests_this_minute": 0,
      "used_today": 0,
      "used_this_month": 0,
      "caller": {
        "caller_id": "string",
        "requests_this_minute": 0,
        "used_today": 0
      }
    },
    "remaining": {
      "this_minute": 0,
      "today": 0,
      "this_month": 0,
      "caller_this_minute": 0,
      "caller_today": 0
    }
  },
  "meta": "string"
}

List an agent’s saved regression tests

GET /api/v1/agents/{id}/regression-tests

List the regression tests saved for an agent, most recent first. Each entry bundles the saved conversation and its expected-output assertions along with the status, timestamp, and captured output of its most recent run, so the studio panel can show pass/fail history at a glance.

string

required

Identifier of the agent whose tests to list.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/regression-tests" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "tests": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "last_run_status": "string",
        "last_run_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

Compare a shadow agent against production

GET /api/v1/agents/{id}/shadow-comparison

Return recent shadow-versus-production comparison logs for a shadow agent over a look-back window, each joined with the production counterpart’s response. Includes a per-log agreement score and a summary with exact-match percentage, average agreement, and token and cost economics, so an operator can judge a shadow candidate before promoting it. Requires owner, admin, or developer role.

string

required

Identifier of the shadow agent to inspect.

integer

Inclusive look-back window in days (default 7).

integer

Maximum number of comparison logs to return (1-200, default 50).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/shadow-comparison" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "shadow_of_agent_id": "string",
    "is_shadow": false,
    "summary": {
      "total_logs": 0,
      "exact_match_pct": 0,
      "avg_agreement_pct": 0,
      "days": 0
    },
    "logs": [
      {}
    ]
  },
  "meta": "string"
}

Look up the squad an agent classifies

GET /api/v1/agents/{id}/squad

Resolve whether this agent is the classifier (entry point) of an active agent squad. Returns the squad configuration with its member agents, their intent labels, and the fallback agent when one exists, or a null data payload when the agent does not front a squad. The agent runtime calls this on each inbound turn to decide whether to run squad routing before invoking the executor.

string

required

Identifier of the agent to test for squad membership.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/squad" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "name": "string",
    "classifier_agent_id": "string",
    "members": [
      {
        "agent_id": "string",
        "intent_labels": [
          "string"
        ],
        "description": "string"
      }
    ],
    "fallback_agent_id": "string",
    "active": false
  },
  "meta": "string"
}

List an agent’s recent tool calls

GET /api/v1/agents/{id}/tool-history

Return the most recent tool-call dispatches made by an agent, newest first, with cursor pagination and an optional conversationId filter. Each row records the tool name, inputs, and outputs (PII-redacted at write time) so operators can audit what the agent actually did. Requires owner, admin, or developer role.

string

required

Identifier of the agent whose tool history to read.

string

Opaque cursor from a prior page.

integer

Maximum rows to return (1-200, default 50).

string

Restrict the history to a single conversation thread.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/tool-history" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "rows": [
      {
        "id": "string",
        "tool_name": "string",
        "conversation_id": "string",
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ],
    "next_cursor": "string",
    "count": 0
  },
  "meta": "string"
}

List an agent’s prompt versions

GET /api/v1/agents/{id}/versions

List an agent’s saved prompt versions, newest first, with cursor pagination and an optional branch filter. Each entry captures the prompt, model, and settings snapshot for that version. The response also returns the agent’s current version number and the set of branch names, powering the version-history and diff surfaces.

string

required

Identifier of the agent whose versions to list.

integer

Return versions with a version_number below this value (pagination cursor).

string

Narrow the list to a single experiment branch.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/versions" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "agent_name": "string",
    "current_version": 0,
    "versions": [
      {
        "id": "string",
        "version_number": 0,
        "branch": "string",
        "model": "string"
      }
    ],
    "branches": [
      "string"
    ],
    "next_cursor": 0
  },
  "meta": "string"
}

Diff two agent prompt versions

GET /api/v1/agents/{id}/versions/{vid}/diff

Return a field-level diff between the version in the path and a comparison target, for the versioned fields (prompt, model, temperature, max tokens, tools, knowledge bases, safety config, config, and cost cap). Set the against query param to prev (the immediately preceding version, the default), live (the agent’s current live config), or another version id on the same agent. Powers the compare-versions view; the first version returns an all-unchanged diff with against: null.

string

required

Identifier of the agent whose versions to diff.

string

required

Identifier of the source version (the path side of the diff).

string

Comparison target: prev, live, or another version id on the same agent.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/versions/{vid}/diff" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "changed_count": 0,
    "against": {},
    "fields": [
      {
        "field": "string",
        "before": "string",
        "after": "string",
        "changed": false
      }
    ]
  },
  "meta": "string"
}

Get an agent’s voice runtime config

GET /api/v1/agents/{id}/voice-config

Return the compact voice-specific configuration the voice gateway needs to run or reconfigure a live call for this agent: its instructions, voice preset, translation target language, opening greeting, and the per-agent audio toggles (background-speech denoising, live accent softening, and ambient sound bed). Used during a multi-agent squad handoff to re-point an in-flight session at the new agent.

string

required

Identifier of the agent whose voice config to fetch.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/{id}/voice-config" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "agent_id": "string",
    "instructions": "string",
    "voice": "string",
    "translation_target_language": "string",
    "first_message": "string",
    "denoise": false,
    "accent_softening": {
      "enabled": false,
      "target_accent": "string",
      "intensity": 0
    },
    "ambient_sound": {
      "enabled": false,
      "sound": "string",
      "volume": 0
    }
  },
  "meta": "string"
}

Export the AI-turn audit log

GET /api/v1/agents/ai-turn-audit

Export your tenant’s immutable AI decision history across all conversations for periodic SOC2, HIPAA, FINRA, or GDPR compliance review. Optionally filter by agentId, conversationId, and a from/to date range, then page by cursor until next_cursor is null. Because it surfaces the entire tenant’s decision history verbatim, this route requires an owner or admin role (stricter than the per-conversation view).

integer

Maximum number of audit rows to return (1–200, default 50).

string

Opaque pagination cursor from a previous response.

string

Restrict the export to rows produced by this agent.

string

Restrict the export to rows within this conversation.

string

ISO-8601 lower bound (inclusive) on the row timestamp.

string

ISO-8601 upper bound (exclusive) on the row timestamp.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/ai-turn-audit" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "rows": [
      "string"
    ],
    "next_cursor": "string",
    "count": 0
  },
  "meta": "string"
}

List all agent conversations

GET /api/v1/agents/conversations

Return a paginated list of agent conversations across your tenant, newest first, spanning every agent. Filter by agent_id, status (active, closed, archived), a from/to date range, and the classifier-derived sentiment (positive, negative, neutral) or intent. This powers the supervisor conversation-history board. Requires an owner or admin role (the supervisor seat is also admitted).

integer

Maximum number of conversations to return per page.

string

Opaque pagination cursor from a previous response.

string

Restrict the list to conversations handled by this agent.

string (enum: active|closed|archived)

Filter conversations by lifecycle status.

string

Only include conversations started at or after this timestamp.

string

Only include conversations started before this timestamp.

string (enum: positive|negative|neutral)

Filter by the classifier-derived sentiment label.

string

Filter by the classifier-derived primary intent/topic.

cURL

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

Node.js

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

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

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

{
  "data": [
    {
      "id": "string",
      "agent_id": "string",
      "status": "string",
      "channel": "string",
      "started_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "meta": "string"
}

Get an agent conversation

GET /api/v1/agents/conversations/{conversationId}

Return a single agent conversation by id, including its full message transcript, contact and channel, status, and metadata such as sentiment and satisfaction. This backs the supervisor conversation-detail view and the transcript viewer for closed conversations. Returns 404 when the conversation does not exist for your tenant. Requires an owner or admin role.

string

required

Identifier of the agent conversation to fetch.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "status": "string",
    "channel": "string",
    "messages": [
      {}
    ],
    "started_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Get a conversation’s AI-turn audit log

GET /api/v1/agents/conversations/{conversationId}/ai-turn-audit

Return the immutable per-turn audit trail for one agent conversation, the chain of decisions the AI made, oldest first. Each row carries the verbatim system and user prompt, the model, the response, token counts, and any human-override stamp. Cursor-paginated and optionally bounded by a from/to date range. This is a supervisor-level compliance surface (the full prompt text is included verbatim) and requires an owner, admin, or developer role.

string

required

Identifier of the agent conversation to export the audit trail for.

integer

Maximum number of audit rows to return (1–200, default 50).

string

Opaque pagination cursor from a previous response.

string

ISO-8601 lower bound (inclusive) on the row timestamp.

string

ISO-8601 upper bound (exclusive) on the row timestamp.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/ai-turn-audit" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "rows": [
      "string"
    ],
    "next_cursor": "string",
    "count": 0
  },
  "meta": "string"
}

Get an agent conversation’s debug log

GET /api/v1/agents/conversations/{conversationId}/debug-log

Return the per-turn debug log for one agent conversation — for each turn the model used, the latency breakdown, cost in cents, the tool calls it made, and the knowledge retrievals it scored. Use it to trace exactly what the agent did during a session when diagnosing a bad answer, a slow turn, or an unexpected tool call. Results are keyset-paginated on turn index via the opaque cursor. Requires an owner, admin, or developer role.

string

required

Agent conversation identifier.

integer

Maximum number of turns to return (1–500).

string

Opaque pagination cursor returned as meta.pagination.cursor by the previous page.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/debug-log" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "conversation_id": "string",
    "turns": [
      {
        "id": "string",
        "turn_index": 0,
        "model": null,
        "latency_ms": null,
        "cost_cents": null,
        "tool_calls": [
          {}
        ],
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z",
    "pagination": {
      "cursor": null,
      "has_more": false
    }
  }
}

List handoffs within an agent conversation

GET /api/v1/agents/conversations/{conversationId}/handoffs

Return the cross-agent handoffs that occurred within a single agent conversation, oldest first. Each entry records the source and target agent, the reason, and a short summary of what was transferred. The conversation viewer uses this to draw handoff dividers between turns so you can see where one agent passed the customer to another.

string

required

Agent conversation identifier.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/handoffs" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "conversation_id": "string",
    "handoffs": [
      {
        "id": "string",
        "source_agent_id": "string",
        "target_agent_id": "string",
        "conversation_id": null,
        "reason": null,
        "summary": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

Get outcome scores for a conversation

GET /api/v1/agents/conversations/{conversationId}/outcomes

Return the outcome-rubric results scored for one agent conversation — for each rubric the conversation was graded against, whether it passed, the judge’s confidence, and its reasoning. The supervisor conversation-detail view uses this to show why a session was marked a success or failure. Requires the agents:read scope.

string

required

Agent conversation identifier.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/outcomes" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "outcomes": [
      {
        "id": "string",
        "conversation_id": "string",
        "rubric_id": "string",
        "rubric_name": "string",
        "scope": null,
        "passed": false,
        "confidence": null,
        "reasoning": null,
        "conversation_type": null,
        "scored_by": null,
        "evaluated_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

List supervisor notes for a conversation

GET /api/v1/agents/conversations/{conversationId}/supervisor-notes

Return the most recent supervisor notes attached to an agent conversation (up to 20, newest first) for the history panel and audit trail. Requires an owner, admin, or supervisor role.

string

required

Agent conversation identifier.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/supervisor-notes" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "conversation_id": "string",
    "notes": [
      {
        "id": "string",
        "note": "string",
        "author_user_id": null,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": "string"
}

List live agent conversations

GET /api/v1/agents/conversations/live

Return the agent conversations currently in progress across your tenant — active chat, API, and text-channel sessions plus live voice-agent calls — most recently active first, capped at 100. This powers the supervisor “Live” board so an operator can watch conversations as they happen and jump in. Requires an owner or admin role.

cURL

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

Node.js

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

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

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

{
  "data": {
    "conversations": [
      {
        "id": "string",
        "agent_id": null,
        "contact_id": null,
        "status": "string",
        "channel": null,
        "turn_count": 0,
        "preview": "string",
        "last_activity_at": null
      }
    ],
    "generatedAt": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

List a tenant’s connected CRM providers

GET /api/v1/agents/crm-tools/internal/active-providers

Return the CRM providers (HubSpot, Salesforce, Zendesk, Calendly, Intercom) the tenant has an active integration connection for. The AI agent runtime calls this while assembling an agent’s tool set so it only offers CRM tools that will actually resolve — a tool for a provider the tenant has not connected is skipped. Internal service-to-service endpoint, authenticated with the runtime internal token rather than a tenant API key.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/crm-tools/internal/active-providers" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "providers": [
      "hubspot"
    ],
    "total": 0
  },
  "meta": "string"
}

List custom agent tools

GET /api/v1/agents/custom-tools

Return the tenant’s custom agent tools — webhook-backed tools you define so agents can call your own APIs. Each entry includes the tool’s name, description, JSON-Schema parameters, executor URL, enabled flag, timeout, and confirmation mode. The encrypted executor secret is never returned; executor_secret_set reports only whether one is configured.

cURL

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

Node.js

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

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

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

{
  "data": {
    "tools": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "json_schema": {},
        "executor_url": "string",
        "executor_secret_set": false,
        "enabled": false,
        "timeout_ms": 0,
        "confirmation": "string",
        "created_by_user_id": "string",
        "created_at": "1970-01-01T00:00:00.000Z",
        "updated_at": "1970-01-01T00:00:00.000Z"
      }
    ],
    "total": 0
  },
  "meta": "string"
}

Get a custom tool

GET /api/v1/agents/custom-tools/{id}

Fetch a single tenant-owned custom tool by id, including its JSON-Schema parameters, executor URL, enabled flag, timeout, confirmation mode, and per-tool spoken messages. The encrypted webhook secret is never returned — executor_secret_set reports only whether one is configured. Use this to populate the custom-tool builder/edit UI.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/custom-tools/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "json_schema": {},
    "executor_url": "string",
    "executor_secret_set": false,
    "enabled": false,
    "timeout_ms": 0,
    "confirmation": "string",
    "created_by_user_id": "string",
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

List enabled custom tools (internal)

GET /api/v1/agents/custom-tools/internal/list

Internal service-to-service endpoint (X-Internal-Token auth) the agent runtime calls when building an agent’s tool registry. Returns every enabled tenant-owned custom tool with its JSON-Schema parameters, executor URL, timeout, and confirmation mode — the encrypted webhook secret is never included (dispatch happens server-side). The list is capped at a generous per-tenant ceiling to bound the payload.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/custom-tools/internal/list" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "tools": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "json_schema": {},
        "executor_url": "string",
        "executor_secret_set": false,
        "enabled": false,
        "timeout_ms": 0,
        "confirmation": "string"
      }
    ],
    "total": 0
  },
  "meta": "string"
}

List knowledge-base coverage gaps

GET /api/v1/agents/knowledge-bases/{id}/gaps

Surface the questions a knowledge base could not confidently answer over a look-back window, clustered into themes with a representative question, how many times it was asked, and how many distinct contacts hit it. Gaps are drawn from low-confidence answers and human escalations across every agent linked to the KB. Use it to decide which articles to write next; an unlinked KB returns an empty cluster list.

string

required

Identifier of the knowledge base to analyse.

integer

Look-back window in days (1–180, default 30).

integer

Maximum number of gap clusters to return (1–50, default 10).

string

Narrow the analysis to a single agent linked to the KB.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/knowledge-bases/{id}/gaps" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "kb_id": "string",
    "days": 0,
    "agent_ids": [
      "string"
    ],
    "total_low_confidence": 0,
    "total_escalations": 0,
    "clusters": [
      {
        "cluster_id": "string",
        "representative_question": "string",
        "question_count": 0,
        "contact_count": 0,
        "recent_examples": [
          {
            "question": "string",
            "conversation_id": "string",
            "created_at": "1970-01-01T00:00:00.000Z"
          }
        ],
        "evidence": "string"
      }
    ]
  },
  "meta": "string"
}

Get the org’s BYO LLM inference credential config

GET /api/v1/agents/llm-provider-credential

Returns this organization’s bring-your-own LLM inference credential configuration (or null when unset), the supported Anthropic-native provider catalog (your own Anthropic key, or an in-region Bedrock / Vertex endpoint serving Claude — never a second model vendor), and the resolved posture (enabled / enforced / fingerprint). The raw credential is never stored or echoed — only its truncated SHA-256 fingerprint. Read-only; requires agents:read.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

"string"

Browse the agent template marketplace

GET /api/v1/agents/marketplace

List the approved agent templates published to the marketplace, with optional filters for category, channel, free-text search over name, description, and tags, plus a featured-only flag. Featured templates sort first, then by install count. Use this to render the template gallery when an operator creates a new agent from a pre-built starting point.

string

Filter to a single template category.

string

Return only templates that support this channel.

string

Case-insensitive match on name, description, or tags.

boolean

When true, return only featured templates.

integer

Maximum number of templates to return (1–100, default 50).

cURL

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

Node.js

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

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

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

{
  "data": {
    "templates": [
      "string"
    ],
    "total": 0,
    "filters": {}
  },
  "meta": "string"
}

Get a marketplace template

GET /api/v1/agents/marketplace/{slug}

Fetch a single approved marketplace template by slug, including its full system prompt and conversation starters, for the template detail / preview page. Pending or rejected slugs return 404 so unapproved template content is never exposed to non-moderators.

string

required

Slug of the marketplace template to fetch.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/marketplace/{slug}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": "string",
  "meta": "string"
}

List templates pending moderation

GET /api/v1/agents/marketplace/pending

Return the platform-wide queue of marketplace templates awaiting moderation, oldest first so older submissions are reviewed before newer ones. Each entry carries the full template payload plus the submitting tenant id so the moderation UI can render a “submitted by” label. Platform-admin only; other callers receive 403.

integer

Maximum number of pending templates to return (1–100, default 50).

cURL

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

Node.js

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

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

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

{
  "data": {
    "templates": [
      "string"
    ],
    "total": 0
  },
  "meta": "string"
}

List an agent’s MCP servers (internal)

GET /api/v1/agents/mcp-servers/internal/list

Internal service-to-service endpoint (X-Internal-Token auth) the agent runtime calls to build an agent’s bring-your-own MCP tool set. Returns the enabled MCP servers registered for the given agent, each with its URL, transport type, and a resolved auth token (a static bearer passed through, or an OAuth2 grant exchanged/refreshed into a live access token) so the runtime can connect without handling stored ciphertext.

string

required

Agent whose enabled MCP servers should be returned.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/mcp-servers/internal/list" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "server_url": "string",
      "server_type": "string",
      "auth_credentials": "string",
      "metadata": {}
    }
  ],
  "meta": "string"
}

List customer memory entries

GET /api/v1/agents/memory

Browse every memory entry the platform has accumulated across all of your tenant’s agents and contacts — the data behind the top-level Customer Memory dashboard. Filter by contact, agent, memory type, or a created-at date window, and page through results with the opaque cursor. Entries are returned newest-first with PII in content masked unless an operator passes ?reveal=true.

string

Only return entries about this contact.

string

Only return entries learned by this agent.

string (enum: summary|fact|preference|goal)

Only return entries of this memory type.

string

Earliest createdAt (inclusive), ISO-8601.

string

Latest createdAt (inclusive), ISO-8601.

string

Opaque pagination cursor returned as next_cursor on the previous page.

integer

Max entries per page (1..200, default 50).

cURL

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

Node.js

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

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

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

{
  "data": {
    "items": [
      "string"
    ],
    "next_cursor": "string",
    "total_scanned": 0,
    "filter": {}
  },
  "meta": "string"
}

Get a customer memory entry

GET /api/v1/agents/memory/{id}

Fetch a single stored customer-memory entry by its id, across any agent or contact in your tenant. Returns the fact body (PII-masked unless you pass ?reveal=true as an owner/admin/developer), its memory type, importance weight, and scoping. Use it to inspect a row surfaced in the Customer Memory dashboard.

string

required

Memory entry id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/memory/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "item": "string"
  },
  "meta": "string"
}

List curated voice-agent model presets

GET /api/v1/agents/model-presets

Retrieve the 4 curated Model Presets (Balanced / High Intelligence / Ultra Fast / Cost Saver) — one-click STT+LLM+TTS bundles annotated with estimated latency, cost-per-minute, and quality metrics so an operator can pick a dependable voice-agent configuration without hand-tuning provider dropdowns. Static catalog content; open to any authenticated user, including an org still provisioning its tenant schema.

cURL

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

Node.js

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

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

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

{
  "data": {
    "presets": [
      {
        "id": "string",
        "title": "string",
        "summary": "string",
        "description": "string",
        "model": "string",
        "fast_model": false,
        "stt_vendor": "string",
        "tts_provider": "string",
        "temperature": 0,
        "max_tokens": 0,
        "metrics": {
          "latency_ms_p50": 0,
          "cost_per_minute_usd": 0,
          "quality_score": 0
        },
        "recommended_for": [
          "string"
        ]
      }
    ],
    "total": 0
  }
}

Retrieve a single model preset detail

GET /api/v1/agents/model-presets/{id}

Fetch the complete configuration of one curated Model Preset (id one of balanced, high_intelligence, ultra_fast, cost_saver), including its model/transcriber/voice bundle and latency/cost/quality metrics. Returns 404 when the id is not a known preset.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/model-presets/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "title": "string",
    "summary": "string",
    "description": "string",
    "model": "string",
    "fast_model": false,
    "stt_vendor": "string",
    "tts_provider": "string",
    "temperature": 0,
    "max_tokens": 0,
    "metrics": {
      "latency_ms_p50": 0,
      "cost_per_minute_usd": 0,
      "quality_score": 0
    },
    "recommended_for": [
      "string"
    ]
  }
}

List available agent models

GET /api/v1/agents/models

List the LLM models an agent can be configured to run on, each with a display label, provider, and capability tags (reasoning, vision, tools, context window). The create/edit-agent model picker reads this list, and the server validates a saved agent’s model against it.

cURL

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

Node.js

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

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

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

{
  "data": [
    {
      "value": "claude-sonnet-4-6",
      "label": "Claude Sonnet 4.6 — Balanced",
      "provider": "Anthropic",
      "capabilities": [
        "Reasoning",
        "Tools",
        "200k"
      ]
    }
  ],
  "meta": {
    "request_id": "req_01hy7m9k2p",
    "timestamp": "2026-07-27T12:00:00.000Z"
  }
}

List org-scoped outcome rubrics

GET /api/v1/agents/outcomes/rubrics

List outcome-scoring rubrics scoped to the inbox, voice, or org (agent-scoped rubrics are excluded). Filter with scope (inbox, voice, org, or all) and paginate with limit and a cursor. Returns the rubrics plus a next_cursor for the following page.

string (enum: inbox|voice|org|all)

Scope filter; all returns inbox + voice + org rubrics.

integer

—

string

Opaque cursor from a previous page’s next_cursor.

cURL

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

Node.js

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

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

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

{
  "data": {
    "rubrics": [
      "string"
    ],
    "next_cursor": "string"
  },
  "meta": "string"
}

Resolve the agent for a phone number

GET /api/v1/agents/resolve-by-number

Resolve which AI agent handles inbound voice calls to a given phone number in your tenant. Pass the number as the phone_number query param; the voice gateway calls this on each inbound to select the agent to run. Returns 404 when no agent is mapped to the number.

string

required

Destination phone number in E.164 format (e.g. +14155551234).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/resolve-by-number" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": "string",
  "meta": "string"
}

List agent squads

GET /api/v1/agents/squads/

List every agent squad configured in your tenant, newest first, each with its classifier agent, member agents and their intent labels, fallback agent, active flag, and optional daily cost cap. Backs the squads overview in the dashboard.

cURL

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

Node.js

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

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

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

{
  "data": [
    "string"
  ],
  "meta": "string"
}

Retrieve a squad by ID

GET /api/v1/agents/squads/{id}

Fetch the configuration of a specific squad, including its classifier agent, member agents, fallback routing, and cost controls. Use this to review squad setup or fetch current state before updating.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/squads/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "classifier_agent_id": "string",
    "members": [
      {
        "agent_id": "string",
        "intent_labels": [
          "string"
        ],
        "description": "string"
      }
    ],
    "fallback_agent_id": "string",
    "active": false,
    "max_cost_per_day_cents": 0,
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  }
}

List all available agent templates

GET /api/v1/agents/templates

Retrieve the catalog of pre-built agent templates (voice templates and curated templates for chatbot/router/workflow types). Each template includes system prompt, tools, test call script (for voice), and recommended use cases. Use this to show operators the template picker when creating new agents.

cURL

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

Node.js

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

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

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

{
  "data": {
    "templates": [
      {
        "id": "string",
        "title": "string",
        "summary": "string",
        "description": "string",
        "agent_type": "string",
        "category": "string",
        "model": "string"
      }
    ],
    "total": 0
  }
}

Retrieve a single template detail

GET /api/v1/agents/templates/{id}

Fetch the complete configuration of a specific agent template, including system prompt, all tools, test call script (for voice), sampling parameters, and recommended use cases. Use this when an operator wants to review or instantiate a template.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/templates/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "title": "string",
    "summary": "string",
    "description": "string",
    "agent_type": "string",
    "category": "string",
    "model": "string",
    "system_prompt": "string",
    "temperature": 0,
    "max_tokens": 0,
    "tools": [
      {}
    ],
    "test_call_script": [
      "string"
    ]
  }
}

List tool approval requests

GET /api/v1/agents/tool-approvals/

Retrieve pending (or approved/rejected) tool approval requests from agents. Includes cost estimates, tool arguments, and request metadata. Use the status query parameter to filter by approval state and review operator governance queue.

cURL

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

Node.js

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

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

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

{
  "data": {
    "approvals": [
      {
        "id": "string",
        "agent_id": "string",
        "tool_id": "string",
        "tool_args": {},
        "cost_estimate": 0,
        "status": "pending",
        "requested_at": "1970-01-01T00:00:00.000Z"
      }
    ],
    "status": "string",
    "count": 0
  }
}

List available tools for agents

GET /api/v1/agents/tools

Retrieve the registry of tools available to agents, including built-in tools, custom tools, and MCP-registered tools. Supports optional field filtering (id,name,description) for lightweight projections used by UI pickers.

cURL

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

Node.js

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

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

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

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "category": "string",
      "parameters": {}
    }
  ]
}

Retrieve a golden set with test cases

GET /api/v1/agents/voice-eval/golden-sets/{id}

Fetch a specific golden set including all its test cases, descriptions, and metadata. Use this to review evaluation criteria or prepare evaluation runs against the set.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/voice-eval/golden-sets/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "case_count": 0,
    "cases": [
      {
        "audio_url": "string",
        "expected_outcome": "string"
      }
    ],
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  }
}

List voice evaluation runs

GET /api/v1/agents/voice-eval/runs

Retrieve a paginated list of voice evaluation runs with filtering by agent, golden set, status, and date range. Use cursor-based pagination to retrieve large result sets efficiently. Results are ordered newest-first.

string

Filter by agent ID

string

Filter by golden set ID

string

Filter by run status (e.g., pending, completed, failed)

string

Filter runs created on or after this ISO 8601 timestamp

string

Filter runs created on or before this ISO 8601 timestamp

string

Opaque cursor for pagination (from next_cursor in previous response)

integer

Number of runs to return per page

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/voice-eval/runs" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "items": [
      {
        "id": "string",
        "agent_id": "string",
        "golden_set_id": "string",
        "trigger_source": "string",
        "status": "string",
        "cases_total": 0,
        "cases_passed": 0,
        "cases_failed": 0,
        "p95_latency_ms": 0,
        "cost_usd": "string",
        "created_at": "1970-01-01T00:00:00.000Z",
        "completed_at": "1970-01-01T00:00:00.000Z",
        "is_simulated": false
      }
    ],
    "next_cursor": "string"
  }
}

Retrieve voice evaluation run details

GET /api/v1/agents/voice-eval/runs/{id}

Fetch full details of a completed or in-progress voice evaluation run, including run metadata and per-case results with transcripts, LLM responses, judge scores, and latency breakdowns. Use this to review evaluation results, analyze failure reasons, and inspect audio recordings.

string

required

The voice evaluation run ID

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/voice-eval/runs/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

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

{
  "data": {
    "run": {
      "id": "string",
      "agent_id": "string",
      "golden_set_id": "string",
      "triggered_by": "string",
      "trigger_source": "string",
      "status": "string",
      "cases_total": 0,
      "cases_passed": 0,
      "cases_failed": 0,
      "stt_provider": "string",
      "tts_provider": "string",
      "llm_model": "string",
      "avg_latency_ms": 0,
      "p95_latency_ms": 0,
      "p99_latency_ms": 0,
      "total_audio_seconds": 0,
      "cost_usd": "string",
      "started_at": "1970-01-01T00:00:00.000Z",
      "completed_at": "1970-01-01T00:00:00.000Z",
      "is_simulated": false,
      "simulated_legs": [
        "string"
      ],
      "simulation_notice": "string"
    },
    "cases": [
      {
        "id": "string",
        "golden_case_id": "string",
        "case_label": "string",
        "expected_response_topic": "string",
        "actual_transcript": "string",
        "actual_response": "string",
        "llm_judge_score": "string",
        "llm_judge_reasoning": "string",
        "stt_latency_ms": 0,
        "llm_latency_ms": 0,
        "tts_latency_ms": 0,
        "end_to_end_latency_ms": 0,
        "stt_word_error_rate": "string",
        "passed": false,
        "failure_reason": "string",
        "audio_recording_url": "string",
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  }
}

Compare run against baseline for regressions

GET /api/v1/agents/voice-eval/runs/{id}/regression-delta

Retrieve regression analysis comparing the specified run against the baseline run. Returns metrics on latency and judge-score regression percentages to detect performance degradation. Use this to identify when a run fails quality gates or shows meaningful performance changes.

string

required

The voice evaluation run ID to compare against baseline

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/agents/voice-eval/runs/{id}/regression-delta" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/voice-eval/runs/{id}/regression-delta', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "has_regression": false,
    "baseline_run_id": "string",
    "p95_regression_pct": 0,
    "judge_score_regression_pct": 0
  }
}

Create an agent

POST /api/v1/agents/

Create a new AI agent in the current tenant. Only name is required; type, model, system_prompt, generation settings (temperature, max_tokens), and tools are optional and fall back to tenant defaults. Use this to provision a chatbot, voice, router, or workflow agent before wiring it to a channel or phone number. The agent is created in draft status unless status is supplied.

string

required

—

string

—

string (enum: custom|chatbot|router|voice|workflow)

—

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

—

string

—

string

—

number

—

integer

—

cURL

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": "Billing Support Bot"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Billing Support Bot"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "name": "string",
    "status": "string",
    "type": "string",
    "model": "string",
    "created_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Create an eval dataset

POST /api/v1/agents/{agentId}/evals/datasets

Create a golden-set eval dataset for an agent with inline test rows. Each row is an { input, expected_output } case the LLM judge scores an eval run against. A dataset must have between 1 and 1000 rows. Use this to codify the prompts and reference answers you want to regression-test the agent against before creating a run.

string

required

—

string

required

—

string

—

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/datasets" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Billing FAQ golden set",
  "rows": []
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/datasets', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Billing FAQ golden set",
  "rows": []
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "name": "string",
    "row_count": 0
  },
  "meta": "string"
}

Start an eval run

POST /api/v1/agents/{agentId}/evals/runs

Launch an LLM-judge eval run that scores the agent against a dataset’s golden rows using the chosen rubric. Pass the dataset_id, a rubric_name (correctness, helpfulness, safety, groundedness, or custom), and optionally a rubric_prompt (required for custom), a Claude judge_model, and a pass threshold (0–100). The run is enqueued and returns immediately with status pending; poll the run by id for scored results.

string

required

—

string

required

—

string (enum: correctness|helpfulness|safety|groundedness|custom)

required

—

string

Required when rubric_name is custom.

string

Claude model id for the judge. Defaults to the agent’s judge model.

integer

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "dataset_id": "evalDs_2Nk9pQ",
  "rubric_name": "correctness"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/evals/runs', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "dataset_id": "evalDs_2Nk9pQ",
  "rubric_name": "correctness"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "dataset_id": "string",
    "rubric_name": "string",
    "judge_model": "string",
    "threshold": 0,
    "status": "string"
  },
  "meta": "string"
}

Create a fine-tuning job

POST /api/v1/agents/{agentId}/fine-tuning/jobs

Register a managed fine-tuning job for an agent, anchored to a completed eval run whose exported JSONL is the training dataset. Supply the provider (openai, anthropic, or hf), the base_model being tuned, and the eval_run_id; Orbit tracks the job’s lifecycle but never runs the tuning itself — you fine-tune on your own provider account. Optionally record an upstream provider_job_id. The eval run must exist for this agent.

string

required

—

string (enum: openai|anthropic|hf)

required

—

string

required

—

string

required

—

string (enum: openai|anthropic|hf)

—

string

Optional external job id if you already submitted upstream.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/jobs" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "openai",
  "base_model": "gpt-4o-mini-2024-07-18",
  "eval_run_id": "evalRun_7Xy2Qa"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/jobs', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "provider": "openai",
  "base_model": "gpt-4o-mini-2024-07-18",
  "eval_run_id": "evalRun_7Xy2Qa"
}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "job": {
      "id": "string",
      "provider": "string",
      "base_model": "string",
      "eval_run_id": "string",
      "format": "string",
      "status": "string",
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  },
  "meta": "string"
}

Deploy a fine-tuned model to an agent

POST /api/v1/agents/{agentId}/fine-tuning/models/{modelId}/deploy

Point the agent at a registered custom (fine-tuned) model so the runtime resolves that model for inference instead of the base model. Call this once a managed fine-tuning job has succeeded and its resulting model is registered — the model becomes the agent’s active_custom_model_id. Use the paired DELETE on this path to revert the agent to its base model.

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/models/{modelId}/deploy" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/models/{modelId}/deploy', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "active_custom_model_id": "string",
    "custom_model": {}
  },
  "meta": "string"
}

Re-chunk a knowledge-base document

POST /api/v1/agents/{agentId}/knowledge-base/{docId}/rechunk

Re-run ingest for a knowledge-base document with an optional new chunk_size / chunk_overlap, rebuilding its chunks and embeddings and bumping the document version so any in-flight test query can detect that its results are now stale. Runs synchronously and returns once the chunks have been rewritten. chunk_overlap must be smaller than chunk_size. Requires an operator role (owner, admin, or developer).

string

required

—

string

required

—

integer

New target chunk size in tokens. Defaults to the tenant setting when omitted.

integer

New chunk overlap in tokens; must be smaller than chunk_size.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/rechunk" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/rechunk', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "document_id": "string",
    "rechunk": {}
  },
  "meta": "string"
}

Test a knowledge-base document query

POST /api/v1/agents/{agentId}/knowledge-base/{docId}/test-query

Run a real similarity search scoped to a single knowledge-base document and return the top-matching chunks plus the synthesized answer the agent would generate — a sandbox for verifying retrieval quality before shipping. Bumps each matched chunk’s retrieval count so operators can watch retrieval frequency stabilise. Requires an operator role (owner, admin, or developer) because it calls the LLM provider and is billable.

string

required

—

string

required

—

string

required

The natural-language query to run against the document.

integer

Top-K chunks to return.

number

Minimum similarity score for a chunk to be included.

boolean

Whether to also synthesize an answer from the retrieved chunks.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "query": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "document_id": "string",
    "doc_version_at_query": 0,
    "query": "string",
    "chunks": [
      {}
    ],
    "synthesized_answer": "string",
    "kb_collection_missing": false,
    "query_embedding_dim": 0,
    "rag_pii_redaction_applied": false
  },
  "meta": "string"
}

Register an MCP server for an agent

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

Register a Model Context Protocol (MCP) server so the agent can discover and call the tools it exposes. Supply a name, an https:// server_url, and server_type: http_sse, optionally with a static bearer credential or an OAuth2 grant (mutually exclusive) and a tool_allowlist that scopes which tools are exposed. The URL is SSRF-validated and any credentials are encrypted at rest. Requires an operator role (owner, admin, or developer).

string

required

—

string

required

Human-readable label, unique per agent.

string

required

HTTPS URL of the MCP server (SSE transport).

string (enum: http_sse)

required

Transport type; only http_sse is supported.

string

Optional static bearer token / API key, stored encrypted. Mutually exclusive with oauth2.

string[]

Optional allowlist of tool names to expose. Absent = expose all; [] = expose none.

object

Optional free-form metadata.

boolean

Whether the server is active. Defaults to true.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/mcp-servers" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "server_url": "string",
  "server_type": "http_sse"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/mcp-servers', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "server_url": "string",
  "server_type": "http_sse"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "organization_id": "string",
    "agent_id": "string",
    "name": "string",
    "server_url": "string",
    "server_type": "string",
    "metadata": {},
    "enabled": false,
    "has_auth_credentials": false,
    "auth_type": "oauth2",
    "tool_allowlist": [
      "string"
    ]
  },
  "meta": "string"
}

Teach an agent a fact about a contact

POST /api/v1/agents/{agentId}/memory

Manually store a fact an agent should remember about a contact, so its retrieval layer treats it exactly like an auto-extracted memory. Supply contact_id and the free-text fact; control characters are stripped and a per-tenant facts-per-contact cap is enforced (a 409 is returned when the contact is already at the cap or has opted out). Requires an operator role (owner, admin, or developer).

string

required

—

string

required

Contact the fact is about.

string

required

The free-text fact body to remember.

string (enum: manual|conversation)

Where the fact originated; drives the dashboard badge.

number

Optional importance weight (0..1). Defaults to 0.9 for manual teaches.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/memory" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b",
  "fact": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/memory', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b",
  "fact": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "item": {}
  },
  "meta": "string"
}

Create an agent outcome rubric

POST /api/v1/agents/{agentId}/outcomes/rubrics

Create an outcome-scoring rubric on an agent: markdown success criteria_md that an LLM judge applies to grade conversations, an optional custom evaluator_prompt, and an optional scope. A maximum of 20 rubrics per agent is enforced. Requires the agents:write scope and an operator role (owner, admin, or developer).

string

required

—

string

required

Display name for the rubric.

string

required

Markdown success criteria the LLM judge grades against.

string

Optional custom judge system prompt. Omit (or pass “default”) to use the built-in prompt.

string (enum: agent|inbox|voice|org)

Which conversations the rubric applies to. Defaults to agent.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "criteria_md": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "criteria_md": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "scope": "string",
    "name": "string",
    "criteria_md": "string",
    "evaluator_prompt": "string",
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Save a studio graph draft

POST /api/v1/agents/{agentId}/studio/graphs

Save a new Agent Studio workflow graph as a draft for the agent. Supply a name and a graph_json object of nodes and edges describing the visual flow (start, LLM, tool, condition, response, and voice nodes). Use it to persist canvas edits before staging and publishing. The graph JSON payload is capped at 1 MB.

string

required

—

string

required

—

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "graph_json": {}
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "graph_json": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "status": "string"
  },
  "meta": "string"
}

Publish a studio graph

POST /api/v1/agents/{agentId}/studio/graphs/{graphId}/publish

Publish a staged Agent Studio graph so its workflow becomes the active interpreter for the agent, unpublishing any previously published graph. The graph must be in staging and pass structure validation (a single start node, at least one terminal node, no dangling edges or cycles); optional per-agent eval gates can additionally block a publish that regresses quality. This request takes no body.

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/publish" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/publish', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "status": "string",
    "version": 0
  },
  "meta": "string"
}

Stage a studio graph

POST /api/v1/agents/{agentId}/studio/graphs/{graphId}/stage

Promote a draft Agent Studio graph to the staging lifecycle state so it can be validated and test-run before going live. Only a graph currently in draft can be staged; staging a graph in any other state returns 409. This request takes no body.

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/stage" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/stage', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "status": "string"
  },
  "meta": "string"
}

Test-run a studio graph

POST /api/v1/agents/{agentId}/studio/graphs/{graphId}/test-run

Dry-run an Agent Studio graph against a single input message without persisting a run or affecting live traffic, returning the workflow’s response plus token and API-call usage. Use it to validate a graph from the studio canvas before staging. Tool nodes are not executed here — publish the graph and call the agent’s run endpoint to exercise tools.

string

required

—

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/test-run" \
  -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/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/studio/graphs/{graphId}/test-run', {
  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())

{
  "data": {
    "response": "string",
    "tokens_used": 0,
    "api_calls_used": 0,
    "escalated": false
  },
  "meta": "string"
}

Invoke an agent over the A2A JSON-RPC endpoint

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

Canonical A2A JSON-RPC 2.0 entry point used by federation peers. Accepts a signed JSON-RPC envelope and dispatches the requested method (agent/discover, tasks/send, tasks/get, tasks/cancel) to the matching handler. Every request must carry a valid HMAC x-a2a-signature header; unsigned or unverifiable calls are rejected. Responds with a JSON-RPC 2.0 result envelope on success.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/a2a', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "taskId": "agentA2aTask_7c1f",
    "status": "submitted"
  }
}

Add an A2A peer to an agent

POST /api/v1/agents/{id}/a2a/peers

Register a remote A2A endpoint as a peer of this agent. The supplied peer_url is validated against SSRF rules, then its /.well-known/agent-card.json (with the legacy agent.json fallback) is fetched and cached so the dashboard can render it without re-fetching. Restricted to owner and admin roles because it mutates federation trust topology.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/peers', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "peer": {
      "id": "agentA2aPeer_3b8d",
      "agent_id": "agent_9f2c",
      "peer_url": "https://peer.example.com/agents/billing/a2a",
      "peer_name": "Billing Assistant",
      "created_at": "2026-07-27T12:34:56.000Z"
    }
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

Create an inbound A2A task

POST /api/v1/agents/{id}/a2a/tasks

REST shorthand for the A2A tasks/send method, letting a federation peer that does not speak JSON-RPC delegate a skill to this agent. The request must be HMAC-signed; the task envelope is persisted in submitted state and surfaced in the dashboard’s task history. Returns the created task.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/tasks', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "task": {
      "id": "agentA2aTask_7c1f",
      "agent_id": "agent_9f2c",
      "direction": "inbound",
      "skill_id": "chat",
      "status": "submitted",
      "input_json": {
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "What is my current balance?"
          }
        ]
      },
      "created_at": "2026-07-27T12:34:56.000Z",
      "updated_at": "2026-07-27T12:34:56.000Z"
    }
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

Delegate a task to a remote A2A peer

POST /api/v1/agents/{id}/a2a/tasks/outbound

Operator-initiated outbound A2A delegation: send a skill request to a known remote peer agent over the signed A2A client, persist the envelope as an outbound task, and return the local task plus the peer’s response. Restricted to owner, admin, and developer roles because it spends LLM tokens and invokes a remote peer’s compute. The peer_url is re-validated against SSRF rules on every call.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/tasks/outbound', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "task": {
      "id": "agentA2aTask_7c1f",
      "agent_id": "agent_9f2c",
      "direction": "outbound",
      "skill_id": "chat",
      "status": "completed",
      "peer_url": "https://peer.example.com/agents/billing/a2a",
      "created_at": "2026-07-27T12:34:56.000Z",
      "updated_at": "2026-07-27T12:35:10.000Z"
    },
    "peer_task": {
      "id": "task_remote_44",
      "status": "completed"
    }
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

Resolve a sticky A/B variant assignment

POST /api/v1/agents/{id}/ab-assignments

Assign a contact to a variant of the agent’s active A/B experiment and return the variant plus the prompt version to apply. The assignment is sticky per contact — the first call rolls the variant using the adaptive traffic split and records an impression, and later calls return the same variant without re-rolling. Pass dry_run: true to preview the would-be variant without persisting. Requires the owner, admin, or developer role.

string

required

Identifier of the agent running the experiment.

string

required

Identifier of the contact to assign a variant to.

string

Optional conversation this assignment belongs to.

boolean

When true, return the would-be variant without persisting.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/ab-assignments', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "contact_id": "contact_4d2f6a8c1e3b5d7f9a1c3e5b"
}),
})
console.log(await res.json())

{
  "data": {
    "has_experiment": false,
    "experiment_id": "string",
    "assignment_id": "string",
    "variant": "a",
    "version_id": "string",
    "conversion_metric": "string",
    "effective_split_pct": 0
  },
  "meta": "string"
}

Record an A/B assignment conversion event

POST /api/v1/agents/{id}/ab-assignments/{assignmentId}/conversion

Record a conversion signal — a reply, goal completion, avoided handoff, or escalation — against an existing A/B assignment so it counts toward the experiment’s per-variant results. The conversion flip is one-way and idempotent: once flipped it stays converted, and an escalation locks the assignment as not-converted. Requires the owner, admin, or developer role.

string

required

Identifier of the agent running the experiment.

string

required

Identifier of the A/B assignment to record the event against.

string (enum: reply_received|goal_completion|human_handoff_avoided|escalated)

required

The conversion signal to record.

string

Optional context for the audit trail.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/ab-assignments/{assignmentId}/conversion" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "event_type": "reply_received"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/ab-assignments/{assignmentId}/conversion', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "event_type": "reply_received"
}),
})
console.log(await res.json())

{
  "data": {
    "assignment_id": "string",
    "experiment_id": "string",
    "variant": "a",
    "metric": "string",
    "event": "string"
  },
  "meta": "string"
}

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/node'

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())

{
  "data": {
    "response": "string",
    "conversation_id": "string",
    "tokens_used": 0
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "status": 0,
    "details": {}
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z",
    "docs_url": "https://example.com"
  }
}

Stream a chat response from an agent (SSE)

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

Server-Sent Events stream of agent response tokens. The response Content-Type is text/event-stream; each event line carries either a partial token (data: {token}) or a terminal payload (data: {final, conversation_id}). The connection persists until the agent completes or the rate-limit window is exhausted (20/min per tenant).

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/node'

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())

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Persist an agent conversation turn

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

Service-to-service callback used by the agent runtime to persist a completed chat conversation and its latest turn — messages, tokens used, and optional per-turn debug data — to the tenant’s conversation history. When the turn tripped an escalation trigger, pass escalated: true with a reason to fire the configured human-handoff action. Authenticated with an internal service token, not a public API key.

string

required

Identifier of the agent that handled the conversation.

string

required

Stable identifier for the conversation being persisted.

object[]

required

Ordered message log for the conversation.

integer

—

string

Channel the conversation ran on (defaults to “api”).

boolean

Set true when the turn tripped an escalation trigger.

string

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/conversations" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "string",
  "messages": []
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/conversations', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "conversation_id": "string",
  "messages": []
}),
})
console.log(await res.json())

{
  "data": {
    "persisted": false,
    "conversation_id": "string"
  },
  "meta": "string"
}

Deploy an agent to a channel

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

Deploy an agent so it starts handling live traffic on a channel — webhook, SMS, WhatsApp, voice, or RCS. Provide a webhook URL for the webhook channel or a phone number for the messaging and voice channels. Returns the updated agent record and writes an audit entry. Requires a role permitted to deploy agents.

string

required

Identifier of the agent to deploy.

string (enum: webhook|sms|whatsapp|voice|rcs)

required

Channel to deploy the agent on.

string

Destination URL for the webhook channel.

string

Phone number to bind for messaging or voice channels.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/deploy', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "channel": "webhook"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "status": "string",
    "channel": "string"
  },
  "meta": "string"
}

Dry-run an agent against a scripted scenario

POST /api/v1/agents/{id}/dry-run

Replay a scripted multi-turn scenario against the agent in sandbox mode and return the turn-by-turn trace plus assertion results. Live tool side effects (calendar, transfer, mutative memory) are short-circuited and billing is skipped, so the LLM call is real but nothing is committed. Use it to test prompt changes and tool behaviour before deploying. Requires owner, admin, or developer.

string

required

Agent identifier (Devotel agent_xxx id).

object

required

—

boolean

Mock mutative tools during the run. Defaults to true.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/dry-run', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "scenario": {}
}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "mock_tools": false,
    "status": "pass",
    "duration_ms": 0,
    "trace": [
      {
        "index": 0,
        "user_msg": "string",
        "assistant_response": "string",
        "tool_calls": [
          {}
        ],
        "latency_ms": 0,
        "tokens_used": 0,
        "error": null
      }
    ],
    "assertions": [
      {
        "name": "string",
        "status": "pass",
        "reason": null
      }
    ]
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Duplicate an agent

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

Create a copy of an existing agent, cloning its full configuration (prompt, model, tools, and knowledge bases) exactly. The copy starts in draft status; pass an optional name to override the default of the source name suffixed with (copy). Requires the owner, admin, or developer role.

string

required

Identifier of the source agent to duplicate.

string

Optional name for the new agent. Defaults to the source agent name suffixed with (copy).

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/duplicate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "name": "string",
    "status": "string",
    "model": null,
    "created_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Start an agent A/B experiment

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

Start a new A/B experiment that routes a configurable share of inbound conversations to variant B (a second prompt version) while the rest see variant A, measuring a single conversion metric. Only one experiment may be active per agent — starting another returns 409. Requires owner, admin, or developer.

string

required

Agent identifier (Devotel agent_xxx id).

string

required

Human-readable experiment name.

string

required

Prompt version id for the control arm (A).

string

required

Prompt version id for the treatment arm (B). Must differ from A.

integer

Percentage of new contacts routed to variant B (1–99, default 50).

string (enum: reply_received|goal_completion|human_handoff_avoided)

required

The single outcome the experiment optimises for.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/experiments" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "variant_a_version_id": "string",
  "variant_b_version_id": "string",
  "conversion_metric": "reply_received"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/experiments', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "variant_a_version_id": "string",
  "variant_b_version_id": "string",
  "conversion_metric": "reply_received"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "name": "string",
    "variant_a_version_id": "string",
    "variant_b_version_id": "string",
    "traffic_split_pct": 0,
    "conversion_metric": "reply_received",
    "started_at": "1970-01-01T00:00:00.000Z",
    "ended_at": null,
    "winner": "a",
    "created_by_user_id": null,
    "created_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

End an agent A/B experiment

POST /api/v1/agents/{id}/experiments/{expId}/end

Stop an active experiment and stamp its ended_at. An optional winner value (a, b, or tie) and note are recorded for reference only — ending an experiment never changes the agent’s live prompt. To make a variant live, call promote-winner separately. Requires owner, admin, or developer.

string

required

Agent identifier (Devotel agent_xxx id).

string

required

Experiment id.

string (enum: a|b|tie)

Descriptive winner stamp. Does not promote anything.

string

Optional note recorded on the audit trail.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/experiments/{expId}/end', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "name": "string",
    "variant_a_version_id": "string",
    "variant_b_version_id": "string",
    "traffic_split_pct": 0,
    "conversion_metric": "reply_received",
    "started_at": "1970-01-01T00:00:00.000Z",
    "ended_at": null,
    "winner": "a",
    "created_by_user_id": null,
    "created_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Promote an A/B experiment winner

POST /api/v1/agents/{id}/experiments/{expId}/promote-winner

Promote the chosen winning variant’s prompt version onto the live agent and mint a fresh history row so the change is auditable. This is the explicit, operator-gated action that makes an experiment result live; it also stamps the experiment ended if it was still running. Requires owner, admin, or developer.

string

required

Agent identifier (Devotel agent_xxx id).

string

required

Experiment id.

string (enum: a|b)

required

Which variant to promote onto the live agent.

string

Optional note recorded on the audit trail.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/experiments/{expId}/promote-winner" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "winner": "a"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/experiments/{expId}/promote-winner', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "winner": "a"
}),
})
console.log(await res.json())

{
  "data": {
    "experiment_id": "string",
    "winner": "a",
    "winner_version_id": "string",
    "new_version": {
      "id": "string",
      "version_number": 0
    }
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Search an agent’s knowledge bases

POST /api/v1/agents/{id}/kb-search

Run a semantic/keyword search across one or more knowledge bases linked to this agent and return the top-scoring chunks, merged and ranked by relevance. Only knowledge bases already attached to the agent may be queried; an unlinked kb_id returns 403. Use it to preview what an agent would retrieve for a given user question.

string

required

Agent identifier (Devotel agent_xxx id).

string

required

Natural-language search query.

string[]

required

Knowledge base ids to search. Each must be linked to this agent.

integer

Maximum number of merged results to return (1–20, default 5).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/kb-search" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string",
  "kb_ids": []
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/kb-search', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "query": "string",
  "kb_ids": []
}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "query": "string",
    "results": [
      {
        "content": "string",
        "score": 0,
        "document_name": null
      }
    ]
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Roll an agent back to a prompt version

POST /api/v1/agents/{id}/prompt-rollback/{vid}

Restore the agent’s live configuration to the snapshot captured at version . Forward-only: it mints a new history row whose parent is the source version, so the timeline stays monotonic and auditable. A pinned eval suite is run first and the rollback is refused with 422 if it regresses. Friendly alias of POST /agents//versions//promote; requires owner or admin.

string

required

Agent identifier (Devotel agent_xxx id).

string

required

Prompt version id to roll back to.

string

Optional note recorded on the audit trail for this rollback.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/prompt-rollback/{vid}', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "rolled_back_from_version_id": "string",
    "rolled_back_from_version_number": 0,
    "new_version": {
      "id": "string",
      "version_number": 0
    },
    "promotion_gate": null
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Save a regression test for an agent

POST /api/v1/agents/{id}/regression-tests

Save a conversation as a regression test for an agent. Provide a name, the conversation turns, and declarative expected_outputs (contains, contains_any, excludes, or verbatim). The test is replayed whenever the prompt, model, or tools change to prove the agent still passes. Requires owner, admin, or developer role.

string

required

Identifier of the agent the test belongs to.

string

required

Human-readable name for the saved test.

string

Optional note describing what the test covers.

object[]

required

The saved conversation turns to replay.

object

Declarative assertions the replayed reply must satisfy.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/regression-tests" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "conversation_json": []
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/regression-tests', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "conversation_json": []
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "agent_id": "string",
    "name": "string"
  },
  "meta": "string"
}

Run all of an agent’s regression tests

POST /api/v1/agents/{id}/regression-tests/run-all

Replay every saved regression test for the agent in sandbox mode (billing and memory extraction are bypassed) and return a pass, fail, or error result per test plus a run summary. Capped at 25 tests per run. Requires owner, admin, or developer role.

string

required

Identifier of the agent whose tests to replay.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/regression-tests/run-all', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "summary": {
      "total": 0,
      "passed": 0,
      "failed": 0,
      "errored": 0
    },
    "results": [
      {
        "id": "string",
        "name": "string",
        "status": "pass",
        "actual": "string",
        "reasons": [
          "string"
        ]
      }
    ]
  },
  "meta": "string"
}

Configure or clear an agent’s shadow target

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

Configure or clear the production agent that this agent shadows. Set shadow_of_agent_id to place the agent in shadow mode, so the runtime side-channels each production run and records a comparison log; set it to null to stop shadowing. Self-shadowing and shadow cycles are rejected. Requires owner, admin, or developer role.

string

required

Identifier of the agent to place in (or remove from) shadow mode.

string

required

Production agent to shadow, or null to clear shadow mode.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/shadow', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "shadow_of_agent_id": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "shadow_of_agent_id": "string"
  },
  "meta": "string"
}

Promote a shadow agent to production

POST /api/v1/agents/{id}/shadow/promote

Promote a shadow agent’s configuration to its production counterpart. Copies the shadow’s system prompt, model, tools, and settings onto the production agent, records a new version-history entry, then clears the shadow link so the shadow row stays available for further iteration. Requires owner or admin role.

string

required

Identifier of the shadow agent being promoted.

boolean

Set true to proceed when the shadow diverged from production by more than 25 percent.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/shadow/promote', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "promoted_from": "string",
    "production_agent_id": "string",
    "promoted_version_id": "string"
  },
  "meta": "string"
}

Stream an agent reply word by word (SSE)

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

Send a chat message and receive the agent reply as a Server-Sent Events stream. The endpoint runs the blocking chat path, then emits the answer word by word as text/event-stream: token events carry incremental text, a terminal done event carries totalTokens, costCents, and conversationId, and an error event carries a code and message. Use this for a typing-indicator experience when the SDK expects a streaming method. Rate limited to 20 requests per minute per tenant.

string

required

Identifier of the agent to converse with.

string

required

User message to send to the agent.

string

Existing conversation id to append onto; omit to start a new conversation.

object[]

Optional prior turns to seed the agent, additive on top of any persisted state.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/{id}/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/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/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())

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Take an agent offline

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

Undeploy a live agent so it stops handling new traffic. Deployment bindings are cleared and the agent returns to a non-live state; its configuration, versions, and conversation history are preserved so it can be redeployed later. Returns the updated agent record. Requires owner, admin, or developer role.

string

required

Identifier of the agent to take offline.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/undeploy', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "name": "string",
    "status": "string"
  },
  "meta": "string"
}

Save a new agent prompt version

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

Capture the agent’s current configuration — system prompt, model, temperature, tools, knowledge bases, safety config, and cost cap — as a new immutable version row, newest version number wins. This does not change the live agent; it checkpoints the current state so you can diff, branch, or roll back to it later. Optionally attach a note, a human-readable label, or a branch name to start an experiment line. Requires an owner, admin, or developer role.

string

required

Identifier of the agent to checkpoint.

string

Optional note describing what changed in this checkpoint.

string

Optional branch label to start or continue an experiment line.

string

Optional human-readable bookmark for this version (e.g. “before Black Friday tweak”).

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/versions', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Branch an agent prompt version

POST /api/v1/agents/{id}/versions/{vid}/branch

Fork a saved version into a sibling experiment line. Mints a new history row that snapshots the source version’s configuration, carries your branch label, and points its parent at the source. The live agent is not touched — a branch is a pre-promote draft you iterate on and later promote to go live. Requires an owner, admin, or developer role.

string

required

Identifier of the agent to branch a version for.

string

required

Identifier of the source version to fork from.

string

required

Label for the new experiment branch.

string

Optional note describing the branch.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/versions/{vid}/branch', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "branch": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Promote an agent prompt version

POST /api/v1/agents/{id}/versions/{vid}/promote

Make a saved version the agent’s live configuration — the rollback action. Copies the version’s prompt, model, settings, and cost cap back onto the agent, bumps the agent’s version counter, and mints a fresh forward-only history row so the audit timeline stays monotonic. When a pinned eval suite or red-team safety gate is configured, the candidate is scored first and the promote is refused with 422 on a regression. If separation-of-duties approval is enabled, the author cannot promote their own version (403). Requires an owner, admin, or developer role.

string

required

Identifier of the agent to promote a version for.

string

required

Identifier of the version to make live.

boolean

Records whether the operator confirmed the promotion in the UI diff dialog.

string

Optional note describing why the version was promoted.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/versions/{vid}/promote', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "promoted_from_version_id": "string",
    "promoted_from_version_number": 0,
    "new_version": "string",
    "promotion_gate": {},
    "red_team_gate": {}
  },
  "meta": "string"
}

Issue an agent authorization mandate

POST /api/v1/agents/agent-authorization-mandate

Issue a fresh scoped, action-capped, revocable authorization mandate that lets an AI agent perform non-payment actions on a principal’s behalf (read a profile, book or reschedule, send on-behalf, invoke a specific tool, access a data category). The mandate is minted in active status carrying a SHA-256 consentDigest over its immutable scope; the response is a serializable snapshot the caller stores and round-trips in each subsequent request. This is the general-purpose sibling of the payment-scoped commerce mandate. Requires the agents:write scope and an owner, admin, or developer role. This surface only decides whether an action is within a mandate — the action itself still exits through the caller’s own rails.

string

required

Opaque, caller-supplied mandate id.

string

required

The agent authorized to act (an Orbit agent id or an external A2A/MCP identity).

string

required

The principal granting consent.

array | null

Action allowlist. Omit or send empty for “any action”.

array | null

Tool allowlist. Omit or send empty for “any tool”.

array | null

Data-category allowlist. Omit or send empty for “any category”.

integer

required

Cumulative action ceiling (a positive integer).

integer | null

Epoch-ms expiry (must be in the future), or null for no expiry.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxInvocations": 0
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxInvocations": 0
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

"string"

Authorize and commit an action against a mandate

POST /api/v1/agents/agent-authorization-mandate/act

Authorize AND commit an action, returning the advanced mandate (its invocationCount incremented, flipped to exhausted once the cap is reached) plus the authorization decision. An action outside the mandate is rejected with VALIDATION_ERROR (surfaced as 422 with the deny reason), so a caller can never act past consent. Requires the agents:write scope and an owner, admin, or developer role. The committed action is audit-logged.

any

required

—

any

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/act" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": "string",
  "action": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/act', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": "string",
  "action": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "mandate": "string",
    "authorization": "string"
  },
  "meta": "string"
}

"string"

Authorize and commit a delegated action

POST /api/v1/agents/agent-authorization-mandate/act-chain

Authorize the full ancestry chain AND commit the leaf action, returning the advanced leaf mandate plus the authorization decision. Rejected with VALIDATION_ERROR (422) when the ancestry doesn’t hold — a revoked, expired, exhausted, or tampered hop anywhere in the lineage, or a scope that isn’t a genuine attenuation — or when the leaf action is out of scope. Requires the agents:write scope and an owner, admin, or developer role. Audit-logged with the chain depth and root/parent mandate ids.

any[]

required

The full delegation chain, ordered [root, ..., leaf].

any

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/act-chain" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "chain": [],
  "action": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/act-chain', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "chain": [],
  "action": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "mandate": "string",
    "authorization": "string"
  },
  "meta": "string"
}

"string"

Reconstruct and verify a delegation chain (audit)

POST /api/v1/agents/agent-authorization-mandate/audit-chain

Reconstruct and verify the full principal → orchestrator → sub-agent → … delegation lineage for an auditor: the end-to-end ancestry verdict plus a per-hop breakdown (each hop’s identity, parent pointer, status, integrity, scope, and invocation state). Read-only — never mutates any mandate.

any[]

required

The full delegation chain to audit, ordered [root, ..., leaf].

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/audit-chain" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "chain": []
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/audit-chain', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "chain": []
}),
})
console.log(await res.json())

{
  "data": {
    "valid": false,
    "reason": "ok",
    "failedAt": null,
    "rootPrincipalId": null,
    "hops": [
      {
        "depth": 0,
        "mandateId": "string",
        "agentId": "string",
        "principalId": "string",
        "parentMandateId": null,
        "status": "active",
        "integrityIntact": false,
        "allowedActions": [
          "string"
        ],
        "allowedTools": [
          "string"
        ],
        "allowedDataCategories": [
          "string"
        ],
        "maxInvocations": 0,
        "invocationCount": 0,
        "expiresAt": null
      }
    ]
  },
  "meta": "string"
}

"string"

Authorize an action against a mandate (dry-run)

POST /api/v1/agents/agent-authorization-mandate/authorize

Evaluate an action against a mandate and return the decision WITHOUT advancing the invocation count — the runtime authorization gate as a dry-run. The A2A/MCP dispatch layer calls this before performing an action. Checks, in order: consent-digest integrity, revocation, expiry, exhaustion, a non-empty action verb, the action / tool / data-category allowlists, and the cumulative invocation cap. authorized is true only when every check passes. Read-only — never mutates the mandate.

any

required

—

any

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/authorize" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": "string",
  "action": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/authorize', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": "string",
  "action": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "authorization": "string"
  },
  "meta": "string"
}

"string"

Authorize a delegated action against its full chain (dry-run)

POST /api/v1/agents/agent-authorization-mandate/authorize-chain

The runtime authorization gate for a DELEGATED action as a dry-run. Walks the full [root, ..., leaf] ancestry back to the principal’s root mandate — re-verifying every hop’s integrity, terminal status, expiry, ancestry link, and attenuation — then evaluates the leaf’s own scope. A revoked, expired, or exhausted mandate ANYWHERE in the lineage denies the action. No state change. chain is ordered root-first, leaf-last (the leaf is the mandate the acting agent presents).

any[]

required

The full delegation chain, ordered [root, ..., leaf].

any

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/authorize-chain" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "chain": [],
  "action": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/authorize-chain', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "chain": [],
  "action": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "authorization": "string"
  },
  "meta": "string"
}

"string"

Delegate an attenuated sub-agent mandate

POST /api/v1/agents/agent-authorization-mandate/delegate

Mint an attenuated CHILD mandate from a live parent for an agent-as-tool / A2A re-delegation hop (orchestrator → sub-agent, or transitively sub-agent → sub-sub-agent). The child’s allowlists, invocation cap, and expiry are each narrowed to a subset of the parent’s — a delegated mandate can never end up with more authority than it was given — and it carries a parentMandateId + parentDigest pointer baked into its own consent digest so the ancestry link cannot be forged or repointed. Delegation is refused from a parent that is revoked, expired, exhausted, or fails its own integrity check. Requires the agents:write scope and an owner, admin, or developer role. Audit-logged.

any

required

—

string

required

Opaque, caller-supplied id for the new child mandate.

string

required

The sub-agent receiving the delegated authority.

array | null

Action allowlist to further narrow to. Omit or send empty to inherit the parent’s unchanged.

array | null

Tool allowlist to further narrow to. Omit or send empty to inherit the parent’s unchanged.

array | null

Data-category allowlist to further narrow to. Omit or send empty to inherit the parent’s unchanged.

integer | null

Invocation cap to further narrow to. Omit to inherit the parent’s cap; the effective cap is the minimum of this and the parent’s, never higher.

integer | null

Expiry to further narrow to. Omit to inherit the parent’s expiry; the effective expiry is the earlier of this and the parent’s, never later.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/delegate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "parent": "string",
  "id": "string",
  "agentId": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/delegate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "parent": "string",
  "id": "string",
  "agentId": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

"string"

Revoke an agent authorization mandate

POST /api/v1/agents/agent-authorization-mandate/revoke

Withdraw consent, moving the mandate to the terminal revoked status so no further action is authorized under it (and, via the chain endpoints, none under any mandate delegated from it). Returns the revoked mandate snapshot. Re-revoking an already-revoked mandate is a VALIDATION_ERROR. Requires the agents:write scope and an owner, admin, or developer role. Audit-logged.

any

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/revoke', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

"string"

POST /api/v1/agents/agent-authorization-mandate/verify

Recompute the SHA-256 consent digest over the mandate’s current immutable scope and report whether it still matches the stored consentDigest. intact: false means a scoped field (an allowlist, the cap, the principal/agent, the expiry, or the ancestry pointer) was altered after consent was recorded — tamper-evidence for auditors. Read-only — never mutates the mandate.

any

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/agent-authorization-mandate/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "intact": false,
    "mandateId": "string",
    "consentDigest": "string"
  },
  "meta": "string"
}

"string"

Record a human override on an AI turn

POST /api/v1/agents/ai-turn-audit/{auditId}/override

Record that a human contested the AI’s decision on a specific audit row (GDPR Art-22 § 3, the right to a human review). Stamps the row with the operator’s user id and a free-text reason. Append-once — a second override on the same row returns 409, and an unknown row returns 404. Requires an owner or admin role.

string

required

Identifier (UUID) of the AI-turn audit row to override.

string

required

Why the human contested the AI decision.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/ai-turn-audit/{auditId}/override" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/ai-turn-audit/{auditId}/override', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "reason": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "audit_id": "string",
    "overridden": false
  },
  "meta": "string"
}

Record an agent calendar event

POST /api/v1/agents/calendar-events

Store a calendar event captured by an AI agent’s create_calendar_event tool during a conversation and fire the agent.calendar_event.created webhook so your Google Calendar or Outlook integration can pick it up. Use it to let an agent book meetings or appointments on the customer’s behalf and sync them to your own calendar of record.

string

required

Stable identifier for the event (used for idempotency and webhook correlation).

string

required

Event title.

string

Optional event description.

string

required

Event start time (ISO-8601).

string

Optional event end time (ISO-8601).

string

Optional attendee email address.

string

Conversation the event was booked from.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/calendar-events" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "string",
  "title": "string",
  "start_time": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/calendar-events', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "event_id": "string",
  "title": "string",
  "start_time": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "event_id": "string",
    "title": "string",
    "start_time": "string",
    "end_time": "string",
    "status": "string"
  },
  "meta": "string"
}

Escalate an agent conversation to a human

POST /api/v1/agents/conversations/{conversationId}/escalate

Hand an in-progress agent conversation to a live human operator by marking it as escalated. This is what the agent’s transfer-to-human tool and the operator “Escalate” action call: it flips the conversation status, records the reason and category, attaches the AI transcript for whoever picks it up, fires the agent.handoff.requested and agent.conversation.ended webhooks, and — when the agent is configured for email delivery — forwards the transcript to the configured address. A conversation already in a terminal state returns 409. Requires an owner, admin, or developer role.

string

required

Agent conversation identifier.

string

Free-text reason shown to the operator who receives the handoff.

Machine-readable handoff category for analytics. Inferred from the reason when omitted.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/escalate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "conversation_id": "string",
    "status": "escalated",
    "reason": "string"
  },
  "meta": "string"
}

Check an agent conversation for a loop

POST /api/v1/agents/conversations/{conversationId}/loop-check

Evaluate whether an agent conversation is stuck in a loop — the customer re-asking the same thing while the agent repeats itself or sentiment keeps dropping — and return a deterministic assessment over the recent message window. This is a read-only check: it inspects the conversation but never mutates it or triggers a handoff. It powers the inbox “this conversation may be looping” banner so an operator can step in. The optional body tunes the detection thresholds. Requires an owner or admin role.

string

required

Agent conversation identifier.

integer

How many recent turns to inspect.

number

Similarity above which two customer turns count as a re-ask.

number

Sentiment below which the window is treated as negative.

integer

Minimum customer turns required before a loop can be flagged.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/loop-check" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/loop-check', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "conversation_id": "string",
    "evaluation": {
      "isLoop": false,
      "reasonCodes": [
        "string"
      ],
      "customerTurnCount": 0
    },
    "window_turns": 0,
    "evaluated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Send a supervisor note to an agent

POST /api/v1/agents/conversations/{conversationId}/supervisor-notes

Send a one-way supervisor “whisper” note to an agent during a live conversation; the agent reads it on its next turn to steer the reply without the customer seeing it. Use it to coach an agent mid-conversation — correct a fact, nudge the tone, or add context. The note must be 1–1000 characters and the conversation must still be active. Requires an owner, admin, or supervisor role.

string

required

Agent conversation identifier.

string

required

The guidance the agent should apply on its next turn.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/supervisor-notes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/conversations/{conversationId}/supervisor-notes', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "note": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "conversation_id": "string"
  },
  "meta": "string"
}

Dispatch a CRM agent tool action

POST /api/v1/agents/crm-tools/internal/dispatch

Execute a CRM action (e.g. hubspot_create_contact, calendly_find_slots) on behalf of a running AI agent, resolving the tenant’s integration connection server-side so provider credentials never cross the runtime boundary. The action must be one of the registered CRM tools for the given provider. Every failure — missing connection, expired auth, provider or network error — comes back as a structured result with ok: false and a safe message the agent can read and react to, never as an HTTP error. Internal service-to-service endpoint, authenticated with the runtime internal token.

string (enum: hubspot|salesforce|zendesk|calendly|intercom)

required

CRM provider the action belongs to.

string

required

Registered CRM tool action to run for the provider (e.g. hubspot_create_contact).

object

Action arguments the model produced. Defaults to an empty object.

string

Optional agent identifier, recorded for audit logging.

string

Optional agent-run identifier, recorded for audit logging.

string

Optional conversation the tool call belongs to.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/crm-tools/internal/dispatch" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "hubspot",
  "action": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/crm-tools/internal/dispatch', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "provider": "hubspot",
  "action": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "ok": false,
    "provider": "string",
    "action": "string",
    "response": "string",
    "duration_ms": 0,
    "error": "string",
    "message": "string"
  },
  "meta": "string"
}

Create a custom agent tool

POST /api/v1/agents/custom-tools

Register a new webhook-backed custom tool for your agents. Supply a lowercase snake_case name, a description the model reads to decide when to call it, an optional JSON-Schema for the tool’s parameters, and the HTTPS executor_url Orbit POSTs to when an agent invokes the tool. An optional executor_secret is stored encrypted and used to HMAC-sign each dispatch. Names that collide with a built-in tool are rejected, and the executor URL is SSRF-checked at write time. Requires an owner, admin, or developer role.

string

required

Lowercase snake_case identifier the model calls (e.g. lookup_order).

string

required

What the tool does — the model reads this to decide when to call it.

object

JSON-Schema for the tool’s parameters (max 32KB serialized).

string

required

HTTPS endpoint Orbit POSTs to when an agent invokes the tool.

string

Optional secret, stored encrypted, used to HMAC-sign each dispatch.

boolean

—

integer

Per-call timeout in milliseconds.

string

Whether the tool call requires operator approval before it runs.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/custom-tools" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "description": "string",
  "executor_url": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/custom-tools', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "description": "string",
  "executor_url": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "json_schema": {},
    "executor_url": "string",
    "executor_secret_set": false,
    "enabled": false,
    "timeout_ms": 0,
    "confirmation": "string",
    "created_by_user_id": "string",
    "created_at": "1970-01-01T00:00:00.000Z",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Fire a sample request against a custom tool’s executor

POST /api/v1/agents/custom-tools/{id}/test

Test a custom tool from the builder UI by dispatching a real request to its executor URL with caller-supplied sample args, returning the live response, status, latency, and any configured spoken message — without ever persisting the call. Supports override_executor_url / override_executor_secret / override_timeout_ms so a not-yet-saved tool can be tried before it is created or patched.

string

required

—

object

Sample arguments matching the tool’s JSON-Schema, forwarded to the executor.

string

Test against this URL instead of the tool’s saved executor_url.

string

Test with this HMAC secret instead of the tool’s saved (encrypted) one.

integer

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/custom-tools/{id}/test', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "ok": false,
    "status": 0,
    "duration_ms": 0,
    "response_body": "string",
    "error": "string",
    "spoken_message": "string",
    "spoken_start_message": "string"
  },
  "meta": "string"
}

Dispatch a custom tool call (internal)

POST /api/v1/agents/custom-tools/internal/dispatch

Internal service-to-service endpoint (X-Internal-Token auth) invoked by the agent runtime when the model picks a tenant-owned custom tool. It looks up the tool by name, decrypts its webhook secret server-side, and fans out an HMAC-signed POST to the tool’s executor URL (with SSRF re-validation and a per-tool timeout), returning the executor response plus any rotating spoken completion/failure message. Plaintext secrets never leave the API process.

string

required

Slug of the custom tool the model selected.

object

Arguments the model produced, matching the tool’s JSON-Schema.

string

required

—

string

required

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/custom-tools/internal/dispatch" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool_name": "string",
  "agent_id": "string",
  "agent_run_id": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/custom-tools/internal/dispatch', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "tool_name": "string",
  "agent_id": "string",
  "agent_run_id": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "ok": false,
    "status": 0,
    "duration_ms": 0,
    "response_body": "string",
    "error": "string",
    "spoken_message": "string",
    "spoken_start_message": "string"
  },
  "meta": "string"
}

Mark a phone or email as Do-Not-Call/Contact

POST /api/v1/agents/dnc

Record a Do-Not-Call/Contact request captured by an AI agent’s mark_dnc tool during a conversation. Adds the phone number or email to your suppression list — and, for voice and SMS, to your Do-Not-Call list — then marks any matching contact as Do-Not-Contact so it is excluded from the next campaign audience, and fires the agent.dnc.marked webhook. Idempotent — repeating the call for an already-suppressed address returns success without creating duplicates or re-firing the webhook. Requires at least one of phone or email.

string

E.164 phone number (e.g. +14155551234). At least one of phone/email is required.

string

—

string

Which channel(s) the suppression applies to. Defaults to all.

string

—

string

—

cURL

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

Node.js

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

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

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

{
  "data": {
    "status": "string",
    "channel": "string",
    "reason": "string",
    "new_suppression_rows": 0,
    "suppressed_voice_dnc": false,
    "contacts_flipped": 0,
    "phone": "string",
    "email": "string"
  },
  "meta": "string"
}

Generate a draft agent from a plain-English prompt

POST /api/v1/agents/from-prompt/

NL-to-agent builder: send a plain-English description of the agent you want (e.g. “a support agent that looks up orders and escalates refunds”) and an LLM generates + persists a draft agent — name, system prompt, recommended channels/tools, evaluation rubrics, and example test inputs. The draft is created with status: draft and must be reviewed and promoted via POST /from-prompt/{draftId}/activate before it goes live. Rate-limited per organization.

string

required

Plain-English description of the agent to generate.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/from-prompt/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "prompt": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "draftAgentId": "string",
    "spec": {},
    "toolsDropped": [
      "string"
    ],
    "latencyMs": 0
  },
  "meta": "string"
}

Promote a generated draft agent to active

POST /api/v1/agents/from-prompt/{draftId}/activate

Promote a draft agent created by POST /from-prompt (or /from-prompt/stream) to status: active so it can start handling real conversations. Fails with 409 if the agent is not currently in draft status (e.g. already activated).

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/from-prompt/{draftId}/activate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/from-prompt/{draftId}/activate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": "string"
}

Fetch seeded sample inputs for a draft agent

POST /api/v1/agents/from-prompt/{draftId}/sandbox-test

Return the NL-builder’s seeded example test inputs (up to 10 rows) for a draft agent, so the builder UI can offer one-click sample prompts before the operator writes their own. Returns an empty list when the draft has no seeded dataset. Rate-limited to 5 requests/minute.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/from-prompt/{draftId}/sandbox-test" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/from-prompt/{draftId}/sandbox-test', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "draftAgentId": "string",
    "agentName": "string",
    "sampleInputs": [
      "string"
    ],
    "note": "string"
  },
  "meta": "string"
}

Generate a draft agent from a prompt, streamed over SSE

POST /api/v1/agents/from-prompt/stream

Server-Sent-Events variant of POST /from-prompt for the agent-builder wizard: streams incremental generation progress/tokens as the LLM drafts the agent, then a final event with the same persisted draft agent payload, so the UI can show live progress instead of a blocking spinner.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/from-prompt/stream', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "prompt": "string"
}),
})
console.log(await res.json())

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Record a cross-agent handoff (internal)

POST /api/v1/agents/internal/handoffs

Internal service-to-service endpoint (X-Internal-Token auth) the agent runtime calls the moment one specialist agent delegates a conversation to another via the transfer_to_agent tool. It persists an idempotent row in the tenant’s agent-handoff audit table and fires the agent.handoff_occurred webhook, enforcing the source agent’s handoff_targets allowlist and refusing an off-allowlist pair with 403. Use it to keep a durable, replay-safe record of A2A routing decisions.

string

required

Caller-supplied idempotency key; a replay is a no-op.

string

required

Agent delegating the conversation.

string

required

Specialist agent receiving the conversation; must be on the source’s handoff_targets allowlist.

string

—

string

—

string

Short recap of the conversation handed to the target agent.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/internal/handoffs" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "handoff_id": "string",
  "source_agent_id": "string",
  "target_agent_id": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/internal/handoffs', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "handoff_id": "string",
  "source_agent_id": "string",
  "target_agent_id": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "persisted": false,
    "handoff_id": "string"
  },
  "meta": "string"
}

Tenant-wide knowledge-base semantic search

POST /api/v1/agents/kb/query

Run a RAG semantic search over the tenant’s knowledge bases, wired by the MCP kb_query tool for agents that don’t yet have a specific agent context. Pass kb_id to restrict the search to one knowledge base (it must be linked to one of the tenant’s agents unless you are owner/admin); omitting kb_id searches across every KB the tenant owns but requires an owner or admin role. Returns the top-k chunk matches ranked by vector similarity with source citations. Use POST /agents/{id}/kb-search instead when searching within a specific agent’s linked knowledge bases.

string

required

—

integer

—

string

Restrict the search to this knowledge base. Omit for a tenant-wide search (owner/admin only).

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/kb/query', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "query": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "results": [
      {
        "documentId": "string",
        "knowledge_base_id": "string",
        "chunkIndex": 0,
        "content": "string",
        "score": 0
      }
    ],
    "query": "string",
    "knowledge_base_id": "string"
  },
  "meta": "string"
}

Activate a pending BYO LLM inference credential

POST /api/v1/agents/llm-provider-credential/activate

Marks a pending credential active. Pass enforce=true to begin routing this tenant’s agent inference through the customer credential — self-serve, with no operator provisioning step. Requires agents:write with the owner or admin role. Writes are audit-logged.

boolean

When true, immediately route this tenant’s agent inference through the credential.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/activate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/activate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

"string"

"string"

Toggle automatic fallback to Orbit’s pooled model

POST /api/v1/agents/llm-provider-credential/pooled-fallback

Opt in (or out) of automatic fallback: when enabled, if this organization’s own inference endpoint starts failing repeatedly, agent turns route through Orbit’s pooled model until the endpoint recovers instead of failing outright. Off by default — a residency / cost-governance credential never leaves your own endpoint unless you explicitly accept the trade-off. Requires agents:write with the owner or admin role. Writes are audit-logged.

boolean

required

Enable (true) or disable (false) automatic degrade-to-pooled-model on repeated endpoint failures.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/pooled-fallback" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/pooled-fallback', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "enabled": false
}),
})
console.log(await res.json())

"string"

"string"

Revoke the BYO LLM inference credential

POST /api/v1/agents/llm-provider-credential/revoke

Revokes the customer credential. Enforcement is cleared and agent inference falls back to the platform-owned key for new turns. Re-enabling BYO inference requires registering a credential afresh. Requires agents:write with the owner or admin role. Writes are audit-logged.

string

Optional operational justification for the audit trail.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/revoke" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/revoke', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

"string"

"string"

Rotate the BYO LLM inference credential

POST /api/v1/agents/llm-provider-credential/rotate

Replaces the registered credential with a new one (endpoint re-validated, secret re-fingerprinted, replaced blob re-encrypted), preserving the lifecycle state of an active credential and bumping the rotation count. Refused on a revoked credential — register a new one instead. Requires agents:write with the owner or admin role. Writes are audit-logged.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/rotate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential/rotate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

"string"

"string"

Install a marketplace template

POST /api/v1/agents/marketplace/{slug}/install

Fork an approved marketplace template into the caller’s tenant, creating a new agent that copies the template’s model, system prompt, tools, and temperature. Optionally override the installed agent’s name and description so the operator gets their own uniquely-named copy. The template’s install counter is incremented after the agent is created.

string

required

Slug of the marketplace template to install.

string

Override the installed agent’s name (defaults to the template name).

string

Override the installed agent’s description.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/marketplace/{slug}/install', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "template_slug": "string",
    "template_name": "string",
    "agent": {}
  },
  "meta": "string"
}

Approve or reject a pending template

POST /api/v1/agents/marketplace/{slug}/moderate

Platform-moderator decision endpoint for a pending marketplace template. Approving flips the template to approved (making it visible in the public list and installable); rejecting flips it to rejected and requires notes so the submitter has actionable feedback. Only pending templates can be moderated — a template already approved or rejected returns 409. Platform-admin only.

string

required

Slug of the pending template to moderate.

string

required

—

string

Reviewer notes; required when rejecting.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/marketplace/{slug}/moderate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "decision": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "slug": "string",
    "status": "string",
    "decision": "string"
  },
  "meta": "string"
}

Submit a template to the marketplace

POST /api/v1/agents/marketplace/publish

Submit a new agent template from your tenant back to the public marketplace. The submission lands in a pending state — invisible to the public list, detail, and install endpoints — until a platform moderator approves it. A slug that collides with an existing template is rejected with 409. Returns 202 to signal the template is queued for review.

string

required

Unique kebab-case identifier (lowercased on save).

string

required

—

string

required

—

string

—

string

required

—

string

—

number

—

string[]

—

string[]

—

string

—

string[]

—

string[]

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/marketplace/publish" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "string",
  "name": "string",
  "category": "string",
  "system_prompt": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/marketplace/publish', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "slug": "string",
  "name": "string",
  "category": "string",
  "system_prompt": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "template_id": "string",
    "slug": "string",
    "status": "string",
    "message": "string"
  },
  "meta": "string"
}

Add a customer memory entry

POST /api/v1/agents/memory

Manually teach the platform a memory about a contact from the Customer Memory dashboard, scoped to a specific agent. The content is embedded exactly like an auto-extracted memory so retrieval treats it identically; when the embedding provider is unavailable the entry is still persisted with a placeholder vector and re-embedded later. A per-tenant facts-per-contact cap is enforced for fact entries (a 409 is returned when the contact is at the cap). Requires an operator role (owner or admin).

string

required

Contact the memory is about.

string

required

Agent the memory is scoped to.

string (enum: summary|fact|preference|goal)

The kind of memory being stored.

string

required

The free-text memory body to store.

number

Optional importance weight (0..1). Defaults to 0.9 for manual entries.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/memory" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "string",
  "agentId": "string",
  "content": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/memory', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "contactId": "string",
  "agentId": "string",
  "content": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "item": "string"
  },
  "meta": "string"
}

Create a draft voice agent from a model preset

POST /api/v1/agents/model-presets/{id}/instantiate

One-click create a draft voice agent pre-wired with the preset’s model, transcriber, voice, and sampling params. Optionally override the agent name and description; the operator can adjust the system prompt afterward in the agent studio. Owner/admin only.

string

required

—

string

—

string

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/model-presets/{id}/instantiate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "preset_id": "string",
    "preset_title": "string",
    "agent": {
      "id": "string",
      "name": "string",
      "status": "string"
    }
  }
}

Create an org-scoped outcome rubric

POST /api/v1/agents/outcomes/rubrics

Create an outcome-scoring rubric scoped to the inbox, voice, or the whole org (not a single agent). Supply a name, markdown criteria_md, and optionally a custom evaluator_prompt and scope. Each scope allows up to 20 rubrics. Use POST /agents//outcomes/rubrics for agent-scoped rubrics.

string

required

—

string

required

Markdown success criteria shown in the rubric editor.

string

Custom judge system prompt; omit to use the built-in judge.

string (enum: inbox|voice|org)

Where the rubric applies. Agent scope must use the agent-scoped endpoint.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/outcomes/rubrics" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "criteria_md": "string"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/outcomes/rubrics', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "string",
  "criteria_md": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Enhance an agent system prompt with AI

POST /api/v1/agents/prompts/enhance

Rewrite an operator-authored draft system prompt into an improved version using the platform LLM — the create-agent wizard’s “AI Enhance” action. Send the current prompt and the target agent_type; the response returns the enhanced prompt and the model that produced it. Rate-limited per tenant.

string

required

The draft system prompt to improve.

string (enum: chatbot|router|voice|workflow|custom)

The kind of agent the prompt is for; tunes the rewrite.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/prompts/enhance', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "prompt": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "prompt": "string",
    "model": "string"
  },
  "meta": "string"
}

Create an agent squad

POST /api/v1/agents/squads/

Create a squad that routes inbound conversations across 2–6 member agents. A classifier agent maps each message to one member’s intent labels, with an optional fallback agent for unmatched intents. Supply name, classifier_agent_id, and the members array; the classifier must not also be a member.

cURL

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

Node.js

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

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

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

{
  "data": "string",
  "meta": "string"
}

Test squad classifier routing

POST /api/v1/agents/squads/{id}/test

Simulate the squad’s classifier agent against a test message and return the routing decision. Shows which squad member the classifier would route to, the matched intent label, and the matched member’s metadata. Use this to verify classifier behavior and label coverage before deploying.

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/squads/{id}/test" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "I need help with my billing account"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/squads/{id}/test', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "message": "I need help with my billing account"
}),
})
console.log(await res.json())

{
  "data": {
    "squad_id": "string",
    "message": "string",
    "classifier_model": "string",
    "agent_id": "string",
    "source": "matched",
    "raw_label": "string",
    "matched_member": {
      "agent_id": "string",
      "intent_labels": [
        "string"
      ],
      "description": "string"
    }
  }
}

Create an agent from a template

POST /api/v1/agents/templates/{id}/instantiate

Clone a template into your tenant by creating a new agent with the template’s system prompt, tools, and voice config pre-configured. Optionally override the agent name and description. The new agent is created in draft status ready for testing before deployment.

string

required

—

string

—

string

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/templates/{id}/instantiate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "template_id": "string",
    "template_title": "string",
    "agent": {
      "id": "string",
      "name": "string",
      "status": "string"
    }
  }
}

Approve a tool use request

POST /api/v1/agents/tool-approvals/{id}/approve

Approve a pending tool approval request, allowing the agent to proceed with the tool invocation. Optionally include a reason/note for audit purposes. Idempotent for re-approvals.

string

required

—

string

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/tool-approvals/{id}/approve', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "status": "string",
    "decided_at": "1970-01-01T00:00:00.000Z"
  }
}

Reject a tool use request

POST /api/v1/agents/tool-approvals/{id}/reject

Reject a pending tool approval request, preventing the agent from invoking the tool. A reason is required for rejection records. The agent is notified of the rejection and may choose a different action.

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/tool-approvals/{id}/reject" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Rejected - email recipient not in approved list"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/tool-approvals/{id}/reject', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "reason": "Rejected - email recipient not in approved list"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "status": "string",
    "decided_at": "1970-01-01T00:00:00.000Z"
  }
}

Create a voice evaluation golden set

POST /api/v1/agents/voice-eval/golden-sets

Create a golden set (reference test suite) for voice agent evaluation. Contains test cases with audio URLs and expected outcomes. Use golden sets to establish baseline evaluation criteria and track agent quality over time.

string

required

—

string

—

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/voice-eval/golden-sets" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support Q&A Golden Set",
  "cases": []
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/voice-eval/golden-sets', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Support Q&A Golden Set",
  "cases": []
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "name": "string",
    "case_count": 0
  }
}

Trigger a voice evaluation run

POST /api/v1/agents/voice-eval/runs

Start an evaluation run to assess agent performance against test cases in a golden set. Triggers asynchronous evaluation with the specified agent (or golden set default), LLM model, and STT/TTS providers. Use this to benchmark agent quality, detect regressions, and capture latency metrics.

string

required

—

string

—

string

—

string

—

string

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/voice-eval/runs" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "golden_set_id": "vevg_golden_set_001"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/voice-eval/runs', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "golden_set_id": "vevg_golden_set_001"
}),
})
console.log(await res.json())

{
  "data": {
    "run_id": "string",
    "cases_total": 0,
    "cases_passed": 0,
    "cases_failed": 0,
    "avg_latency_ms": 0,
    "p95_latency_ms": 0,
    "p99_latency_ms": 0,
    "is_simulated": false,
    "simulated_legs": [
      "string"
    ],
    "simulation_notice": "string"
  }
}

Update an agent

PUT /api/v1/agents/{id}

Update an existing AI agent’s configuration — any subset of name, description, model, temperature, max tokens, system prompt, tools, knowledge-base ids, voice config, metadata, and status. Only the fields supplied in the request body are changed; the full updated agent record is returned and the edit is audit-logged.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Set an agent’s invocation rate limits

PUT /api/v1/agents/{id}/rate-limits

Partially update an agent’s invocation rate limits. Only the axes present in the request body change; an omitted axis is left untouched, while an explicit null clears that axis (unlimited). Requires at least one axis in the body. Requires the owner or admin role; writes are audit-logged.

string

required

Identifier of the agent whose rate limits to update.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/rate-limits', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "limits": "string"
  },
  "meta": "string"
}

Register a BYO LLM inference credential

PUT /api/v1/agents/llm-provider-credential

Registers (or re-registers over a revoked config) a customer-owned Anthropic-native inference credential. The endpoint is validated, the secret is fingerprinted for audit and stored encrypted at rest (never echoed). New registrations start pending and must be activated + enforced before inference routes through them — a self-serve flow with no operator provisioning step. Requires agents:write with the owner or admin role. Writes are audit-logged.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/llm-provider-credential', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

"string"

"string"

Update a squad

PUT /api/v1/agents/squads/{id}

Modify one or more fields of an existing squad (name, description, classifier, members, fallback agent, or cost cap). The update validates the merged state to prevent routing loops before persisting.

string

required

—

string

—

string

—

string

—

object[]

—

boolean

—

integer

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/squads/{id}', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "name": "string",
    "updated_at": "1970-01-01T00:00:00.000Z"
  }
}

Advance a fine-tuning job

PATCH /api/v1/agents/{agentId}/fine-tuning/jobs/{jobId}

Move a fine-tuning job to its next lifecycle state as the external tuning run progresses (queued → running → succeeded/failed/cancelled). Record the upstream provider_job_id, the resulting fine_tuned_model (required to reach succeeded), or an error reason. On success the resulting model is auto-registered into the agent’s custom-model registry — pass model_display_name to label it. Terminal states cannot transition.

string

required

—

string

required

—

string (enum: queued|running|succeeded|failed|cancelled)

required

—

string

—

string

Required when transitioning to succeeded.

string

Failure reason when transitioning to failed.

string

Display name for the custom model auto-registered on success.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/jobs/{jobId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "succeeded"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/jobs/{jobId}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "status": "succeeded"
}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "job": {
      "id": "string",
      "status": "string",
      "fine_tuned_model": null,
      "custom_model_id": null
    },
    "registered_model": null
  },
  "meta": "string"
}

Update an outcome rubric

PATCH /api/v1/agents/{agentId}/outcomes/rubrics/{rubricId}

Update an agent-scoped outcome rubric by id. Send any subset of name, criteria_md (the markdown success criteria), evaluator_prompt (a custom LLM-judge prompt), or scope; omitted fields keep their current value. Use it to refine how conversations are graded pass or fail. Returns 404 when the rubric does not exist for that agent.

string

required

—

string

required

—

string

—

string

—

string

—

string (enum: agent|inbox|voice|org)

—

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics/{rubricId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics/{rubricId}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Update a custom tool

PATCH /api/v1/agents/custom-tools/{id}

Partially update a tenant-owned custom tool — any subset of description, JSON-Schema parameters, executor URL, executor secret (rotate or clear with null), enabled flag, timeout, confirmation mode, or spoken messages. The executor URL is re-validated against SSRF/DNS-rebinding rules when changed, and every update takes effect on the next tool call.

string

required

—

string

—

object

JSON-Schema describing the tool’s parameters, shown to the LLM.

string

HTTPS webhook the runtime POSTs to when the tool is invoked.

string

New secret rotates the HMAC key; null clears it; omit to leave unchanged.

boolean

—

integer

—

string

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/custom-tools/{id}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": "string"
}

Adjust a memory entry’s importance

PATCH /api/v1/agents/memory/{id}

Update the importance weight of an existing customer-memory entry in place — the dashboard “Boost” action that promotes a fact so it is retained longer and retrieved sooner. Only importance (0..1) is mutable; content, type, and scoping are fixed once stored.

string

required

Memory entry id.

number

required

New retention weight in the range 0..1.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/agents/memory/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "importance": 0
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/memory/{id}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "importance": 0
}),
})
console.log(await res.json())

{
  "data": {
    "item": "string"
  },
  "meta": "string"
}

Update an outcome rubric

PATCH /api/v1/agents/outcomes/rubrics/{rubricId}

Update an existing outcome-scoring rubric by id (org, inbox, or voice scoped). Send any of name, criteria_md, evaluator_prompt, or scope; omitted fields are left unchanged. Reassigning to agent scope must use the agent-scoped endpoint. Returns the rubric id and its new updated_at.

string

required

Rubric id.

string

—

string

—

string

—

string (enum: inbox|voice|org)

—

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/agents/outcomes/rubrics/{rubricId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/outcomes/rubrics/{rubricId}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "updated_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Undeploy a fine-tuned model

DELETE /api/v1/agents/{agentId}/fine-tuning/models/{modelId}/deploy

Revert the agent to its base model by clearing the active custom model, so the runtime stops resolving the fine-tuned model for inference. This is the paired revert for the deploy POST on this path. Only succeeds when modelId is the agent’s currently active model — a stale undeploy of a model that isn’t deployed returns 409 so it cannot silently drop a newer deploy.

string

required

—

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/models/{modelId}/deploy" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/fine-tuning/models/{modelId}/deploy', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "agent_id": "string",
    "active_custom_model_id": null
  },
  "meta": "string"
}

Remove an agent’s MCP server

DELETE /api/v1/agents/{agentId}/mcp-servers/{id}

Delete a Model Context Protocol (MCP) server registration from an agent. The call is idempotent — deleting an id that no longer exists returns 200 with deleted: 0 rather than a 404, so retries and double-clicks are safe. Requires an operator role (owner, admin, or developer).

string

required

—

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/{agentId}/mcp-servers/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/mcp-servers/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "deleted": 0,
    "id": "string",
    "agent_id": "string"
  },
  "meta": "string"
}

Forget an agent memory fact

DELETE /api/v1/agents/{agentId}/memory/{itemId}

Delete a single memory fact from an agent by its item id, scoped to the caller’s tenant so a guessed id from another tenant cannot be removed. Use it to honour a “forget this” request or prune an incorrect fact the agent learned. Requires an operator role (owner, admin, or developer).

string

required

—

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/{agentId}/memory/{itemId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/memory/{itemId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Delete an outcome rubric

DELETE /api/v1/agents/{agentId}/outcomes/rubrics/{rubricId}

Delete an agent-scoped outcome rubric by id so it no longer grades new conversations for the agent. Outcome rows already recorded against the rubric are retained for reporting. Use it to retire a grading criterion. Deleting a rubric that does not exist still succeeds.

string

required

—

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics/{rubricId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/outcomes/rubrics/{rubricId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Delete an agent

DELETE /api/v1/agents/{id}

Delete an AI agent by id within the caller’s tenant. The agent stops serving new conversations immediately, while existing conversation history is retained for reporting. Use it to permanently remove an agent you no longer need. Returns 404 when no agent with that id exists in the tenant.

string

required

—

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Remove an A2A peer from an agent

DELETE /api/v1/agents/{id}/a2a/peers/{peerId}

Remove a registered remote A2A peer from this agent, breaking the federation link so outbound delegation can no longer target it. Restricted to owner and admin roles and audit-logged. Returns 404 when no peer with that id exists.

string

required

—

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/peers/{peerId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/a2a/peers/{peerId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "deleted": true,
    "peer_id": "agentA2aPeer_3b8d"
  },
  "meta": {
    "request_id": "req_8a1f2e",
    "timestamp": "2026-07-27T12:34:56.000Z"
  }
}

Delete a saved regression test

DELETE /api/v1/agents/{id}/regression-tests/{testId}

Remove a single saved regression test from an agent by its test id. The test is deleted only when it belongs to the given agent. Requires owner, admin, or developer role.

string

required

Identifier of the agent the test belongs to.

string

required

Identifier of the regression test to delete.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/{id}/regression-tests/{testId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/regression-tests/{testId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "deleted": false
  },
  "meta": "string"
}

Delete a custom tool

DELETE /api/v1/agents/custom-tools/{id}

Permanently remove a tenant-owned custom tool by id and, in the same transaction, strip its id from every agent’s custom_tool_ids allowlist so no agent keeps a dangling reference. Publishes a tenant-wide cache invalidation so the runtime drops the tool on its next executor build. Returns 404 when no tool with that id exists for the tenant.

string

required

Identifier of the custom tool to delete.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/custom-tools/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "deleted": false
  },
  "meta": "string"
}

Erase all memory for a contact

DELETE /api/v1/agents/memory

GDPR right-to-erasure: permanently delete every memory entry stored about a contact across all agents, and flip the contact’s memory_enabled flag to false so agents stop writing new memories about them. The opt-out flag is set before the vector delete to close the race where a concurrent agent turn could re-add an entry. Requires an operator role (owner or admin).

string

required

The contact whose memory should be erased. Required so a stray call cannot wipe the whole tenant.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/memory', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Delete a customer memory entry

DELETE /api/v1/agents/memory/{id}

Delete a single stored customer-memory entry by its id. The lookup is scoped to the caller’s tenant so a guessed id from another tenant cannot be removed, and it honours GDPR right-to-erasure even for tenants with more than 1000 memory entries. Requires an operator role (owner or admin).

string

required

Memory entry id.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/memory/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Delete an outcome rubric

DELETE /api/v1/agents/outcomes/rubrics/{rubricId}

Permanently delete an outcome-scoring rubric by id (org, inbox, or voice scoped). Once removed, the rubric no longer grades new conversations. Returns 204 No Content on success. This action is audit-logged.

string

required

Rubric id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/agents/outcomes/rubrics/{rubricId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/outcomes/rubrics/{rubricId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Delete an agent squad

DELETE /api/v1/agents/squads/{id}

Permanently delete an agent squad by id. Removing a squad stops classifier-based routing for its classifier agent; the member agents themselves are not deleted. Returns the deleted squad id. This action is audit-logged.

string

required

Squad id.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/agents/squads/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "deleted": false
  },
  "meta": "string"
}

​Agents API

​title: “Worked request and response samples” description: “Worked samples for the most-asked agent operations: create an agent with a model and knowledge-base binding, send a user turn, and the error to expect when a knowledge-base id is detached.”

​Worked request and response samples

​Create an agent

​Converse with the agent

​Error envelope

​List agents

​List eval datasets

​Get an eval dataset

​List eval runs

​Get an eval run

​Compare two eval runs

​List fine-tuning jobs

​List knowledge-base document chunks

​List an agent’s MCP servers

​List an agent’s memory facts for a contact

​List an agent’s outcome rubrics

​Get outcome pass-rate stats

​Get agent quality scorecard

​Get a studio graph

​Get a studio graph run

​Get an agent

​Get an agent’s public A2A Agent Card

​Get an agent’s public A2A Agent Card (legacy path)

​Get an agent’s A2A card and shareable endpoint

​List an agent’s A2A peers

​List an agent’s A2A tasks

​Get an A2A task by id

​Get A/B experiment lift attribution

​Fetch the agent’s active A/B experiment

​Get aggregated analytics for an agent

​Get First Contact Resolution analytics

​List an agent’s conversations

​List messages in an agent conversation

​Export an agent’s conversations as CSV

​Resolve an agent’s conversation cost cap

​List agent A/B experiments

​Get A/B experiment detail

​List an agent’s handoff events

​List recent agent handoffs

​List an agent’s prompt version history

​Get an agent’s invocation rate limits and live usage

​List an agent’s saved regression tests

​Compare a shadow agent against production

​Look up the squad an agent classifies

​List an agent’s recent tool calls

​List an agent’s prompt versions

​Diff two agent prompt versions

​Get an agent’s voice runtime config

​Export the AI-turn audit log

​List all agent conversations

​Get an agent conversation

​Get a conversation’s AI-turn audit log

​Get an agent conversation’s debug log

​List handoffs within an agent conversation

​Get outcome scores for a conversation

​List supervisor notes for a conversation

​List live agent conversations

​List a tenant’s connected CRM providers

​List custom agent tools

​Get a custom tool

​List enabled custom tools (internal)

​List knowledge-base coverage gaps

​Get the org’s BYO LLM inference credential config

​Browse the agent template marketplace

​Get a marketplace template

​List templates pending moderation

​List an agent’s MCP servers (internal)

​List customer memory entries

​Get a customer memory entry

​List curated voice-agent model presets

​Retrieve a single model preset detail

​List available agent models

​List org-scoped outcome rubrics

​Resolve the agent for a phone number

​List agent squads

​Retrieve a squad by ID

​List all available agent templates

​Retrieve a single template detail

​List tool approval requests

Agents API

title: “Worked request and response samples” description: “Worked samples for the most-asked agent operations: create an agent with a model and knowledge-base binding, send a user turn, and the error to expect when a knowledge-base id is detached.”

Worked request and response samples

Create an agent

Converse with the agent

Error envelope

List agents

List eval datasets

Get an eval dataset

List eval runs

Get an eval run

Compare two eval runs

List fine-tuning jobs

List knowledge-base document chunks

List an agent’s MCP servers

List an agent’s memory facts for a contact

List an agent’s outcome rubrics

Get outcome pass-rate stats

Get agent quality scorecard

Get a studio graph

Get a studio graph run

Get an agent

Get an agent’s public A2A Agent Card

Get an agent’s public A2A Agent Card (legacy path)

Get an agent’s A2A card and shareable endpoint

List an agent’s A2A peers

List an agent’s A2A tasks

Get an A2A task by id

Get A/B experiment lift attribution

Fetch the agent’s active A/B experiment

Get aggregated analytics for an agent

Get First Contact Resolution analytics

List an agent’s conversations

List messages in an agent conversation

Export an agent’s conversations as CSV

Resolve an agent’s conversation cost cap

List agent A/B experiments

Get A/B experiment detail

List an agent’s handoff events

List recent agent handoffs

List an agent’s prompt version history

Get an agent’s invocation rate limits and live usage

List an agent’s saved regression tests

Compare a shadow agent against production

Look up the squad an agent classifies

List an agent’s recent tool calls

List an agent’s prompt versions

Diff two agent prompt versions

Get an agent’s voice runtime config

Export the AI-turn audit log

List all agent conversations

Get an agent conversation

Get a conversation’s AI-turn audit log

Get an agent conversation’s debug log

List handoffs within an agent conversation

Get outcome scores for a conversation

List supervisor notes for a conversation

List live agent conversations

List a tenant’s connected CRM providers

List custom agent tools

Get a custom tool

List enabled custom tools (internal)

List knowledge-base coverage gaps

Get the org’s BYO LLM inference credential config

Browse the agent template marketplace

Get a marketplace template

List templates pending moderation

List an agent’s MCP servers (internal)

List customer memory entries

Get a customer memory entry

List curated voice-agent model presets

Retrieve a single model preset detail

List available agent models

List org-scoped outcome rubrics

Resolve the agent for a phone number

List agent squads

Retrieve a squad by ID

List all available agent templates

Retrieve a single template detail

List tool approval requests