Worked sequences — Orby assistant chains - Devotel Orbit Documentation

Worked sequences — Orby assistant chains

Eight operations cover the Orby surface most integrations actually run: grounding search, thread pre-allocation, streamed assistant turns, the tool-action approval gate, the “where do I configure X” settings lookup, thread replay on reload, knowledge-base reindex, and index health. Each sequence below shows the body you send and the body the API returns. All Orby routes are operator-session only: authenticate with a dashboard Bearer token (Authorization: Bearer $ORBIT_OPERATOR_JWT), not an X-API-Key. Key-authenticated requests are rejected with 403 ORBY_SESSION_REQUIRED. Reindex and index status additionally require the super-admin role.

1. Search the Orbit knowledge base

Hybrid search over the Orbit product-docs index. Send query and an optional limit (default 10, max 50). Returns ranked data.results, each with doc_id, title, section, category, url, snippet, score, and last_updated_at. While the index is cold or reindexing the endpoint degrades to an empty result set with a kb_outage_hint instead of erroring.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/orby/kb/search?query=quiet%20hours&limit=5" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT"

Node.js

const params = new URLSearchParams({ query: "quiet hours", limit: "5" });
const res = await fetch(
  `https://api.orbit.devotel.io/api/v1/orby/kb/search?${params}`,
  { headers: { Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}` } },
);
console.log(await res.json());

200

{
  "data": {
    "results": [
      {
        "doc_id": "doc_compliance_quiet_hours",
        "title": "Quiet hours and sending windows",
        "section": "Compliance",
        "category": "messaging",
        "url": "/guides/quiet-hours",
        "snippet": "Quiet hours suppress outbound sends inside the tenant-configured window. The check runs per recipient timezone on every scheduled batch…",
        "score": 0.91,
        "last_updated_at": "2026-09-12T08:14:22.000Z"
      },
      {
        "doc_id": "doc_campaigns_schedule",
        "title": "Schedule a campaign",
        "section": "Campaigns",
        "category": "messaging",
        "url": "/guides/campaign-scheduling",
        "snippet": "A scheduled campaign respects the org-level quiet-hours window before per-recipient overrides…",
        "score": 0.83,
        "last_updated_at": "2026-08-30T16:02:41.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01J8WN4P2K6E3Z9D5QXB7AVTSQ",
    "timestamp": "2026-09-30T12:00:00.000Z"
  }
}

2. Create an Orby thread

Pre-allocates a new Orby conversation thread before the first user message (the dashboard pre-allocation flow). Accepts an optional title and page context; returns the new thread’s id, title, and created_at / updated_at timestamps.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/orby/threads" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Failed SMS investigation", "page": { "page": "/en/messaging/delivery-report" } }'

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/orby/threads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Failed SMS investigation",
    page: { page: "/en/messaging/delivery-report" },
  }),
});
const { data } = await res.json();
console.log(data.id); // ort_01J8WM2QXA4C9VZ0PB1H7KY3GB

200

{
  "data": {
    "id": "ort_01J8WM2QXA4C9VZ0PB1H7KY3GB",
    "title": "Failed SMS investigation",
    "created_at": "2026-09-30T11:54:01.412Z",
    "updated_at": "2026-09-30T11:54:01.412Z"
  },
  "meta": {
    "request_id": "req_01J8WN5R4K7E1A8C2QZD6BHVWM",
    "timestamp": "2026-09-30T11:54:01.512Z"
  }
}

3. Start an Orby assistant turn (SSE stream)

Runs one Orby turn and streams the result as Server-Sent Events (text/event-stream): router, status, token, tool_start, tool_pending, tool_end, refusal, clarify, response, and error frames. Send { message, thread_id?, page? } — omit thread_id to start a new thread. Rate-limited to 60 turns/min per operator.

cURL

curl -N -X POST "https://api.orbit.devotel.io/api/v1/orby/assistant" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "message": "Summarize yesterday'"'"'s failed SMS deliveries.", "thread_id": "ort_01J8WM2QXA4C9VZ0PB1H7KY3GB" }'

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/orby/assistant", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}`,
    "Content-Type": "application/json",
    Accept: "text/event-stream",
  },
  body: JSON.stringify({
    message: "Summarize yesterday's failed SMS deliveries.",
    thread_id: "ort_01J8WM2QXA4C9VZ0PB1H7KY3GB",
  }),
});

