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.

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)

Worked session/memory + budget envelopes

1. Session memory round trip

2. Token-budget precheck

3. Errors-as-decision-table

​Worked session/memory + budget envelopes

​1. Session memory round trip

​2. Token-budget precheck

​3. Errors-as-decision-table

Worked session/memory + budget envelopes

1. Session memory round trip

2. Token-budget precheck

3. Errors-as-decision-table