Orby Assistant API

Orby is Orbit’s in-dashboard operator assistant. These endpoints power the Orby chat panel: you send a message, Orby streams back a response over Server-Sent Events (SSE), and — when a turn proposes an action that changes data (such as sending an SMS or reassigning a conversation) — it pauses for an explicit approval before running it. Orby is operator-facing. Every endpoint runs in the context of the signed-in dashboard user, scoped to that user’s organization and tenant. There is no server-to-server API-key path for Orby. Base path: /api/v1/orby

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

import { Orbit } from "@devotel-orbit/node";

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

const { data } = await orbit.request<unknown>(
  "GET",
  "/orby/turns"
);

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/orby/turns")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK for install. Go, Ruby, and PHP ship the same untyped request method — call it the same way you would any untyped endpoint:

import (
    "context"
    "log"

    "github.com/devotel/orbit-go/orbit"
)

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
if err != nil {
    log.Fatal(err)
}

var envelope struct {
    Data any    `json:"data"`
    Meta any    `json:"meta"`
}
err = client.Request(context.Background(), "GET", "/orby/turns", nil, nil, &envelope, "")
if err != nil {
    log.Fatal(err)
}

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY
res = client.request("GET", "/orby/turns")

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  // reads ORBIT_API_KEY
$res = $client->request("GET", "/orby/turns");

Samples below stay dependency-free so they run even before you vendor an SDK. Full SDK index at SDK quickstart.

Authentication

Orby uses the dashboard user (Bearer token) method, not an API key. Send the signed-in operator’s JWT:

curl https://api.orbit.devotel.io/api/v1/orby/threads \
  -H "Authorization: Bearer eyJhbG..."

const response = await fetch("https://api.orbit.devotel.io/api/v1/orby/threads", {
  headers: { Authorization: "Bearer eyJhbG..." },
});
const { data, meta } = await response.json();

import requests

response = requests.get(
    "https://api.orbit.devotel.io/api/v1/orby/threads",
    headers={"Authorization": "Bearer eyJhbG..."},
)
data = response.json()

req, err := http.NewRequest(
    "GET",
    "https://api.orbit.devotel.io/api/v1/orby/threads",
    nil,
)
if err != nil {
    log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer eyJhbG...")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

require "net/http"
require "json"

uri = URI("https://api.orbit.devotel.io/api/v1/orby/threads")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer eyJhbG..."
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

<?php
$curl = curl_init("https://api.orbit.devotel.io/api/v1/orby/threads");
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer eyJhbG..."],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($curl);
curl_close($curl);

A request authenticated with an API key — whether sent as X-API-Key or as a dv_* Bearer token — is rejected with 403 ORBY_SESSION_REQUIRED. There is no server-to-server path. When any ORBY_* code comes back, use Troubleshooting: Orby operator errors for the cause table and fix path per code. Every Orby endpoint requires one of these operator roles: owner, admin, developer, viewer, or billing. Two knowledge-base maintenance endpoints (POST /kb/reindex and GET /kb/status) additionally require super-admin and return 403 INSUFFICIENT_PERMISSIONS otherwise. A thread belongs to the operator who created it. You can only list, read, and post turns to your own threads — requesting another operator’s thread returns 404.

Rate limits

Surface	Limit
`POST /assistant` (turns)	60 turns per minute per operator
`POST /tool-actions/:id/approve` and `/reject`	60 requests per minute per tenant
`GET /tool-actions/:id` (poll)	120 requests per minute per tenant

When you exceed the turn limit, POST /assistant returns 429 ORBY_RATE_LIMITED with a Retry-After header (seconds).

Run a turn

POST /api/v1/orby/assistant Start a new Orby conversation or continue an existing thread. The response is an SSE stream (Content-Type: text/event-stream), one event per token and per lifecycle step, terminated by a done event.

string

required

The operator’s message. 1–8000 characters.

string

Continue an existing thread. Omit to start a new one — the response stream reports the new thread_id in the final response event, and the thread is auto-titled from your first message.

object

Optional context describing the dashboard page the operator is on, so Orby can ground its answer. All fields are optional.

Show child attributes

string

Route or page identifier (max 200 chars).

string

Identifier of the record in view, e.g. a conversation id (max 200 chars).

string

Human-readable label for that record (max 200 chars).

object

Free-form key/value context.

Pass an optional Idempotency-Key header to make a retried turn safe against double-execution of any tool it runs.

cURL

curl -N -X POST https://api.orbit.devotel.io/api/v1/orby/assistant \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How many conversations are unassigned right now?",
    "page": { "page": "/inbox", "contextLabel": "Inbox" }
  }'