let buffer = "";
for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
  buffer += new TextDecoder().decode(chunk);
  let sep: number;
  while ((sep = buffer.indexOf("\n\n")) !== -1) {
    const frame = buffer.slice(0, sep);
    buffer = buffer.slice(sep + 2);
    const [eventLine, dataLine] = frame.split("\n");
    const event = eventLine.replace(/^event:\s*/, "");
    const data = JSON.parse(dataLine.replace(/^data:\s*/, ""));
    if (event === "token") process.stdout.write(data.content);
    if (event === "response") console.log("\nturn:", data);
  }
}

SSE 200

event: router
data: { "intent": "query", "confidence": 0.92 }

event: status
data: { "status": "thinking" }

event: token
data: { "content": "Yesterday saw 41 failed deliveries, mostly 30005 (destination unreachable)." }

event: tool_pending
data: { "toolCallId": "orbyTurn_0192", "tool": "send_sms", "input": { "to": "+14155552671", "body": "Retry the 41 failed sends" }, "cost_estimate_cents": 41, "pending_action_id": "opa_01J8WM0K6T4B7D9YE3P5H1JRMN" }

event: response
data: { "response": "Yesterday saw 41 failed deliveries, mostly 30005. Approve the pending retry to resend them.", "turn_id": "orbyTurn_01J8WM1A2B3C4D5E6F7G8H9J", "thread_id": "ort_01J8WM2QXA4C9VZ0PB1H7KY3GB", "tokens_used": 312, "cost_cents_billable": 0 }

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

Distinguish a tool_pending event (paused on a confirmation gate — approve it with POST /api/v1/orby/tool-actions/{id}/approve) from token deltas (the answer, safe to render in UI). The response frame closes the turn with turn_id + thread_id; feed thread_id back on the next turn to continue the thread.

4. Get a pending Orby tool action and approve it

Poll the pending action the turn paused on. Returns the action’s tool, args, cost_estimate_cents, status, result, error_code / error_message, and created_at / expires_at / executed_at / cancelled_at timestamps. A pending row past its five-minute window is lazily flipped to cancelled. Poll:

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/orby/tool-actions/opa_01J8WM0K6T4B7D9YE3P5H1JRMN" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT"

Node.js

const id = "opa_01J8WM0K6T4B7D9YE3P5H1JRMN";
const res = await fetch(
  `https://api.orbit.devotel.io/api/v1/orby/tool-actions/${id}`,
  { headers: { Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}` } },
);
console.log(await res.json());

200

{
  "data": {
    "id": "opa_01J8WM0K6T4B7D9YE3P5H1JRMN",
    "tool": "send_sms",
    "args": { "to": "+14155552671", "body": "Retry the 41 failed sends" },
    "cost_estimate_cents": 41,
    "status": "pending",
    "result": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-30T11:57:02.841Z",
    "expires_at": "2026-09-30T12:02:02.841Z",
    "executed_at": null,
    "cancelled_at": null
  },
  "meta": {
    "request_id": "req_01J8WN6T4K8E2B9D3QZAXCWRNP",
    "timestamp": "2026-09-30T11:57:04.102Z"
  }
}

Approve:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/orby/tool-actions/opa_01J8WM0K6T4B7D9YE3P5H1JRMN/approve" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT" \
  -H "Idempotency-Key: opa_approve_01J8WM7"

Node.js

const approveRes = await fetch(
  `https://api.orbit.devotel.io/api/v1/orby/tool-actions/${id}/approve`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}`,
      "Idempotency-Key": `opa_approve_${Date.now()}`,
    },
  },
);
console.log(await approveRes.json());

200

