AI Knowledge Base endpoints (ingest, refresh, search)

The AI API also includes an embedded, org-wide Knowledge Base — not shown in the auto-generated endpoint list below. Ingest documents by upload, URL, markdown, or bulk help-center import (POST /api/v1/ai/kb/documents, POST /api/v1/ai/kb/import/help-center), keep them fresh with a staleness scorecard and per-document verification (GET /api/v1/ai/kb/staleness, POST /api/v1/ai/kb/documents/{id}/verify), and query them with raw semantic search (POST /api/v1/ai/kb/search) or a grounded answer with citations (POST /api/v1/ai/kb/answers). See the full AI Knowledge Base reference. For a separately provisioned, per-knowledge-base store, use the Knowledge Bases API.

Response envelopes for the generated shells

The auto-generated shells below this section show each route’s schema, but their response examples are empty placeholders. The worked envelopes here show the exact { data, meta } body your integration receives, with real values, for every knowledge-source and AI-inference route on this page. Read them top to bottom as a pipeline: discover connectors, ingest documents, keep them fresh, then analyze, classify, generate, and search on top of them. All routes on this page require a signed-in operator seat (or an internal token); the knowledge-source write routes additionally require an owner or admin seat, and every /ai call that runs inference is metered against your workspace’s credit wallet.

1. List knowledge connectors

GET /knowledge/connectors

Discover the source connectors the knowledge base can ingest from. status is live for connectors you can register today and catalogued for sources on the roadmap; auth_required tells you whether registering one needs an OAuth grant or just a public subdomain.