TypeScript

const response = await fetch(
  "https://api.orbit.devotel.io/api/v1/orby/assistant",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer eyJhbG...",
      "Content-Type": "application/json",
      Accept: "text/event-stream",
    },
    body: JSON.stringify({
      message: "How many conversations are unassigned right now?",
      page: { page: "/inbox", contextLabel: "Inbox" },
    }),
  },
);
// the response body is an SSE stream — consume it event-by-event

Python

import requests

response = requests.post(
    "https://api.orbit.devotel.io/api/v1/orby/assistant",
    headers={
        "Authorization": "Bearer eyJhbG...",
        "Accept": "text/event-stream",
    },
    json={
        "message": "How many conversations are unassigned right now?",
        "page": {"page": "/inbox", "contextLabel": "Inbox"},
    },
    stream=True,
)
# the response is an SSE stream — iterate it event-by-event

Stream events

Each SSE frame has an event: name and a JSON data: payload. Read them in order until you receive done (success) or error (failure); the connection then closes.

Event	`data` payload	Meaning
`router`	`{ intent, confidence }`	Orby classified the message intent.
`status`	`{ status, detail? }`	Progress marker (e.g. `thinking`, `approving`).
`token`	`{ content }`	One fragment of the streamed answer. Concatenate in order.
`tool_start`	`{ toolCallId, tool, input, cost_estimate_cents, requires_confirmation }`	Orby is running a tool.
`tool_pending`	`{ toolCallId, tool, input, cost_estimate_cents, pending_action_id }`	The tool needs explicit approval before it runs. Hold here and redeem `pending_action_id` (see Tool confirmations).
`tool_end`	`{ toolCallId, tool, input, output, status, cost_cents }`	A tool finished.
`refusal`	`{ message }`	Orby declined the request.
`clarify`	`{ question }`	Orby needs more information to proceed.
`response`	`{ response, turn_id, thread_id, tokens_used, cost_cents_billable }`	The completed turn. Persist `thread_id` to continue the conversation.
`error`	`{ code, message, details? }`	The turn failed.
`done`	`{ ok: true }`	The stream is finished.

event: token
data: {"content": "You currently have "}

event: token
data: {"content": "7 unassigned conversations."}

event: response
data: {"response": "You currently have 7 unassigned conversations.", "turn_id": "orbyTurn_abc", "thread_id": "othr_123", "tokens_used": 142, "cost_cents_billable": 1}

event: done
data: {"ok": true}

When Orby pauses on a tool_pending event, you can resume the same turn either by redeeming the pending action through the tool-actions endpoints, or by sending a follow-up turn on the same thread whose message is a plain confirm / yes / cancel. The chat reply and the explicit approve/reject button resolve through the same path, so the audit trail is identical.

Consume the stream (worked example)

A turn consumer does three jobs: open the connection, dispatch each named event, and handle tool_pending by holding the pending_action_id for approval or rejection. Register a listener per named event — the events listed above arrive as event: router, event: token, and so on, so a generic onmessage / message handler never sees them. State you track while the stream runs:

text — concatenate every token payload’s content in order. The response event then reports the full assembled answer, so you never have to re-assemble it client-side.
Pending actions — on tool_pending, store the pending_action_id with the tool name, input, and cost estimate, then render an approve/reject control (see Redeem a pending action below). A tool_end payload that arrives after approval reports the tool’s result.
Thread handle — hold the operator JWT in a variable; every request on this page carries it as Authorization: Bearer.