{
  "data": {
    "id": "opa_01J8WM0K6T4B7D9YE3P5H1JRMN",
    "status": "done",
    "result": { "sanitized": "Queued 41 SMS to +14155552671. Batch bat_01J8WNA accepted." }
  },
  "meta": {
    "request_id": "req_01J8WN7W9KAE4CF6QZGDXFTSRV",
    "timestamp": "2026-09-30T12:00:41.230Z"
  }
}

The approval window expires five minutes after the gate was raised — a 409 returns error.details.id plus the current status when the row is already terminal.

5. Find the dashboard setting for a described task

“Where do I configure X” helper — resolves a natural-language description to the dashboard settings that control it. Returns ranked data.matches, each with setting_path, dashboard_url, label, description, doc_url, snippet, and score. Degrades to an empty result with a kb_outage_hint while the knowledge base is initialising.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/orby/kb/find-setting" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "description": "stop SMS sends during the night", "limit": 3 }'

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/orby/kb/find-setting", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ description: "stop SMS sends during the night", limit: 3 }),
});
console.log(await res.json());

200

{
  "data": {
    "matches": [
      {
        "setting_path": "Settings → Messaging → Quiet hours",
        "dashboard_url": "https://orbit.devotel.io/en/settings/messaging#quiet-hours",
        "label": "Quiet hours window",
        "description": "Suppress outbound sends inside the window you set; recipients' local time decides the boundary.",
        "doc_url": "https://docs.orbit.devotel.io/settings/quiet-hours",
        "snippet": "Set a daily quiet-hours window per tenant. Enabled sends queue until the window closes…",
        "score": 0.93
      },
      {
        "setting_path": "Settings → Compliance → Sending rules",
        "dashboard_url": "https://orbit.devotel.io/en/settings/compliance#sending-rules",
        "label": "Per-channel send schedule",
        "description": "Force a per-channel schedule so SMS never fires inside legislated windows for regulated geographies.",
        "doc_url": "https://docs.orbit.devotel.io/compliance/sending-rules",
        "snippet": "Sending rules let you pin quiet hours per country/jurisdiction…",
        "score": 0.81
      }
    ]
  },
  "meta": {
    "request_id": "req_01J8WN8Z2KBG5DH8QZKFXJVRWC",
    "timestamp": "2026-09-30T12:04:10.441Z"
  }
}

6. List the operator’s Orby threads and a thread’s messages

List up to the 50 most recent threads (the dashboard Past-chats panel) — each with id, title, metadata, and created_at / updated_at / archived_at timestamps — then replay one thread’s persisted message log (oldest-first) so the dashboard can re-render history on reload. List threads:

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/orby/threads" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/orby/threads", {
  headers: { Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}` },
});
console.log(await res.json());

200

{
  "data": {
    "threads": [
      {
        "id": "ort_01J8WM2QXA4C9VZ0PB1H7KY3GB",
        "title": "Failed SMS investigation",
        "metadata": { "startPage": "/en/messaging/delivery-report" },
        "created_at": "2026-09-30T11:54:01.412Z",
        "updated_at": "2026-09-30T12:01:38.110Z",
        "archived_at": null
      },
      {
        "id": "ort_01J7QR9VTK4B2D6X8ZPW0M3EA5HN",
        "title": "Where do I set quiet hours?",
        "metadata": null,
        "created_at": "2026-09-21T09:12:44.900Z",
        "updated_at": "2026-09-21T09:14:02.004Z",
        "archived_at": "2026-09-22T08:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01J8WNA4KDH6FK9QZMHXKTYSZL",
    "timestamp": "2026-09-30T12:05:11.055Z"
  }
}

Replay messages:

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/orby/threads/ort_01J8WM2QXA4C9VZ0PB1H7KY3GB/messages" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/orby/threads/ort_01J8WM2QXA4C9VZ0PB1H7KY3GB/messages",
  { headers: { Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}` } },
);
console.log(await res.json());

200

