AI API

A focused set of LLM-backed primitives that the Orbit platform uses internally — message analysis, reply suggestion, intent classification, summarization, content generation, and a small knowledge-base utility. All LLM requests route through Orbit’s partner-vetted Anthropic gateway — you don’t manage model-provider keys directly. Base path: /api/v1/ai Authentication: API key (X-API-Key) or session JWT. Service-to-service callers authenticate with X-Orbit-Signature (an HMAC-signed request) and get the developer role to cap blast radius. The legacy X-Internal-Token bearer header is still accepted only until 2026-09-01, after which requests using it will be rejected — internal callers should migrate to X-Orbit-Signature before that date. Response envelope: every route returns a { "data": <payload>, "meta": { "request_id", "timestamp" } } wrapper. The samples below show the full envelope once and then the inner data payload only. All endpoints except /kb/* share a 30-requests-per-minute LLM rate limit; KB reads sit behind a lighter authenticated-read limit.

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>(
  "POST",
  "/ai/analyze",
  {}
);

Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Analysis & insight

Method	Path	Purpose
`POST`	`/api/v1/ai/analyze`	General message / content analysis
`POST`	`/api/v1/ai/analyze-message/{id}`	Analyze a specific message by ID
`POST`	`/api/v1/ai/classify-intent`	Classify a message’s intent
`POST`	`/api/v1/ai/summarize-conversation`	Summarize a long conversation
`POST`	`/api/v1/ai/dashboard-insights`	Generate dashboard insight prose

Analyze

POST /api/v1/ai/analyze analyzes free text for sentiment, intent, detected language, and extracted topics. Feed it any customer-facing text — an inbound SMS body, an email snippet, a product review — and it returns a structured breakdown you can route on.

Field	Type	Required	Notes
`text`	`string`	yes	1–10,000 characters of the text to analyze.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/analyze \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your delivery is 3 days late and no one is answering my refund request."
  }'

{
  "data": {
    "sentiment": { "score": -0.82, "label": "negative" },
    "intent": { "label": "complaint", "confidence": 0.78 },
    "language": { "code": "en", "name": "English", "confidence": 0.99 },
    "topics": ["refund", "delivery", "customer-support"]
  },
  "meta": {
    "request_id": "req_7f2h9k",
    "timestamp": "2026-08-28T10:15:04.321Z"
  }
}

A body missing text returns 422 VALIDATION_ERROR.

Analyze a message by ID

POST /api/v1/ai/analyze-message/{id} loads one stored message, runs the same analysis, and persists the result into the message’s metadata so you get a durable audit trail.

Field	Type	Required	Notes
`id` (path)	`string`	yes	UUID of the message to analyze.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/analyze-message/9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "message_id": "9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11",
  "analysis": {
    "sentiment": "negative",
    "intent": "support",
    "language": "en",
    "urgency": 4,
    "summary": "Customer reports a billing error and requests a refund."
  }
}

A missing id returns 422; an unknown or body-less message returns 404 / 422.

Classify intent

POST /api/v1/ai/classify-intent classifies the dominant intent for a conversation (billing, support, sales, complaint, general inquiry, and so on) from its transcript, with a confidence score and a one-line rationale.

Field	Type	Required	Notes
`conversation_id`	`string`	yes	Conversation to classify.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/classify-intent \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_01H3X2K4T7"
  }'

{
  "conversation_id": "conv_01H3X2K4T7",
  "intent": "billing",
  "sub_intent": "refund_request",
  "confidence": 0.86,
  "reasoning": "Customer raises a refund question and quotes an invoice number."
}

A conversation with no messages returns 422 with the message “Conversation has no messages.”

Summarize a conversation

POST /api/v1/ai/summarize-conversation collapses a thread into a one-paragraph summary, key topics, and the overall sentiment — the same digest the supervisor inbox uses.

Field	Type	Required	Notes
`conversation_id`	`string`	yes	Conversation to summarize.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/summarize-conversation \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_01H3X2K4T7"
  }'

{
  "conversation_id": "conv_01H3X2K4T7",
  "summary": "The customer reports being double-charged for last month's plan. The agent confirmed the duplicate invoice, issued an immediate refund, and promised a confirmation email.",
  "key_topics": ["refund", "duplicate-charge", "resolution"],
  "sentiment": "neutral",
  "message_count": 12
}

Generation & rewriting

Method	Path	Purpose
`POST`	`/api/v1/ai/suggest-reply`	Draft a reply to an inbound message
`POST`	`/api/v1/ai/generate-content`	Generate marketing content from a brief
`POST`	`/api/v1/ai/improve-text`	Rewrite for tone / clarity / length
`POST`	`/api/v1/ai/translate`	Translate to a target language
`POST`	`/api/v1/ai/compose-campaign`	Compose a multi-step campaign from a goal
`POST`	`/api/v1/ai/optimize-channel`	Recommend best channel/time for a contact

Suggest a reply

POST /api/v1/ai/suggest-reply reads the conversation transcript and returns 2–3 ready-to-send reply drafts, each tagged with a tone (professional, empathetic, concise) and a confidence score — the same inline copilot the agent inbox uses.

Field	Type	Required	Notes
`conversation_id`	`string`	yes	Conversation to draft replies for.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/suggest-reply \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_01H3X2K4T7"
  }'

{
  "conversation_id": "conv_01H3X2K4T7",
  "channel": "sms",
  "suggestions": [
    {
      "text": "Confirming the duplicate charge now. Issuing the refund immediately.",
      "tone": "professional",
      "confidence": 0.88
    },
    {
      "text": "I can see the billing problem you flagged. Let me check the duplicate charge and refund it now.",
      "tone": "empathetic",
      "confidence": 0.82
    },
    {
      "text": "On it — refund issued, confirmation coming.",
      "tone": "concise",
      "confidence": 0.76
    }
  ]
}

A missing conversation_id returns 422 VALIDATION_ERROR:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Conversation ID is required",
    "status": 422,
    "details": {
      "issues": [
        { "field": "conversation_id", "message": "Conversation ID is required" }
      ]
    }
  },
  "meta": {
    "request_id": "req_9a1cd4",
    "timestamp": "2026-08-28T10:31:22.114Z"
  }
}

Generate content

POST /api/v1/ai/generate-content writes channel-appropriate message copy from a brief. The campaign composer and send dialogs both call this — pass a channel so the result fits the target (SMS length, WhatsApp formatting, email subject/body). The server-side grounding guard strips any offer, discount, price, or urgency claim the operator’s brief did not already make.

Field	Type	Required	Notes
`prompt`	`string`	yes	What you want the message to say (1–2,000 chars).
`tone`	`string`	no	One of `professional`, `casual`, `urgent`, `friendly` (default `professional`).
`channel`	`string`	no	Target channel (`sms`, `whatsapp`, `email`, …).
`campaign_name`	`string`	no	Campaign title the copy should anchor on.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/generate-content \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Invite loyal customers to our end-of-season sale preview.",
    "tone": "friendly",
    "channel": "sms",
    "campaign_name": "End-of-season VIP preview"
  }'

{
  "content": "Hi Ana, you're a valued member of our club — come preview our end-of-season VIP sale this weekend in store or online. We can't wait to see you.",
  "channel": "sms",
  "tone": "friendly",
  "char_count": 161
}

Improve text

POST /api/v1/ai/improve-text rewrites an existing message. Choose the action: improve (general polish), shorter, longer, change_tone, fix_grammar, or rephrase. If the model returns no usable rewrite the endpoint hands back your original text unchanged with a 200 — the AI-assist button never breaks the composer.

Field	Type	Required	Notes
`text`	`string`	yes	The text to rewrite (1–10,000 chars).
`action`	`string`	yes	One of `improve`, `shorter`, `longer`, `change_tone`, `fix_grammar`, `rephrase`.
`tone`	`string`	no	Target tone when `action` is `change_tone`.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/improve-text \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi Ana, your order is due friday. Please contact support with any questions.",
    "action": "fix_grammar"
  }'

{
  "text": "Hi Ana, your order is due Friday. Please contact support with any questions.",
  "action": "fix_grammar"
}

Translate

POST /api/v1/ai/translate translates free text into a target language, reporting the detected source language in the response.

Field	Type	Required	Notes
`text`	`string`	yes	1–10,000 chars to translate.
`target_language`	`string`	yes	ISO code or language name (2–50 chars).

curl -X POST https://api.orbit.devotel.io/api/v1/ai/translate \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Good morning, Ana. Your order shipped today.",
    "target_language": "es"
  }'

{
  "translated": "Buenos días, Ana. Tu pedido ha enviado hoy.",
  "sourceLang": "en"
}

Compose a campaign

POST /api/v1/ai/compose-campaign turns a plain-English goal into a full campaign blueprint: a name and description, per-channel message drafts, a visual journey graph (React Flow nodes and edges) ready to drop into the canvas, and an audience hint. The result is a draft — the operator still reviews it and clicks Launch.

Field	Type	Required	Notes
`goal`	`string`	yes	Plain-English campaign goal (5–2,000 chars).
`audience_segment`	`string`	no	Contact-score segment to target (`champion`, `high_value_engaged`, `engaged`, `new`, `passive`, `at_risk`).
`audience_description`	`string`	no	Free-text audience description to embed in the LLM context.
`channels`	`string[]`	no	Channels to build into the journey.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/compose-campaign \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Re-engage customers who haven\'t purchased in 60 days with a VIP discount.",
    "audience_segment": "at_risk",
    "channels": ["sms", "email"]
  }'

{
  "name": "Lapsed-customer VIP winback",
  "description": "Re-engaging at-risk customers with a VIP discount prompt.",
  "audience": {
    "segment_label": "at_risk",
    "description": "Contacts with no purchase in the last 60 days."
  },
  "messages": {
    "sms": {
      "body": "Hi Ana, we miss you! Here's a VIP discount on your next order."
    },
    "email": {
      "subject": "We'd love to see you back",
      "body": "Hi Ana, it's been a while — here's a VIP discount to welcome you back."
    }
  },
  "journey_definition": {
    "nodes": [
      { "id": "trigger", "type": "trigger", "data": { "label": "Campaign start" } },
      { "id": "audience", "type": "audience", "data": { "label": "at_risk" } },
      { "id": "send_sms", "type": "send", "data": { "label": "SMS" } }
    ],
    "edges": [
      { "id": "trigger->audience", "source": "trigger", "target": "audience" },
      { "id": "audience->send_sms", "source": "audience", "target": "send_sms" }
    ]
  },
  "rationale": "An early SMS nudge converts lapsed VIP discount interest into re-purchase."
}

Optimize channel

POST /api/v1/ai/optimize-channel scores a recipient’s delivery history, reachable identifiers, and cost to recommend the best channel (with fallbacks) for one message. Campaigns use this as the auto channel selector.

Field	Type	Required	Notes
`to`	`string`	yes	Recipient phone number or email.
`message_type`	`string`	no	`marketing`, `transactional`, or `otp` (default `transactional`).
`goal`	`string`	no	`cheapest`, `fastest`, `highest_engagement`, or `balanced` (default `balanced`).
`available_channels`	`string[]`	no	Channels to consider.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/optimize-channel \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "message_type": "marketing",
    "goal": "highest_engagement"
  }'

{
  "channel": "whatsapp",
  "fallbacks": ["sms"],
  "reason": "Prior deliveries show this contact most often responds on WhatsApp.",
  "estimatedCost": 0.02,
  "confidence": 0.74
}

Inference building blocks

Two general-purpose endpoints let you run embeddings and chat inference on the same managed fleet — and the same wallet — as the rest of your Orbit comms. Both are OpenAI-compatible, so existing SDKs drop in by pointing their base URL at /api/v1/ai.

Method	Path	Purpose
`POST`	`/api/v1/ai/embeddings`	Generate embedding vectors for one or more texts
`POST`	`/api/v1/ai/chat/completions`	Run a chat completion (general inference)

Both endpoints call a model provider on every request and are billed per token, metered to your workspace wallet. They share the same rate limit as the other AI routes.

Embeddings

POST /api/v1/ai/embeddings returns one vector per input. Send input as a single string, or as an array of up to 96 strings (each 1–10,000 characters) to embed a batch in one request.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/embeddings \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["order status", "refund policy"]
  }'

Field	Type	Required	Notes
`input`	`string` or `string[]`	yes	One text, or up to 96 texts (each 1–10,000 chars).

The OpenAI-compatible envelope (object: "list", per-input embedding, usage) sits under data:

{
  "object": "list",
  "model": "orbit-embed",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0131, -0.0427, 0.1180, 0.2079, -0.0734] },
    { "object": "embedding", "index": 1, "embedding": [0.0064, 0.0912, -0.1588, 0.1011, 0.0242] }
  ],
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}

A malformed body (missing input, an empty string, or more than 96 items) returns 400.

Chat completions

POST /api/v1/ai/chat/completions is OpenAI-compatible. Point any OpenAI SDK at your /api/v1/ai base URL — the SDK appends /chat/completions — and send a messages array. OpenAI model ids are remapped to the platform’s managed model, so you don’t manage provider keys.

curl -X POST https://api.orbit.devotel.io/api/v1/ai/chat/completions \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a concise support assistant." },
      { "role": "user", "content": "Summarize our refund policy in one line." }
    ]
  }'

Field	Type	Required	Notes
`messages`	`object[]`	yes	1–50 turns; each has `role` (`system`/`user`/`assistant`) and `content` (1–100,000 chars).
`model`	`string`	no	Optional model id; OpenAI ids are remapped to the platform’s fast tier.
`temperature`	`number`	no	Sampling temperature, `0`–`2`.
`max_tokens`	`integer`	no	Output token cap, `1`–`8192`.
`response_format`	`object`	no	Set `{ "type": "json_object" }` to force JSON output (default `text`).

The OpenAI-style chat.completion envelope (choices, usage) sits under data:

{
  "id": "chatcmpl-req_4d2e9f",
  "object": "chat.completion",
  "created": 1792800000,
  "model": "orbit-inference-default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Customers can request a refund within 30 days of purchase."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 17,
    "total_tokens": 59
  }
}

A body missing messages (or with an out-of-range field) returns 400.

Node / OpenAI SDK snippet

The two inference endpoints are an OpenAI drop-in — set the base URL to /api/v1/ai, send any OpenAI model id, and it is remapped to the platform’s managed model. Either library style works:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORBIT_API_KEY,
  baseURL: "https://api.orbit.devotel.io/api/v1/ai",
});

const completion = await client.chat.completions.create({
  model: "orbit-inference-default",
  messages: [
    { role: "system", content: "You are a concise support assistant." },
    { role: "user", content: "Summarize our refund policy in one line." },
  ],
});

console.log(completion.choices[0].message.content);

Plain fetch works too — wrap the API in a helper that posts to the Orbit envelope and reads data:

const res = await fetch("https://api.orbit.devotel.io/api/v1/ai/chat/completions", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [
      { role: "system", content: "You are a concise support assistant." },
      { role: "user", content: "Summarize our refund policy in one line." },
    ],
  }),
});

const { data } = await res.json();
console.log(data.choices[0].message.content);

Knowledge base

An embedded, org-wide knowledge base: ingest documents (upload, URL, markdown, or a bulk help-center import), keep them fresh with a staleness scorecard and per-document verification, and query them with raw semantic search or a grounded answer with citations. For a separately provisioned, per-knowledge-base store, use the Knowledge Bases API instead.

Method	Path	Purpose	Request
`GET`	`/api/v1/ai/kb/documents`	List embedded KB documents (keyset-paged)	Query: `cursor`, `limit` (1–100, default 100)
`POST`	`/api/v1/ai/kb/documents`	Upload or import a document	Multipart file, or JSON `{ "source_type": "url", "source_url", "name"?, "metadata"? }` / `{ "source_type": "markdown", "name", "content" }`
`POST`	`/api/v1/ai/kb/import/help-center`	Bulk-import a public Zendesk Guide help center — one document per published article	JSON `{ "subdomain", "provider"?, "locale"?, "name_prefix"?, "max_articles"? (1–1000, default 250) }`
`GET`	`/api/v1/ai/kb/documents/{id}`	Get a document	Path: `id` (UUID)
`DELETE`	`/api/v1/ai/kb/documents/{id}`	Delete a document and its vectors	Path: `id` (UUID)
`POST`	`/api/v1/ai/kb/documents/{id}/reindex`	Force reindex	Path: `id` (UUID)
`POST`	`/api/v1/ai/kb/documents/{id}/verify`	Stamp a document as reviewed and still accurate (`last_verified_at`)	Path: `id` (UUID)
`GET`	`/api/v1/ai/kb/staleness`	Org-wide freshness scorecard — stale-document counts by reason	Query: `limit` (1–1000, default 25)
`GET`	`/api/v1/ai/kb/connectors`	Browse the knowledge-connector catalog	Query: `category`?, `status`?, `search`?
`GET`	`/api/v1/ai/kb/connectors/{id}`	Get one connector plus its activation detail	Path: `id` (connector slug)
`POST`	`/api/v1/ai/kb/search`	Semantic search across documents (raw chunks + scores)	JSON `{ "query", "limit"? (1–20, default 5), "threshold"? }`
`POST`	`/api/v1/ai/kb/answers`	Grounded answer with citations and a confidence score	JSON `{ "question", "knowledge_base_ids"?, "limit"? (1–10, default 8), "threshold"?, "min_confidence"?, "language"? }`

Mini-cookbook: ingest → poll → search → answer

The full KB lifecycle in four calls. Upload a markdown document, poll it until it is ready, run a raw semantic search, then get a grounded answer with citations. Like the rest of /api/v1/ai, these routes have no typed SDK helper today — the samples below pair each step’s curl with the Node SDK generic orbit.request escape hatch or plain fetch, and the Python SDK client.request (which prepends /api/v1) or plain requests, following the same pattern as the Verify factor suite.

1. Ingest a document

POST /api/v1/ai/kb/documents ingests a markdown document, uploads a file, or imports a public URL. One document at a time.

cURL
Node.js SDK
Node.js (fetch)
Python SDK
Python (requests)

curl -X POST https://api.orbit.devotel.io/api/v1/ai/kb/documents \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "markdown",
    "name": "Refund policy",
    "content": "# Refund policy\n\nFull refund within 30 days; partial refund between 30 and 90 days. Contact support for a receipt."
  }'

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

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

const { data } = await orbit.request<{
  document: { id: string; name: string; source_type: string; status: string };
}>('POST', '/api/v1/ai/kb/documents', {
  data: {
    source_type: 'markdown',
    name: 'Refund policy',
    content:
      '# Refund policy\n\nFull refund within 30 days; partial refund between 30 and 90 days. Contact support for a receipt.',
  },
});
const documentId = data.document.id; // poll this id in step 2

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/documents', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source_type: 'markdown',
    name: 'Refund policy',
    content:
      '# Refund policy\n\nFull refund within 30 days; partial refund between 30 and 90 days. Contact support for a receipt.',
  }),
});

const { data } = await res.json();
const documentId = data.document.id;

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

response = client.request("POST", "/ai/kb/documents", json={
    "source_type": "markdown",
    "name": "Refund policy",
    "content": "# Refund policy\n\nFull refund within 30 days; partial refund between 30 and 90 days. Contact support for a receipt.",
})
document_id = response["data"]["document"]["id"]

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/ai/kb/documents",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={
        "source_type": "markdown",
        "name": "Refund policy",
        "content": "# Refund policy\n\nFull refund within 30 days; partial refund between 30 and 90 days. Contact support for a receipt.",
    },
)
document_id = res.json()["data"]["document"]["id"]

The response carries the new document record (id, name, source_type, status, chunk/token counts, timestamps) under data — every example above reads the same envelope, so curl, SDK, and fetch/requests stay interchangeable. It enters processing, generating a chunk index on the server. To upload a binary file instead, send multipart/form-data (10 MB max). For a public URL source, send { "source_type": "url", "source_url": "https://example.com/policy" }. For a bulk Zendesk Guide import, POST /kb/import/help-center queues one document per published article.

2. Poll until ready

GET /api/v1/ai/kb/documents/{id} checks the document status.

curl https://api.orbit.devotel.io/api/v1/ai/kb/documents/9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "document": {
      "id": "9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11",
      "name": "Refund policy",
      "source_type": "markdown",
      "status": "ready",
      "chunk_count": 8,
      "total_tokens": 2140,
      "size_bytes": 923,
      "created_at": "2026-08-28T10:12:03.421Z",
      "updated_at": "2026-08-28T10:13:11.200Z"
    },
    "staleness": { "is_stale": false, "reasons": [] }
  }
}

Same poll in code — Node SDK first, plain fetch below it; Python SDK client.request and requests take one-second sleep loops:

Node.js SDK
Node.js (fetch)
Python SDK
Python (requests)

const { data } = await orbit.request<{
  document: { status: string };
  staleness: { is_stale: boolean; reasons: string[] };
}>('GET', '/api/v1/ai/kb/documents/9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11');

if (data.document.status !== 'ready') {
  // still indexing — poll again shortly
}

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/ai/kb/documents/9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } },
);

const { data } = await res.json();
data.document.status; // poll until 'ready'

import time

document_id = "9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11"

while True:
    doc = client.request("GET", f"/ai/kb/documents/{document_id}")
    if doc["data"]["document"]["status"] == "ready":
        break
    time.sleep(1)

import os
import time
import requests

while True:
    doc = requests.get(
        f"https://api.orbit.devotel.io/api/v1/ai/kb/documents/{document_id}",
        headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    ).json()
    if doc["data"]["document"]["status"] == "ready":
        break
    time.sleep(1)

Wait for status: "ready" — only then will queries hit the document. A staleness block always accompanies the document detail; list endpoints page back with { documents, next_cursor }.

3. Semantic search

POST /api/v1/ai/kb/search runs a raw semantic search across all ingested documents, returning the top matching chunks with their cosine/re-rank score, parent document, and chunk index.

cURL
Node.js SDK
Node.js (fetch)
Python SDK
Python (requests)

curl -X POST https://api.orbit.devotel.io/api/v1/ai/kb/search \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund within 90 days",
    "limit": 5
  }'

const { data } = await orbit.request<{
  query: string;
  results: Array<{
    id: string;
    score: number;
    content: string;
    documentId: string;
    documentName: string;
    chunkIndex: number;
    sourceType: string;
    sourceUrl: string | null;
  }>;
}>('POST', '/api/v1/ai/kb/search', {
  data: { query: 'refund within 90 days', limit: 5 },
});

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/search', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: 'refund within 90 days', limit: 5 }),
});

const { data } = await res.json();
data.results[0].score; // best-match relevance score

result = client.request("POST", "/ai/kb/search", json={
    "query": "refund within 90 days",
    "limit": 5,
})
for hit in result["data"]["results"]:
    print(hit["score"], hit["documentName"], hit["content"][:80])

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/ai/kb/search",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"query": "refund within 90 days", "limit": 5},
)
hits = res.json()["data"]["results"]

{
  "data": {
    "query": "refund within 90 days",
    "results": [
      {
        "id": "4d2e9f7a-1c2b-4d3e-9e8a-2f7c1c40b502",
        "score": 0.896,
        "content": "Full refund within 30 days; partial refund between 30 and 90 days.",
        "documentId": "9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11",
        "documentName": "Refund policy",
        "chunkIndex": 0,
        "sourceType": "markdown",
        "sourceUrl": null
      }
    ]
  }
}

4. Grounded answer

POST /api/v1/ai/kb/answers runs the knowledge base’s grounded QA loop — it retrieves the chunks above, then has the LLM synthesis an answer with citations and a confidence score. Call it (rather than raw search) from a customer-facing surface; the answer only counts as billable when the model is confident the source document covers the question.

cURL
Node.js SDK
Node.js (fetch)
Python SDK
Python (requests)

curl -X POST https://api.orbit.devotel.io/api/v1/ai/kb/answers \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Do we refund a purchase made 45 days ago?"
  }'

const { data } = await orbit.request<{
  answered: boolean;
  answer: string | null;
  confidence: number;
  citations: Array<{
    documentId: string;
    documentName: string;
    chunkIndex: number;
    score: number;
  }>;
}>('POST', '/api/v1/ai/kb/answers', {
  data: { question: 'Do we refund a purchase made 45 days ago?' },
});

if (data.answered) {
  console.log(data.answer, data.citations);
}

const res = await fetch('https://api.orbit.devotel.io/api/v1/ai/kb/answers', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ question: 'Do we refund a purchase made 45 days ago?' }),
});

const { data } = await res.json();
if (data.answered) console.log(data.answer, data.citations);

answer = client.request("POST", "/ai/kb/answers", json={
    "question": "Do we refund a purchase made 45 days ago?",
})
if answer["data"]["answered"]:
    print(answer["data"]["answer"])
    for citation in answer["data"]["citations"]:
        print("-", citation["documentName"], citation["score"])

import os
import requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/ai/kb/answers",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"question": "Do we refund a purchase made 45 days ago?"},
)
data = res.json()["data"]
if data["answered"]:
    print(data["answer"], data["citations"])

{
  "data": {
    "question": "Do we refund a purchase made 45 days ago?",
    "answered": true,
    "answer": "Yes, at a partial credit — a purchase made 45 days ago falls in the 30–90 day window under our refund policy.",
    "confidence": 0.83,
    "citations": [
      {
        "knowledgeBaseId": "kb_f1a4c2e0",
        "documentId": "9c3c8a01-2b4f-4c6b-9d1e-2f8b9f7e0a11",
        "documentName": "Refund policy",
        "sourceUrl": null,
        "chunkIndex": 0,
        "score": 0.896
      }
    ],
    "usage": {
      "meterSlug": "kb-answer",
      "unit": "resolution",
      "billable": true,
      "reference": "req_4091c7"
    }
  }
}

answered: false means the KB does not cover the question — the answer comes back null with low confidence. Scope the search with knowledge_base_ids, threshold, min_confidence, or language; gating by audience ACLs is always enforced.

API Reference

All Endpoints

AI API: translation, classification, and generation

AI API

Using the SDKs

Analysis & insight

Analyze

Analyze a message by ID

Classify intent

Summarize a conversation

Generation & rewriting

Suggest a reply

Generate content

Improve text

Translate

Compose a campaign

Optimize channel

Inference building blocks

Embeddings

Chat completions

Node / OpenAI SDK snippet

Knowledge base

Mini-cookbook: ingest → poll → search → answer

1. Ingest a document

2. Poll until ready

3. Semantic search

4. Grounded answer

See also

​AI API

​Using the SDKs

​Analysis & insight

​Analyze

​Analyze a message by ID

​Classify intent

​Summarize a conversation

​Generation & rewriting

​Suggest a reply

​Generate content

​Improve text

​Translate

​Compose a campaign

​Optimize channel

​Inference building blocks

​Embeddings

​Chat completions

​Node / OpenAI SDK snippet

​Knowledge base

​Mini-cookbook: ingest → poll → search → answer

​1. Ingest a document

​2. Poll until ready

​3. Semantic search

​4. Grounded answer

​See also

AI API

Using the SDKs

Analysis & insight

Analyze

Analyze a message by ID

Classify intent

Summarize a conversation

Generation & rewriting

Suggest a reply

Generate content

Improve text

Translate

Compose a campaign

Optimize channel

Inference building blocks

Embeddings

Chat completions

Node / OpenAI SDK snippet

Knowledge base

Mini-cookbook: ingest → poll → search → answer

1. Ingest a document

2. Poll until ready

3. Semantic search

4. Grounded answer

See also