Node (eventsource)
Python (sseclient)

// npm install eventsource
import { EventSource } from "eventsource";

interface OrbyToolPending {
  toolCallId: string;
  tool: string;
  input: unknown;
  cost_estimate_cents: number;
  pending_action_id: string;
}

function runTurn(jwt: string, message: string, threadId?: string) {
  const source = new EventSource(
    "https://api.orbit.devotel.io/api/v1/orby/assistant",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${jwt}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message,
        ...(threadId ? { thread_id: threadId } : {}),
      }),
    },
  );

  let text = "";
  let thread_id = threadId;
  const pending: OrbyToolPending[] = [];

  source.addEventListener("token", (event) => {
    text += JSON.parse(event.data).content;
  });

  source.addEventListener("tool_pending", (event) => {
    const action = JSON.parse(event.data) as OrbyToolPending;
    pending.push(action);
    // render an approve/reject control for action.pending_action_id
  });

  source.addEventListener("response", (event) => {
    const data = JSON.parse(event.data);
    text = data.response; // full assembled answer
    thread_id = data.thread_id; // persist to continue the thread
  });

  source.addEventListener("error", (event) => {
    source.close();
    const data = JSON.parse(event.data);
    reportOrbyTurnError(data.code, data.message);
  });

  source.addEventListener("done", () => {
    source.close();
    renderTurn({ text, thread_id, pending });
  });
}

# pip install sseclient requests
import json
import requests
import sseclient

def run_turn(jwt, message, thread_id=None):
    response = requests.post(
        "https://api.orbit.devotel.io/api/v1/orby/assistant",
        headers={
            "Authorization": f"Bearer {jwt}",
            "Content-Type": "application/json",
            "Accept": "text/event-stream",
        },
        json={"message": message, **({"thread_id": thread_id} if thread_id else {})},
        stream=True,
    )
    client = sseclient.SSEClient(response)

    state = {"text": "", "thread_id": thread_id, "pending": []}

    @client.on_event("token")
    def on_token(event):
        state["text"] += json.loads(event.data)["content"]

    @client.on_event("tool_pending")
    def on_tool_pending(event):
        state["pending"].append(json.loads(event.data))
        # render an approve/reject control for the held pending_action_id

    @client.on_event("response")
    def on_response(event):
        data = json.loads(event.data)
        state["text"] = data["response"]  # full assembled answer
        state["thread_id"] = data["thread_id"]  # persist to continue

    @client.on_event("error")
    def on_error(event):
        data = json.loads(event.data)
        raise OrbyTurnError(data["code"], data["message"])

    for _event in client.events():
        pass  # callbacks fire per named event; loop until `done`

    return state

Both samples dispatch on the named events the Stream events table lists. Ignore any event name you do not handle — adding event types is backwards-compatible.

Redeem a pending action

On tool_pending, hold the pending_action_id and redeem it through the tool-actions endpoints. The approve call can race a second click or arrive after the 5-minute expiry window, so retry 409 responses whose error_code is PENDING_ACTION_RACE or PENDING_ACTION_EXPIRED after refreshing the action state.

PENDING_ID=pact_abc123
curl -X POST "https://api.orbit.devotel.io/api/v1/orby/tool-actions/${PENDING_ID}/approve" \
  -H "Authorization: Bearer eyJhbG..."
# on a 409, re-read the action first:
curl "https://api.orbit.devotel.io/api/v1/orby/tool-actions/${PENDING_ID}" \
  -H "Authorization: Bearer eyJhbG..."

async function approvePending(jwt: string, pendingActionId: string) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const response = await fetch(
      `https://api.orbit.devotel.io/api/v1/orby/tool-actions/${pendingActionId}/approve`,
      { method: "POST", headers: { Authorization: `Bearer ${jwt}` } },
    );

    if (response.status === 409) {
      const body = await response.json();
      const code = body?.error?.code;
      if (code === "PENDING_ACTION_EXPIRED") {
        showExpiredNotice();
        return null; // window elapsed; ask Orby again instead
      }
      if (code === "PENDING_ACTION_RACE") {
        await sleep(250 * (attempt + 1)); // a concurrent approve won
        continue;
      }
      throw new Error(`approve rejected: ${code}`);
    }

    return (await response.json()).data; // { id, status, result }
  }
  throw new Error("approve lost the race repeatedly");
}