{
  "data": {
    "messages": [
      {
        "id": "orm_01J8WM3B4C5D6E7F8G9H0J1K",
        "role": "user",
        "content": "Summarize yesterday's failed SMS deliveries.",
        "created_at": "2026-09-30T11:57:01.102Z"
      },
      {
        "id": "orm_01J8WM4C5D6E7F8G9H0J1K2L",
        "role": "assistant",
        "content": "Yesterday saw 41 failed deliveries, mostly 30005. Approve the pending retry to resend them.",
        "created_at": "2026-09-30T11:57:04.310Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01J8WNB7KEH7GN2QZPKYLVBXML",
    "timestamp": "2026-09-30T12:05:19.901Z"
  }
}

7. Trigger an Orby knowledge-base reindex

Super-admin only. Triggers a manual reindex of the Orbit docs corpus. Runs inline when the docs source is mounted on the pod, otherwise schedules the reindex for the background worker. Returns { scheduled, ran_inline, error }.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/orby/kb/reindex" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT" \
  -H "Idempotency-Key: orby_reindex_20260930"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/orby/kb/reindex", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}`,
    "Idempotency-Key": `orby_reindex_${new Date().toISOString().slice(0, 10)}`,
  },
});
console.log(await res.json());

200

{
  "data": {
    "scheduled": true,
    "ran_inline": false,
    "error": null
  },
  "meta": {
    "request_id": "req_01J8WNCAXFJAHM4QZSMZNCPYRV",
    "timestamp": "2026-09-30T12:06:02.114Z"
  }
}

8. Read index status

Super-admin only. Health snapshot of the Orby docs index: collection name and shape, total and stale chunk counts, last reindex timestamp, current version, and in-process cache statistics.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/orby/kb/status" \
  -H "Authorization: Bearer $ORBIT_OPERATOR_JWT"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/orby/kb/status", {
  headers: { Authorization: `Bearer ${process.env.ORBIT_OPERATOR_JWT!}` },
});
console.log(await res.json());

200

{
  "data": {
    "collection": "orbit_docs",
    "shape": "healthy",
    "total_chunks": 18412,
    "stale_chunks": 23,
    "last_run_at": "2026-09-30T06:00:09.881Z",
    "current_version": "2026-09-30.1",
    "cache": {
      "size": 213,
      "hit_rate": 0.87,
      "hits": 1489,
      "misses": 222
    }
  },
  "meta": {
    "request_id": "req_01J8WNDC2GKBJN7QZTNVERWCBX",
    "timestamp": "2026-09-30T12:07:44.661Z"
  }
}

Errors worth branching on

These failures cover the assistant turn (POST /api/v1/orby/assistant), the heartbeat of every copilot chat. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The bearer token is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_orbya1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the session token failing before the route ran — it never means the resource is wrong. Re-mint the dashboard session or rotate the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The credential is valid but does not carry the operator-session this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_orbya1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 on Orby usually means the request arrived with an X-API-Key instead of a session Bearer token — Orby routes are operator-session only. Super-admin-only routes (/kb/reindex, /kb/status) also return 403 with INSUFFICIENT_PERMISSIONS for non-admin roles.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "thread_id", "value": "ort_0192", "expected": "an active thread id from POST /api/v1/orby/threads" }
    },
    "meta": {
      "request_id": "req_orbyb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and open a new thread and re-fire the same prompt against the fresh thread id instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_orbyc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

402 — Feature gate

  {
    "error": {
      "code": "ORBY_BUDGET_EXCEEDED",
      "message": "The Orby run exceeded its token budget for this session.",
      "status": 402,
      "details": { "budget_tokens": 50000, "used_tokens": 51214 }
    },
    "meta": {
      "request_id": "req_orbyd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Rotate the session or return control to the operator; do not re-fire immediately.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the session token itself fails	Surface. Re-mint the dashboard session; do not retry the same request.
403 `FORBIDDEN`	wrong credential type, or the role lacks this operation’s grant	Surface. Use an operator session Bearer, not an API key; fix the role; a retry with the same credential never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`ORBY_BUDGET_EXCEEDED` (402 feature gate)	page-specific gating	Branch on `error.code`. Rotate the session or return control to the operator; do not re-fire immediately.

API Reference

All Endpoints

Worked sequences — Orby assistant chains