{
  "data": {
    "connectors": [
      {
        "id": "zendesk_guide",
        "provider": "zendesk_guide",
        "name": "Zendesk Guide",
        "status": "live",
        "auth_required": false,
        "description": "Enumerates published help-center articles and ingests each one as a URL-sourced document."
      },
      {
        "id": "confluence",
        "provider": "confluence",
        "name": "Confluence",
        "status": "catalogued",
        "auth_required": true,
        "description": "Space-scoped page sync (on the roadmap)."
      }
    ],
    "total": 2
  },
  "meta": {
    "request_id": "req_kbconn_list",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

2. Get one knowledge connector

GET /knowledge/connectors/{id}

Fetch a single connector by the id values from the list above, including the configuration fields the import endpoint accepts for it.

{
  "data": {
    "connector": {
      "id": "zendesk_guide",
      "provider": "zendesk_guide",
      "name": "Zendesk Guide",
      "status": "live",
      "auth_required": false,
      "config": {
        "subdomain": "acme",
        "locale": "en-us",
        "max_articles": 500
      }
    }
  },
  "meta": {
    "request_id": "req_kbconn_get",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An unknown connector id returns 404 NOT_FOUND — branch on it when you cache the catalog client-side.

3. List knowledge documents

GET /knowledge/documents

Every document in the org-wide knowledge base, with the ingest status you poll after a upload, import, or reindex: pending while the ingest worker chunks and embeds it, indexed once it is retrievable, error when ingestion failed.

{
  "data": {
    "documents": [
      {
        "id": "kb_doc_5e8a2c4f",
        "name": "Refund policy",
        "source_type": "url",
        "source_url": "https://help.acme.example/hc/en-us/articles/101",
        "status": "indexed",
        "chunks": 14,
        "created_at": "2026-07-12T09:30:00.000Z",
        "last_indexed_at": "2026-07-12T09:31:42.000Z"
      },
      {
        "id": "kb_doc_9b1d7e3a",
        "name": "Onboarding guide.pdf",
        "source_type": "upload",
        "status": "pending",
        "chunks": 0,
        "created_at": "2026-08-01T11:58:00.000Z",
        "last_indexed_at": null
      }
    ],
    "total": 2
  },
  "meta": {
    "request_id": "req_kbdoc_list",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

4. Get one knowledge document

GET /knowledge/documents/{id}

The full record for a single document, including its ingest status and chunk count. An unknown id returns 404 NOT_FOUND.

{
  "data": {
    "document": {
      "id": "kb_doc_5e8a2c4f",
      "name": "Refund policy",
      "source_type": "url",
      "source_url": "https://help.acme.example/hc/en-us/articles/101",
      "status": "indexed",
      "chunks": 14,
      "created_at": "2026-07-12T09:30:00.000Z",
      "last_indexed_at": "2026-07-12T09:31:42.000Z"
    }
  },
  "meta": {
    "request_id": "req_kbdoc_get",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

5. Run the staleness scan

GET /knowledge/stale-scan

Score the whole knowledge base for freshness in one read. score is 0–1 (higher is fresher), and each document carries a fresh / aging / stale classification plus the days since its source changed. Poll it on a schedule and reindex or delete what goes stale.

{
  "data": {
    "scanned_at": "2026-08-01T12:00:00.000Z",
    "score": 0.82,
    "total": 58,
    "stale_count": 6,
    "documents": [
      {
        "id": "kb_doc_5e8a2c4f",
        "name": "Refund policy",
        "classification": "fresh",
        "days_since_update": 4
      },
      {
        "id": "kb_doc_2c6f9a1d",
        "name": "2025 pricing FAQ",
        "classification": "stale",
        "days_since_update": 212
      }
    ]
  },
  "meta": {
    "request_id": "req_kbstale",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

6. Analyze text

POST /ai/analyze

Run one piece of text through sentiment, intent, language, and topic detection in a single call. Send { "text": "..." } (1–10 000 characters); the reply carries all four dimensions on data. Request

{
  "text": "I love the new dashboard but my invoice looks wrong."
}

{
  "data": {
    "sentiment": "mixed",
    "intent": "billing",
    "language": "en",
    "topics": ["billing", "dashboard"]
  },
  "meta": {
    "request_id": "req_ai_analyze",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An empty text fails validation before any inference runs and is never charged:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Text is required"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

7. Analyze a message and persist the result

POST /ai/analyze/persist

Analyze one stored message by id and write the result back onto the message record, so the Messages and Interactions surfaces show the same analysis you received here. The reply carries the message_id and the analysis object exactly as stored. Request

{
  "message_id": "msg_3d7c1b9e"
}

{
  "data": {
    "message_id": "msg_3d7c1b9e",
    "analysis": {
      "sentiment": "negative",
      "intent": "complaint",
      "language": "en",
      "topics": ["delivery"]
    }
  },
  "meta": {
    "request_id": "req_ai_analyze_persist",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

A message id that does not exist in your workspace returns 404 NOT_FOUND:

404

{
  "error": {
    "code": "NOT_FOUND",
    "status": 404,
    "message": "Message msg_00000000 not found"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

8. OpenAI-compatible chat completion

POST /ai/chat/completions

Point any OpenAI SDK at your /api/v1/ai base URL and it will call this route. The request body is the standard OpenAI subset (messages, optional model, temperature, max_tokens, response_format), and the reply is a faithful chat.completion object wrapped in the Orbit envelope: choices[0].message.content holds the text, usage the token counts to add to your accounting. Inference runs on Orbit’s managed model fleet and is billed to the same wallet as your comms; a model you send is echoed back as requested. Request

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "You are a concise support assistant." },
    { "role": "user", "content": "How do I reset my password?" }
  ]
}

{
  "data": {
    "id": "chatcmpl-req_ai_chat_001",
    "object": "chat.completion",
    "created": 1785931200,
    "model": "gpt-4o-mini",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Open Settings, choose Security, then select Reset password."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 64,
      "completion_tokens": 21,
      "total_tokens": 85
    }
  },
  "meta": {
    "request_id": "req_ai_chat_001",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An empty messages array is rejected before inference:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "At least one message is required"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

9. Classify intent

POST /ai/classify-intent

Classify the intent behind a conversation, not a single string: send { "conversation_id": "..." } and the most recent messages are read for you. The reply names the primary intent category with a 0–1 confidence and one sentence of reasoning you can log or show to the operator. Request

{
  "conversation_id": "conv_8b2c4d6e1f"
}

{
  "data": {
    "intent": "billing",
    "confidence": 0.87,
    "reasoning": "The customer asks twice about a charge on the latest invoice."
  },
  "meta": {
    "request_id": "req_ai_intent",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

A missing conversation_id fails validation with 422 VALIDATION_ERROR (“Conversation ID is required”) and is not charged.

10. Generate a campaign blueprint

POST /ai/campaign-blueprint

Describe a campaign goal in plain English and receive a draft blueprint: a name and description, one message body per requested channel, a journey graph (nodes and edges in the visual builder’s shape) ready to load into the canvas, and an audience hint. The result is a draft — review it and launch it yourself. Set audience_segment to start the journey with a score check so only contacts in that bucket receive it. Request

{
  "goal": "Win back customers who have not purchased in 90 days with a 15% offer.",
  "audience_segment": "at_risk",
  "channels": ["sms", "email"],
  "tone": "friendly",
  "brand_name": "Acme"
}

{
  "data": {
    "name": "We miss you — 15% inside",
    "description": "Two-touch win-back for customers quiet for 90+ days.",
    "messages": [
      {
        "channel": "sms",
        "body": "Acme: it's been a while. Here's 15% off your next order, on us. Reply STOP to opt out."
      },
      {
        "channel": "email",
        "subject": "A little thank-you for coming back",
        "body": "Hi there, we noticed it's been a while..."
      }
    ],
    "journey": {
      "nodes": [
        { "id": "trigger", "type": "trigger" },
        { "id": "score_check", "type": "segment" },
        { "id": "send_sms", "type": "send" }
      ],
      "edges": [
        { "source": "trigger", "target": "score_check" },
        { "source": "score_check", "target": "send_sms" }
      ]
    },
    "audience": { "segment_label": "at_risk" }
  },
  "meta": {
    "request_id": "req_ai_blueprint",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

A goal shorter than a sentence is rejected so the model never drafts from a fragment:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Describe the goal in at least a sentence"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

11. Generate dashboard insights

POST /ai/dashboard-insights

Send your current dashboard statistics and receive two to three actionable insights. The result is cached server-side for one hour, so repeated calls inside the hour return the same insights with cached: true. This endpoint is best-effort by design: if inference is unavailable it degrades to an empty insights array with cached: false rather than erroring your dashboard.

{
  "data": {
    "insights": [
      "SMS delivery dipped 4pp on Tuesdays; the drop concentrates in one sender pool.",
      "WhatsApp open rates are 2.1x SMS for re-engagement flows this month."
    ],
    "cached": false
  },
  "meta": {
    "request_id": "req_ai_insights",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

12. Create embeddings

POST /ai/embeddings

Turn one string, or up to 96 strings, into embedding vectors using the same model Orbit uses for its own retrieval. The payload mirrors OpenAI’s /embeddings wire shape (object: "list", one embedding entry per input, a usage token count), so existing embedding SDKs drop in unchanged. Spend is billed to your wallet per token. Request

{
  "input": ["Prefers SMS over calls", "Contract renews 2026-10-01"]
}

{
  "data": {
    "object": "list",
    "model": "text-embedding-3-small",
    "data": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": [0.0132, -0.0208, 0.0041]
      },
      {
        "object": "embedding",
        "index": 1,
        "embedding": [0.0097, 0.0164, -0.0119]
      }
    ],
    "usage": {
      "prompt_tokens": 18,
      "total_tokens": 18
    }
  },
  "meta": {
    "request_id": "req_ai_embed",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Vectors are truncated above for readability; each real entry carries the model’s full dimension. A batch above the 96-input ceiling is rejected as oversized before any spend:

413

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "status": 413,
    "message": "At most 96 inputs per request"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

13. Generate content for a channel

POST /ai/content-for-channel

Draft message copy from a prompt and tone, tuned for the target channel (sms, whatsapp, email, voice). Use it anywhere you compose a send: the campaign wizard, send dialogs, or your own tooling. Request

{
  "prompt": "Announce our new loyalty tier launching next Monday.",
  "tone": "friendly",
  "channel": "sms"
}

{
  "data": {
    "content": "Big news: our new loyalty tier launches Monday. Early members earn double points all month.",
    "tone": "friendly",
    "channel": "sms"
  },
  "meta": {
    "request_id": "req_ai_content",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An empty prompt returns 422 VALIDATION_ERROR (“Prompt is required”) and is not charged.

14. Rewrite text

POST /ai/rewrite-text

Rewrite existing text with a named action: improve, shorter, longer, change_tone, fix_grammar, or rephrase. fix_grammar corrects grammar and spelling only and never rephrases; rephrase keeps meaning and length. This is the endpoint behind the AI-assist button in send dialogs. Request

{
  "text": "Your order has shipped and will arrive tommorow.",
  "action": "fix_grammar"
}

{
  "data": {
    "text": "Your order has shipped and will arrive tomorrow.",
    "action": "fix_grammar"
  },
  "meta": {
    "request_id": "req_ai_rewrite",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An empty text returns 422 VALIDATION_ERROR (“Text is required”).

15. Ask the knowledge base

POST /ai/ask

Ask a question in plain language and receive a grounded answer drawn from your indexed documents, with the citations list your UI should show alongside it. confidence tells you when to fall back to a human: below your threshold, route the conversation to an operator instead of surfacing the answer. Request

{
  "question": "What is the refund window for annual plans?"
}

{
  "data": {
    "answer": "Annual plans can be refunded in full within 30 days of purchase; after that, refunds are prorated by month.",
    "confidence": 0.91,
    "citations": [
      {
        "document_id": "kb_doc_5e8a2c4f",
        "title": "Refund policy",
        "snippet": "Annual plans are eligible for a full refund within 30 days..."
      }
    ]
  },
  "meta": {
    "request_id": "req_ai_ask",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An empty question returns 422 VALIDATION_ERROR before the search and answer steps run.

16. Ingest a document

POST /knowledge/documents

Add one document by upload, URL, or inline markdown. Indexing is asynchronous: the create returns immediately with the document record in pending status, and you poll GET /knowledge/documents/{id} until it reads indexed (or error). Requires an owner or admin seat.

{
  "data": {
    "document": {
      "id": "kb_doc_9b1d7e3a",
      "name": "Onboarding guide.pdf",
      "source_type": "upload",
      "status": "pending",
      "chunks": 0,
      "created_at": "2026-08-01T11:58:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_kbdoc_create",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Requests without a valid credential, or from a seat below owner/admin, are refused before anything is stored:

401

{
  "error": {
    "code": "UNAUTHORIZED",
    "status": 401,
    "message": "Valid credentials with knowledge write access are required."
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

17. Reindex a document

POST /knowledge/documents/{id}/reindex

Re-queue a document for chunking and embedding. Use it after a failed ingest (status: "error") or after the source of a URL document changed. Like the create, it returns 202 immediately and the document transitions pending → indexed (or back to error); poll the document record for the outcome.

{
  "data": {
    "document": {
      "id": "kb_doc_9b1d7e3a",
      "status": "pending"
    }
  },
  "meta": {
    "request_id": "req_kbdoc_reindex",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An unknown document id returns 404 NOT_FOUND.

18. Verify a document

POST /knowledge/documents/{id}/verify

Run a verification pass over one indexed document: whether its source still resolves, whether its content still matches the indexed chunks, and whether it remains retrievable in search. verified: true means all checks passed; otherwise issues names each failed check so you know what to fix before reindexing.

{
  "data": {
    "document_id": "kb_doc_5e8a2c4f",
    "verified": true,
    "checked_at": "2026-08-01T12:00:00.000Z",
    "issues": []
  },
  "meta": {
    "request_id": "req_kbdoc_verify",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

An unknown document id returns 404 NOT_FOUND.

19. Import a help center

POST /knowledge/import/help-center

Seed the knowledge base from an existing help center in one call. Send the provider (zendesk_guide today), your subdomain, the help-center locale, and an optional max_articles ceiling. Every published article is queued as a URL-sourced document through the standard ingest pipeline, so queued tells you how many documents to expect and truncated: true means the help center holds more articles than your ceiling; raise max_articles and re-run to capture the rest. Drafts are skipped. Request

{
  "provider": "zendesk_guide",
  "subdomain": "acme",
  "locale": "en-us",
  "max_articles": 500
}

{
  "data": {
    "queued": 42,
    "truncated": false,
    "provider": "zendesk_guide"
  },
  "meta": {
    "request_id": "req_kbimport",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

A subdomain or locale that does not resolve to a public help center returns 404 NOT_FOUND; a private or rate-limited help center surfaces as 502 BAD_GATEWAY:

404

{
  "error": {
    "code": "NOT_FOUND",
    "status": 404,
    "message": "Help center not found. Verify the subdomain and locale (for example en-us)."
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

20. Search the knowledge base

GET /knowledge/search

Raw semantic search over the indexed documents, scored 0–1. Use it when you want the matching passages themselves; use POST /ai/ask when you want a single grounded answer composed from them.

{
  "data": {
    "query": "refund window annual plans",
    "results": [
      {
        "document_id": "kb_doc_5e8a2c4f",
        "title": "Refund policy",
        "snippet": "Annual plans are eligible for a full refund within 30 days of purchase.",
        "score": 0.88
      },
      {
        "document_id": "kb_doc_7a4e2b8c",
        "title": "Billing FAQ",
        "snippet": "Prorated refunds apply after the first 30 days.",
        "score": 0.71
      }
    ],
    "total": 2
  },
  "meta": {
    "request_id": "req_kbsearch",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The knowledge-source write routes (POST /knowledge/documents, reindex, verify, and help-center import) all enforce the same owner/admin seat requirement as section 16 shows: a request without a valid credential gets 401, and a signed-in seat below owner/admin gets 403. Every failure on this page uses the shared { error, meta } envelope from the errors table below, so one retry/reframe/escalate switch covers all of them.

Worked session/memory + budget envelopes

The auto-generated response examples below show the OpenAPI schema shape. The worked envelopes in this section show the exact fields your integration sees, with real values, across the three AI chains the reference below only half-covers: the per-contact session-memory read/write pair, the per-agent token-budget precheck, and the chat response the whole flow ends in. Together with the worked agent samples they give you a body you can branch on for every call an agent build makes first. Both the memory round trip and the budget precheck are tenant-owned controls: memory facts are scoped to one contact (and deleted with the contact’s GDPR erasure), and the token budget is a per-agent cap your workspace sets. The session-memory pair has its four statuses — 201 write, 200 read, 409 opt-out or per-contact fact cap, 422 validation.

1. Session memory round trip

Teach the agent a fact about a contact, then read the same contact’s facts back. The write returns 201 with the stored item; the read returns the newest facts with PII in the fact bodies masked unless your role is in the unmask allowlist and you pass ?reveal=true. When the contact has opted out of memory the write returns 409 MEMORY_DISABLED_FOR_CONTACT and the read returns an empty list with memory_enabled: false.

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

Manual teach. contact_id and fact are required; source is manual (default) or conversation, and importance (0–1) overrides the default 0.9 for manual teaches. The fact body is sanitised, capped to your tenant’s content limit, and stored with an embedding so the agent can retrieve it in later turns. Request

{
  "contact_id": "ctt_4f2a9c1e",
  "fact": "Prefers SMS over calls; contract renews 2026-10-01.",
  "source": "manual",
  "importance": 0.9
}

{
  "data": {
    "item": {
      "id": "memory_7b2d4f6a",
      "tenantId": "tnt_9c1e3a5b",
      "contactId": "ctt_4f2a9c1e",
      "agentId": "agt_7e3b9c1f",
      "memoryType": "fact",
      "content": "Prefers SMS over calls; contract renews 2026-10-01.",
      "importance": 0.9,
      "createdAt": "2026-08-01T12:00:00.000Z",
      "expiresAt": "2026-10-30T12:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_mem_teach",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

GET /api/v1/agents/{agentId}/memory?contact_id=ctt_4f2a9c1e

Read back the same contact’s facts. By default only fact-type entries are returned and phone/email tokens in the bodies are PII-masked; owner, admin, and developer roles can pass reveal=true to unmask (each reveal is audit-logged). A contact that has opted out returns an empty items list with memory_enabled: false.

{
  "data": {
    "items": [
      {
        "id": "memory_7b2d4f6a",
        "tenantId": "tnt_9c1e3a5b",
        "contactId": "ctt_4f2a9c1e",
        "agentId": "agt_7e3b9c1f",
        "memoryType": "fact",
        "content": "Prefers SMS over calls; contract renews 2026-10-01.",
        "importance": 0.9,
        "createdAt": "2026-08-01T12:00:00.000Z",
        "expiresAt": "2026-10-30T12:00:00.000Z"
      }
    ],
    "memory_enabled": true,
    "agent_id": "agt_7e3b9c1f",
    "contact_id": "ctt_4f2a9c1e",
    "facts_only": true
  },
  "meta": {
    "request_id": "req_mem_read",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The 409 the write returns when the contact has opted out — branch on this before you surface “teach the agent” in your UI:

409

{
  "error": {
    "code": "MEMORY_DISABLED_FOR_CONTACT",
    "status": 409,
    "message": "This contact has opted out of memory storage (memory_enabled = false)."
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

2. Token-budget precheck

Evaluate an action against your agent’s governance policies before the send, so a long turn never starts when it would be denied. Pass the intended model, the tool id (if the action invokes a tool), and the tokens the agent has already consumed this UTC month. The response merges every enabled policy that applies to the agent and returns a single allow/deny verdict with the effective caps it resolved — the monthly token budget is the strictest (minimum) across applying policies, and the model allowlist is the intersection. Gate on allowed: true/false; when the gate denies, reason is one of model_not_allowed, budget_exceeded, or sod_approval_required. Both fields you need to gate the send are on the envelope below.

GET /api/v1/agents/governance-internal/resolve?agent_id=agt_7e3b9c1f&model=claude-sonnet-4-6&monthly_tokens_used=84129

{
  "data": {
    "agent_id": "agt_7e3b9c1f",
    "applies": true,
    "allowed": true,
    "reason": "ok",
    "effective": {
      "applies": true,
      "policy_ids": ["gov_2b4d6f8a"],
      "prompt_guardrail": {
        "pii_redaction": true,
        "prompt_injection": true
      },
      "monthly_token_budget": 250000,
      "model_allowlist": ["claude-sonnet-4-6", "claude-haiku-4-5"],
      "sod_required": false,
      "sod_tools": []
    }
  },
  "meta": {
    "request_id": "req_gov_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

When the same call with monthly_tokens_used=250000 (already at the budget) the verdict flips — gate on it before you send:

200

{
  "data": {
    "agent_id": "agt_7e3b9c1f",
    "applies": true,
    "allowed": false,
    "reason": "budget_exceeded",
    "monthly_tokens_used": 250000
  },
  "meta": {
    "request_id": "req_gov_deny",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Once the precheck clears, the turn itself is the chat call — the response carries the token split you add to your own usage accounting:

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

200

{
  "conversationId": "conv_8b2c4d6e1f",
  "response": "Open Settings > Security, then choose Reset password.",
  "tokens_used": 412,
  "prompt_tokens": 301,
  "completion_tokens": 111,
  "conversation_persisted": true
}

3. Errors-as-decision-table

Every /ai and /agents failure returns the same { error, meta } envelope. The error.code and status tell you which of the three decisions to take; don’t treat 4xx as one class.

Decision	Status + code	What it means	Response
Retry	`429 RATE_LIMITED` with `error.retry_after` (and a `Retry-After` header)	The AI rate bucket is exhausted for the window.	Wait `error.retry_after` seconds, then retry the identical request.
Retry	`502 BILLING_PROVIDER_ERROR`	Credits could not be debited for this call (a transient wallet/ledger hiccup) — nothing was charged.	Back off and retry; the request is safe to replay.
Retry	`503 SERVICE_UNAVAILABLE`	The upstream AI provider is unavailable.	Back off and retry; the platform marks it self-healing.
Reframe	`422 VALIDATION_ERROR` with `error.details`	The body/query failed schema validation.	Fix the named field and resend — retrying the same body will never succeed.
Reframe	`402 INSUFFICIENT_BALANCE`	Your wallet is out of credits for this metered AI call.	Top up, then resend.
Reframe	`409 MEMORY_DISABLED_FOR_CONTACT` / `409 MEMORY_FACTS_CAP_EXCEEDED`	The memory write is blocked by consent (opt-out) or the per-contact fact cap.	Respect the opt-out (never retry); on the cap, forget one fact before teaching another.
Escalate	`500 CREATE_FAILED` / `DELETE_FAILED`	The memory store rejected the write.	Retry once; if it persists, escalate with `meta.request_id`.

429

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 17 seconds.",
    "status": 429,
    "retry_after": 17
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
  }
}

Retry buckets (429, 502, 503) are the only safe replay: they mean nothing was committed, so the same request can be resent after the wait. Reframe statuses (402, 409, 422) will fail identically every time until you change the request — and 409 MEMORY_DISABLED_FOR_CONTACT specifically means stop, because the contact revoked consent.

API Reference

All Endpoints

AI Knowledge Base endpoints (ingest, refresh, search)

Response envelopes for the generated shells

1. List knowledge connectors

2. Get one knowledge connector

3. List knowledge documents

4. Get one knowledge document

5. Run the staleness scan

6. Analyze text

7. Analyze a message and persist the result

8. OpenAI-compatible chat completion

9. Classify intent

10. Generate a campaign blueprint

11. Generate dashboard insights

12. Create embeddings

13. Generate content for a channel

14. Rewrite text

15. Ask the knowledge base

16. Ingest a document

17. Reindex a document

18. Verify a document

19. Import a help center

20. Search the knowledge base

Worked session/memory + budget envelopes

1. Session memory round trip

2. Token-budget precheck

3. Errors-as-decision-table

​Response envelopes for the generated shells

​1. List knowledge connectors

​2. Get one knowledge connector

​3. List knowledge documents

​4. Get one knowledge document

​5. Run the staleness scan

​6. Analyze text

​7. Analyze a message and persist the result

​8. OpenAI-compatible chat completion

​9. Classify intent

​10. Generate a campaign blueprint

​11. Generate dashboard insights

​12. Create embeddings

​13. Generate content for a channel

​14. Rewrite text

​15. Ask the knowledge base

​16. Ingest a document

​17. Reindex a document

​18. Verify a document

​19. Import a help center

​20. Search the knowledge base

​Worked session/memory + budget envelopes

​1. Session memory round trip

​2. Token-budget precheck

​3. Errors-as-decision-table

Response envelopes for the generated shells

1. List knowledge connectors

2. Get one knowledge connector

3. List knowledge documents

4. Get one knowledge document

5. Run the staleness scan

6. Analyze text

7. Analyze a message and persist the result

8. OpenAI-compatible chat completion

9. Classify intent

10. Generate a campaign blueprint

11. Generate dashboard insights

12. Create embeddings

13. Generate content for a channel

14. Rewrite text

15. Ask the knowledge base

16. Ingest a document

17. Reindex a document

18. Verify a document

19. Import a help center

20. Search the knowledge base

Worked session/memory + budget envelopes

1. Session memory round trip

2. Token-budget precheck

3. Errors-as-decision-table