import time
import requests

def approve_pending(jwt, pending_action_id):
    for attempt in range(3):
        response = requests.post(
            f"https://api.orbit.devotel.io/api/v1/orby/tool-actions/{pending_action_id}/approve",
            headers={"Authorization": f"Bearer {jwt}"},
        )

        if response.status_code == 409:
            body = response.json()
            code = body.get("error", {}).get("code")
            if code == "PENDING_ACTION_EXPIRED":
                show_expired_notice()
                return None  # window elapsed; ask Orby again instead
            if code == "PENDING_ACTION_RACE":
                time.sleep(0.25 * (attempt + 1))  # a concurrent approve won
                continue
            raise RuntimeError(f"approve rejected: {code}")

        return response.json()["data"]  # { id, status, result }
    raise RuntimeError("approve lost the race repeatedly")

func approvePending(jwt, pendingActionID string) (map[string]any, error) {
    for attempt := 0; attempt < 3; attempt++ {
        url := fmt.Sprintf(
            "https://api.orbit.devotel.io/api/v1/orby/tool-actions/%s/approve",
            pendingActionID,
        )
        req, err := http.NewRequest("POST", url, nil)
        if err != nil {
            return nil, err
        }
        req.Header.Set("Authorization", "Bearer "+jwt)
        resp, err := http.DefaultClient.Do(req)
        if err != nil {
            return nil, err
        }
        defer resp.Body.Close()

        var envelope struct {
            Data    map[string]any `json:"data"`
            Error   *struct {
                Code string `json:"code"`
            } `json:"error"`
        }
        if err := json.NewDecoder(resp.Body).Decode(&envelope); err != nil {
            return nil, err
        }

        if resp.StatusCode == 409 {
            switch envelope.Error.Code {
            case "PENDING_ACTION_EXPIRED":
                return nil, nil // window elapsed; ask Orby again instead
            case "PENDING_ACTION_RACE":
                time.Sleep(250 * time.Millisecond * time.Duration(attempt+1))
                continue
            }
            return nil, fmt.Errorf("approve rejected: %s", envelope.Error.Code)
        }

        return envelope.Data, nil
    }
    return nil, errors.New("approve lost the race repeatedly")
}

require "net/http"
require "json"

def approve_pending(jwt, pending_action_id)
  attempts = 3

  attempts.times do |attempt|
    uri = URI("https://api.orbit.devotel.io/api/v1/orby/tool-actions/#{pending_action_id}/approve")
    request = Net::HTTP::Post.new(uri)
    request["Authorization"] = "Bearer #{jwt}"
    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end
    envelope = JSON.parse(response.body)

    if response.code == "409"
      code = envelope.dig("error", "code")
      if code == "PENDING_ACTION_EXPIRED"
        return nil # window elapsed; ask Orby again instead
      end
      if code == "PENDING_ACTION_RACE"
        sleep(0.25 * (attempt + 1)) # a concurrent approve won
        next
      end
      raise "approve rejected: "
    end

    return envelope["data"] # { id, status, result }
  end

  raise "approve lost the race repeatedly"
end

<?php
function approvePending(string $jwt, string $pendingActionId): ?array
{
    for ($attempt = 0; $attempt < 3; $attempt++) {
        $curl = curl_init(
            "https://api.orbit.devotel.io/api/v1/orby/tool-actions/{$pendingActionId}/approve"
        );
        curl_setopt_array($curl, [
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => ["Authorization: Bearer {$jwt}"],
            CURLOPT_RETURNTRANSFER => true,
        ]);
        $raw = curl_exec($curl);
        $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
        $envelope = json_decode($raw, true);
        curl_close($curl);

        if ($status === 409) {
            $code = $envelope["error"]["code"] ?? null;
            if ($code === "PENDING_ACTION_EXPIRED") {
                return null; // window elapsed; ask Orby again instead
            }
            if ($code === "PENDING_ACTION_RACE") {
                usleep(250000 * ($attempt + 1)); // a concurrent approve won
                continue;
            }
            throw new RuntimeException("approve rejected: {$code}");
        }

        return $envelope["data"]; // { id, status, result }
    }

    throw new RuntimeException("approve lost the race repeatedly");
}

To cancel instead, POST to /tool-actions/{id}/reject; the same pattern applies.

Poll the pending action and render the countdown

While an approval control is on screen, poll GET /tool-actions/{id} (120 requests per minute per tenant — once every few seconds is enough) and count down to expires_at. When the window elapses, disable the control: the next poll reports the action as cancelled with error_code: PENDING_ACTION_EXPIRED.

PENDING_ID=pact_abc123
curl "https://api.orbit.devotel.io/api/v1/orby/tool-actions/${PENDING_ID}" \
  -H "Authorization: Bearer eyJhbG..."

async function* pollPending(jwt: string, pendingActionId: string) {
  while (true) {
    const response = await fetch(
      `https://api.orbit.devotel.io/api/v1/orby/tool-actions/${pendingActionId}`,
      { headers: { Authorization: `Bearer ${jwt}` } },
    );
    const { data } = await response.json();

    const secondsLeft = Math.max(
      0,
      (new Date(data.expires_at).getTime() - Date.now()) / 1000,
    );
    yield { action: data, secondsLeft };

    if (data.status !== "pending") return; // terminal state reached
    await sleep(2000);
  }
}

for await (const tick of pollPending(jwt, "pact_abc123")) {
  renderCountdown(tick.secondsLeft); // disable the control at 0
}

import time
import datetime as dt
import requests

def poll_pending(jwt, pending_action_id):
    while True:
        response = requests.get(
            f"https://api.orbit.devotel.io/api/v1/orby/tool-actions/{pending_action_id}",
            headers={"Authorization": f"Bearer {jwt}"},
        )
        data = response.json()["data"]

        expires_at = dt.datetime.fromisoformat(data["expires_at"].replace("Z", "+00:00"))
        seconds_left = max(
            0,
            (expires_at - dt.datetime.now(dt.timezone.utc)).total_seconds(),
        )
        yield {"action": data, "seconds_left": seconds_left}

        if data["status"] != "pending":
            return  # terminal state reached
        time.sleep(2)

for tick in poll_pending(jwt, "pact_abc123"):
    render_countdown(tick["seconds_left"])  # disable the control at 0

Threads

List threads

GET /api/v1/orby/threads Return the operator’s most recent threads (up to 50, newest first) for the “Past chats” panel.

curl "https://api.orbit.devotel.io/api/v1/orby/threads" \
  -H "Authorization: Bearer eyJhbG..."

import requests

response = requests.get(
    "https://api.orbit.devotel.io/api/v1/orby/threads",
    headers={"Authorization": "Bearer eyJhbG..."},
)
data = response.json()

req, err := http.NewRequest(
    "GET",
    "https://api.orbit.devotel.io/api/v1/orby/threads",
    nil,
)
if err != nil {
    log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer eyJhbG...")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

require "net/http"
require "json"

uri = URI("https://api.orbit.devotel.io/api/v1/orby/threads")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer eyJhbG..."
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
data = JSON.parse(response.body)

<?php
$curl = curl_init("https://api.orbit.devotel.io/api/v1/orby/threads");
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer eyJhbG..."],
    CURLOPT_RETURNTRANSFER => true,
]);
$raw = curl_exec($curl);
$data = json_decode($raw, true);
curl_close($curl);

{
  "data": {
    "threads": [
      {
        "id": "othr_123",
        "title": "Unassigned conversations",
        "metadata": { "startPage": "/inbox" },
        "created_at": "2026-06-30T12:00:00Z",
        "updated_at": "2026-06-30T12:01:00Z",
        "archived_at": null
      }
    ]
  },
  "meta": {
    "request_id": "req_orby_001",
    "timestamp": "2026-06-30T12:01:00Z"
  }
}

Error envelope (bash + TypeScript + Python)

403 ORBY_SESSION_REQUIRED

{
  "error": {
    "code": "ORBY_SESSION_REQUIRED",
    "message": "Orby requires a dashboard-user bearer token; API-key auth is not accepted.",
    "status": 403
  },
  "meta": { "request_id": "req_orby_auth_01", "timestamp": "2026-06-30T12:01:00Z" }
}

Create a thread

POST /api/v1/orby/threads Pre-allocate an empty thread before the first message (the chat panel uses this to reserve a thread id up front). You can also let POST /assistant create the thread implicitly by omitting thread_id.

string

Optional thread title (max 200 chars). Left empty, the thread is auto-titled from the first message.

object

Optional page context stored on the thread.

Show child attributes

string

Route or page identifier (max 200 chars).

string

Record identifier (max 200 chars).

string

Record label (max 200 chars).

{
  "data": {
    "id": "othr_123",
    "title": null,
    "created_at": "2026-06-30T12:00:00Z",
    "updated_at": "2026-06-30T12:00:00Z"
  },
  "meta": {
    "request_id": "req_orby_002",
    "timestamp": "2026-06-30T12:00:00Z"
  }
}

Error envelope (bash + TypeScript + Python)

422 Validate — missing search text

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body failed schema validation.",
    "status": 422,
    "details": { "field": "title", "reason": "exceeds 200 characters" }
  },
  "meta": { "request_id": "req_orby_val_01", "timestamp": "2026-06-30T12:00:00Z" }
}

Get thread messages

GET /api/v1/orby/threads/{id}/messages Replay a thread’s persisted messages (oldest-first) to re-render history on reload.

string

required

Thread id.

{
  "data": {
    "messages": [
      {
        "id": "omsg_001",
        "role": "user",
        "content": { "text": "How many conversations are unassigned right now?" },
        "created_at": "2026-06-30T12:00:00Z"
      },
      {
        "id": "omsg_002",
        "role": "assistant",
        "content": { "text": "You currently have 7 unassigned conversations." },
        "created_at": "2026-06-30T12:00:02Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_orby_003",
    "timestamp": "2026-06-30T12:00:05Z"
  }
}

Error envelope (bash + TypeScript + Python)

404 THREAD_NOT_FOUND

{
  "error": {
    "code": "THREAD_NOT_FOUND",
    "message": "The requested thread does not belong to the authenticated operator.",
    "status": 404
  },
  "meta": { "request_id": "req_orby_msg_404", "timestamp": "2026-06-30T12:00:05Z" }
}

Tool confirmations

When a turn proposes an action that changes data, Orby does not run it immediately. It emits a tool_pending event carrying a pending_action_id and waits. Approve to execute, or reject to cancel. A pending action expires 5 minutes after it is created; an expired action returns 409 PENDING_ACTION_EXPIRED.

Approve an action

POST /api/v1/orby/tool-actions/{id}/approve Execute the pending action. Returns the tool’s result once it runs.

string

required

The pending_action_id from the tool_pending event.

curl -X POST https://api.orbit.devotel.io/api/v1/orby/tool-actions/pact_abc123/approve \
  -H "Authorization: Bearer eyJhbG..."

const response = await fetch(
  "https://api.orbit.devotel.io/api/v1/orby/tool-actions/pact_abc123/approve",
  { method: "POST", headers: { Authorization: "Bearer eyJhbG..." } },
);
const { data } = await response.json();

import requests

response = requests.post(
    "https://api.orbit.devotel.io/api/v1/orby/tool-actions/pact_abc123/approve",
    headers={"Authorization": "Bearer eyJhbG..."},
)
data = response.json()

req, err := http.NewRequest(
    "POST",
    "https://api.orbit.devotel.io/api/v1/orby/tool-actions/pact_abc123/approve",
    nil,
)
if err != nil {
    log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer eyJhbG...")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

require "net/http"
require "json"

uri = URI("https://api.orbit.devotel.io/api/v1/orby/tool-actions/pact_abc123/approve")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer eyJhbG..."
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
data = JSON.parse(response.body)

<?php
$curl = curl_init("https://api.orbit.devotel.io/api/v1/orby/tool-actions/pact_abc123/approve");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer eyJhbG..."],
    CURLOPT_RETURNTRANSFER => true,
]);
$raw = curl_exec($curl);
$data = json_decode($raw, true);
curl_close($curl);

{
  "data": {
    "id": "pact_abc123",
    "status": "done",
    "result": { "sanitized": "Message queued to +1•••••••00." }
  },
  "meta": {
    "request_id": "req_orby_004",
    "timestamp": "2026-06-30T12:02:00Z"
  }
}

Error envelope (bash + TypeScript + Python)

409 PENDING_ACTION_NOT_APPROVABLE

{
  "error": {
    "code": "PENDING_ACTION_NOT_APPROVABLE",
    "message": "Only a pending action can be approved; this action is already in another state.",
    "status": 409,
    "details": { "current_status": "done" }
  },
  "meta": { "request_id": "req_orby_409appr", "timestamp": "2026-06-30T12:02:00Z" }
}

Reject an action

POST /api/v1/orby/tool-actions/{id}/reject Cancel the pending action without running it.

string

required

The pending_action_id.

{
  "data": {
    "id": "pact_abc123",
    "status": "cancelled"
  },
  "meta": {
    "request_id": "req_orby_005",
    "timestamp": "2026-06-30T12:02:00Z"
  }
}

Error envelope (bash + TypeScript + Python)

409 PENDING_ACTION_EXPIRED

{
  "error": {
    "code": "PENDING_ACTION_EXPIRED",
    "message": "The 5-minute approval window elapsed before the action was confirmed.",
    "status": 409,
    "details": { "expired_at": "2026-06-30T12:05:00Z" }
  },
  "meta": { "request_id": "req_orby_409rej", "timestamp": "2026-06-30T12:02:00Z" }
}

Poll an action

GET /api/v1/orby/tool-actions/{id} Read the current state of a pending action, including its expires_at so you can render a countdown. A pending action whose window has elapsed is reported as cancelled with error_code: PENDING_ACTION_EXPIRED.

string

required

The pending_action_id.

{
  "data": {
    "id": "pact_abc123",
    "tool": "send_sms",
    "args": { "to": "+15555550100", "body": "Your order shipped." },
    "cost_estimate_cents": 1,
    "status": "pending",
    "result": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-06-30T12:00:00Z",
    "expires_at": "2026-06-30T12:05:00Z",
    "executed_at": null,
    "cancelled_at": null
  },
  "meta": {
    "request_id": "req_orby_006",
    "timestamp": "2026-06-30T12:00:30Z"
  }
}

Error envelope (bash + TypeScript + Python)

404 NOT_FOUND

{
  "error": {
    "code": "PENDING_ACTION_NOT_FOUND",
    "message": "No pending action with this id exists for the authenticated operator.",
    "status": 404
  },
  "meta": { "request_id": "req_orby_poll_404", "timestamp": "2026-06-30T12:00:30Z" }
}

Action states are pending, executing, done, undone, failed, and cancelled. Only a pending action can be approved or rejected — acting on any other state returns 409 PENDING_ACTION_NOT_APPROVABLE, and a concurrent second approve returns 409 PENDING_ACTION_RACE. Both approve and reject are idempotent in effect: the action runs (or cancels) exactly once. A done action moves to undone when the operator reverses it within the tool’s undo window — for example, a sent message rolled back inside its 30-second grace period. Treat undone as a terminal state whose side effect has been undone; it differs from cancelled, which marks an action that was rejected (or expired) before it ever ran.

Knowledge-base search

Orby can search the Orbit product documentation so operators can answer “where do I configure X” without leaving the dashboard. These endpoints sit under /api/v1/orby/kb.

Search docs

GET /api/v1/orby/kb/search Hybrid search over the Orbit docs index. Available to any authenticated operator role.

string

required

Search text. 1–500 characters.

integer

default:"10"

Results to return (max 50).

string

Restrict to a docs section.

string

Restrict to a docs category.

{
  "data": {
    "results": [
      {
        "doc_id": "quiet-hours",
        "title": "Quiet hours",
        "section": "messaging",
        "category": "compliance",
        "url": "https://docs.orbit.devotel.io/compliance/quiet-hours",
        "snippet": "Set the hours during which campaigns pause…",
        "score": 0.82,
        "last_updated_at": "2026-06-01T00:00:00Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_orby_007",
    "timestamp": "2026-06-30T12:00:00Z"
  }
}

Error envelope (bash + TypeScript + Python)

422 VALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The `query` parameter is required and must be between 1 and 500 characters.",
    "status": 422,
    "details": { "field": "query" }
  },
  "meta": { "request_id": "req_orby_search_422", "timestamp": "2026-06-30T12:00:00Z" }
}

Find a setting

POST /api/v1/orby/kb/find-setting Map a plain-language description to the dashboard route where the setting lives. Available to any authenticated operator role.

string

required

What the operator wants to configure. 1–500 characters.

integer

default:"10"

Matches to return (max 20).

{
  "data": {
    "matches": [
      {
        "setting_path": "settings.messaging.quiet_hours",
        "dashboard_url": "/settings/messaging#quiet-hours",
        "label": "Quiet hours",
        "description": "Pause outbound campaigns during set hours.",
        "doc_url": "https://docs.orbit.devotel.io/compliance/quiet-hours",
        "snippet": "Set the hours during which campaigns pause…",
        "score": 0.9
      }
    ]
  },
  "meta": {
    "request_id": "req_orby_008",
    "timestamp": "2026-06-30T12:00:00Z"
  }
}

Error envelope (bash + TypeScript + Python)

422 VALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The `description` field is required and must be between 1 and 500 characters.",
    "status": 422,
    "details": { "field": "description" }
  },
  "meta": { "request_id": "req_orby_setting_422", "timestamp": "2026-06-30T12:00:00Z" }
}

Reindex and status (super-admin)

POST /api/v1/orby/kb/reindex triggers a rebuild of the docs index and returns immediately with { "scheduled": true } (or { "ran_inline": true } when the corpus is available in-process). GET /api/v1/orby/kb/status returns a health snapshot: total and stale chunk counts, the last run timestamp, the current version, and cache hit rate. Both require the super-admin role and return 403 INSUFFICIENT_PERMISSIONS otherwise.

Error envelope (bash + TypeScript + Python)

403 INSUFFICIENT_PERMISSIONS

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This operation requires the super-admin role.",
    "status": 403,
    "details": { "required_role": "super_admin" }
  },
  "meta": { "request_id": "req_orby_su_403", "timestamp": "2026-06-30T12:00:00Z" }
}

API Reference

All Endpoints

Orby Assistant API: drive the in-dashboard operator AI

Orby Assistant API

Using the SDKs

Authentication

Rate limits

Run a turn

Stream events

Consume the stream (worked example)

Redeem a pending action

Poll the pending action and render the countdown

Threads

List threads

Create a thread

Get thread messages

Tool confirmations

Approve an action

Reject an action

Poll an action

Knowledge-base search

Search docs

Find a setting

Reindex and status (super-admin)

​Orby Assistant API

​Using the SDKs

​Authentication

​Rate limits

​Run a turn

​Stream events

​Consume the stream (worked example)

​Redeem a pending action

​Poll the pending action and render the countdown

​Threads

​List threads

​Create a thread

​Get thread messages

​Tool confirmations

​Approve an action

​Reject an action

​Poll an action

​Knowledge-base search

​Search docs

​Find a setting

​Reindex and status (super-admin)

Orby Assistant API

Using the SDKs

Authentication

Rate limits

Run a turn

Stream events

Consume the stream (worked example)

Redeem a pending action

Poll the pending action and render the countdown

Threads

List threads

Create a thread

Get thread messages

Tool confirmations

Approve an action

Reject an action

Poll an action

Knowledge-base search

Search docs

Find a setting

Reindex and status (super-admin)