Knowledgebases - Devotel Orbit Documentation

Worked knowledge-bases samples

The endpoint list below documents every operation’s parameters; this overlay walks a knowledge base the way an AI-agent integration actually uses it: list the knowledge bases → read their documents → upload one document → handle a stale or rejected-upload error. Success envelopes are { data, meta }, error envelopes { error, meta } — see How to read a worked sample. Run samples with a sandbox (dv_test_sk_*) key; documents the pipeline cannot validate (error indexing status) never enter the agent’s retrieval set, and you can re-queue them via the retry endpoint (see Knowledge bases). Every response carries meta.request_id and meta.timestamp. Quote the request id when you report a failing upload or a drifted document status.

1. List knowledge bases

GET /api/v1/knowledge-bases returns your workspace’s knowledge-base records — id, name, description, optional config, refresh cadence — with pagination. Use this to populate an AI-agent threading UI or pick the kb to which a document will be uploaded.

curl -X GET "https://api.orbit.devotel.io/api/v1/knowledge-bases" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "knowledge_bases": [
      {
        "id": "kb_8fb2d1b7c00c4ec9",
        "name": "Checkout troubleshooting",
        "description": "Returns/ refund rules / payment errors",
        "refresh_schedule": "weekly",
        "document_count": 3
      }
    ],
    "pagination": { "cursor": null, "has_more": false }
  },
  "meta": {
    "request_id": "req_kb_list",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Field notes a reader will hit on first integration:

refresh_schedule is manual (default) or one of the recurring cadence values the create endpoint accepts — the non-manual values drive recurring re-scrape of URL/RSS/Notion sources.
document_count is a read cache; update it with the list- read and use the documents endpoint below for per-file truth.

2. Read a knowledge base’s documents

GET /api/v1/knowledge-bases/{id}/documents returns the document ledger for one knowledge base — the rows an operator sees on the dashboard — and reports pre-ingest status for each file (pending, indexed, error, failed). A rejected upload tells you the analysis and moderation pipeline flagged it so you can act on the offending chunk.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "documents": [
      {
        "id": "doc_8fb2d1b7c00c4ec9",
        "name": "returns-policy.md",
        "type": "markdown",
        "status": "indexed",
        "version": 2,
        "created_at": "2026-08-01T12:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_documents",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}

3. Upload one document

POST /api/v1/knowledge-bases/{id}/documents ingests a text/markdown document into the knowledge base. The body is the uploadDocumentSchema — name, type (one of the allowed text-code/image formats via vision OCR), and content up to the router’s 10 MB text-upload cap. Files larger than that need the multipart endpoint the dashboard uses; an image upload flows through OCR transcription and chains into the same retrieval set.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "returns-policy.md",
  "type": "markdown",
  "content": "# Returns — 30-day window\n\n…"
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "returns-policy.md",
      type: "markdown",
      content: "# Returns — 30-day window\n\n…",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "doc_9e8d7c6b5a4f3021",
    "status": "pending",
    "version": 1
  },
  "meta": {
    "request_id": "req_kb_upload",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

4. Errors

Errors follow the { error, meta } envelope. The failure every uploader hits: 422 — validation. A name past 200 characters, unsupported type, or a body over the text-upload cap:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Document content too large (max 10MB). Split the file or upload via the multipart endpoint.",
    "status": 422
  },
  "meta": {
    "request_id": "req_kb_err",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}

5. Worked sequences — advanced lifecycle

Beyond upload and read-back, most AI-agent deployments run the full editorial loop: register an external source connector with POST /api/v1/knowledge-bases/{id}/connectors, kick off its initial sync with POST .../sync, watch drift and staleness, moderate the AI assistant’s proposed documents, roll a published version back after reading the lineage, and delete the documents the team has retired. The samples below keep the same identifiers end-to-end; pause on scheduled syncs by patching a connector with enabled: false.

5.1 Create a connector and start its initial sync

Register a connector that pulls one knowledge base’s documents from an external source. The body names the provider (one of notion, confluence, google_drive, sharepoint, zendesk) plus an optional scope, sync_schedule (default daily), and auto_refresh_on_drift. The returned id stays the handle for every later call.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connectors" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "notion",
  "display_name": "Returns & refunds space",
  "scope": { "space_keys": ["RETURNS"] },
  "sync_schedule": "hourly",
  "auto_refresh_on_drift": true
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connectors",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider: "notion",
      display_name: "Returns & refunds space",
      scope: { space_keys: ["RETURNS"] },
      sync_schedule: "hourly",
      auto_refresh_on_drift: true,
    }),
  },
);
console.log(await res.json());

201

{
  "data": {
    "id": "kbc_4b5e8a1f3c9d0e2f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "provider": "notion",
    "display_name": "Returns & refunds space",
    "scope": { "space_keys": ["RETURNS"] },
    "sync_schedule": "hourly",
    "auto_refresh_on_drift": true,
    "enabled": true,
    "created_at": "2026-08-26T12:04:00.000Z"
  },
  "meta": {
    "request_id": "req_kb_connector",
    "timestamp": "2026-08-26T12:04:01.000Z"
  }
}

Start the first pull right away instead of waiting for the schedule — the response is 202 because the sync runs asynchronously; poll GET /api/v1/knowledge-bases/{id}/connectors for the connector’s last-sync status.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connectors/kbc_4b5e8a1f3c9d0e2f/sync" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connectors/kbc_4b5e8a1f3c9d0e2f/sync",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

202

{
  "data": {
    "id": "kbc_4b5e8a1f3c9d0e2f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "status": "running",
    "last_sync_started_at": "2026-08-26T12:04:30.000Z"
  },
  "meta": {
    "request_id": "req_kb_connector_sync",
    "timestamp": "2026-08-26T12:04:30.000Z"
  }
}

5.2 Read the connector drift report and staleness

Once a sync has pulled, the connector drain worker hashes the live source and compares it against the cached content your agents ground on. Read the drift scorecard to decide whether to re-sync or to switch auto_refresh_on_drift on. Until the worker has checked a connector at least once, detection_active is false — the 0-drifted totals are not yet a passing signal.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connector-drift-report" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connector-drift-report",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "detection_active": true,
    "totals": {
      "connectors": 2,
      "in_sync": 1,
      "drifted": 1,
      "unknown": 0
    },
    "drifted": [
      {
        "id": "kbc_4b5e8a1f3c9d0e2f",
        "provider": "notion",
        "display_name": "Returns & refunds space",
        "enabled": true,
        "auto_refresh_on_drift": true,
        "drift_status": "drifted",
        "drift_detected_at": "2026-08-26T11:55:00.000Z",
        "last_drift_checked_at": "2026-08-26T11:55:00.000Z",
        "last_synced_at": "2026-08-26T10:00:00.000Z"
      }
    ],
    "connectors": [
      {
        "id": "kbc_4b5e8a1f3c9d0e2f",
        "provider": "notion",
        "display_name": "Returns & refunds space",
        "enabled": true,
        "auto_refresh_on_drift": true,
        "drift_status": "drifted",
        "drift_detected_at": "2026-08-26T11:55:00.000Z",
        "last_drift_checked_at": "2026-08-26T11:55:00.000Z",
        "last_synced_at": "2026-08-26T10:00:00.000Z"
      },
      {
        "id": "kbc_7e2a9d1c4f8b5e6a",
        "provider": "confluence",
        "display_name": "Checkout help",
        "enabled": true,
        "auto_refresh_on_drift": false,
        "drift_status": "in_sync",
        "drift_detected_at": null,
        "last_drift_checked_at": "2026-08-26T11:50:00.000Z",
        "last_synced_at": "2026-08-26T11:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_drift",
    "timestamp": "2026-08-26T12:05:00.000Z"
  }
}

Staleness is the document-side companion: it buckets each document into fresh, stale, or critical against your org’s threshold (90 days by default; override per call with ?default_threshold_days= or per document via its metadata) so an operator’s review queue catches the files an agent still quotes as current.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/staleness" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/staleness",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "totals": {
      "fresh": 2,
      "stale": 1,
      "critical": 0,
      "documents_scanned": 3,
      "never_verified": 1
    },
    "attention_required": [
      {
        "id": "doc_8fb2d1b7c00c4ec9",
        "name": "returns-policy.md",
        "status": "stale",
        "last_verified_at": "2026-05-15T09:00:00.000Z"
      }
    ],
    "default_threshold_days": 90,
    "scanned_at": "2026-08-26T12:05:30.000Z"
  },
  "meta": {
    "request_id": "req_kb_staleness",
    "timestamp": "2026-08-26T12:05:30.000Z"
  }
}

Both endpoints are read-only and deliberately avoid audit-log writes, so polling them from a dashboard or a scheduled job stays cheap.

5.3 Approve or reject the assistant’s proposed document

This moderation path runs in addition to the plain upload flow when your knowledge base enables require_publish_approval, or when an AI assistant (for example, a gap-cluster draft) proposes a document — either way the file arrives with status: pending and never enters retrieval until a reviewer acts. Approving flips the document to approved and starts the deferred vector indexing; rejecting flips it to rejected and its chunks are never indexed. Optional notes are stored on the document so the submitter gets actionable feedback. Approve:

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Reviewed against the current returns policy." }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      notes: "Reviewed against the current returns policy.",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "doc_3c9d0e2f4b5e8a1f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "Returns policy draft",
    "status": "approved"
  },
  "meta": {
    "request_id": "req_kb_approve",
    "timestamp": "2026-08-26T12:06:00.000Z"
  }
}

Reject the same way, or fix and re-upload before approving — a document that was never indexed stays out of agent retrieval either way:

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Superseded by the 2026-08 policy revision." }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      notes: "Superseded by the 2026-08 policy revision.",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "doc_3c9d0e2f4b5e8a1f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "Returns policy draft",
    "status": "rejected"
  },
  "meta": {
    "request_id": "req_kb_reject",
    "timestamp": "2026-08-26T12:06:10.000Z"
  }
}

Only documents pending review accept either decision — moderation status approved (or missing) returns 409 CONFLICT, and a publish-scan rejected document must be fixed and re-uploaded before it can be approved. Both actions are audit-logged.

5.4 Roll back a published version

Read the version lineage first, then the diff that tells you what the head changed, and roll back the published version if the retrieval set needs a previous copy. GET .../versions lists the immutable lineage — current head plus retained snapshots — without the heavy content blobs.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/versions" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/versions",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "document_id": "doc_8fb2d1b7c00c4ec9",
    "current": {
      "version": 2,
      "name": "returns-policy.md",
      "type": "markdown",
      "char_count": 1820,
      "is_current": true
    },
    "history": [
      {
        "version": 1,
        "name": "returns-policy.md",
        "type": "markdown",
        "char_count": 1740,
        "is_current": false
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_versions",
    "timestamp": "2026-08-26T12:07:00.000Z"
  }
}

Read the diff for the two versions you care about. A version outside the retained lineage returns 404; a version whose content was too large to retain returns 422 — rollback works only against retained snapshots.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/versions/diff?from=1&to=2" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/versions/diff?from=1&to=2",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "document_id": "doc_8fb2d1b7c00c4ec9",
    "from_version": 1,
    "to_version": 2,
    "added": 4,
    "removed": 2,
    "unchanged": 61,
    "truncated": false,
    "hunks": [
      "- Refunds take up to 10 business days.",
      "+ Returns are processed within 5–7 business days of approval.",
      "+ Enterprise contracts follow the contractual SLA instead."
    ]
  },
  "meta": {
    "request_id": "req_kb_diff",
    "timestamp": "2026-08-26T12:07:15.000Z"
  }
}

Then roll the document back. Non-destructive: the current head moves into the retained history first, so the operation is fully reversible.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/rollback" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1 }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/rollback",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ version: 1 }),
  },
);
console.log(await res.json());

202

{
  "data": {
    "id": "doc_8fb2d1b7c00c4ec9",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "returns-policy.md",
    "status": "processing",
    "version": 3
  },
  "meta": {
    "request_id": "req_kb_rollback",
    "timestamp": "2026-08-26T12:07:30.000Z"
  }
}

5.5 Search the knowledge base

The POST .../search hook is the same retrieval an attached AI agent’s search_knowledge tool runs, and the response shape exists so you can preview what an agent would ground on before a customer asks. The body is query (required, ≤ 1000 chars) plus optional limit (default 5, max 20); when a per-base search config is active, recency, source weighting, and category filters apply before the list is truncated. An empty results array means no chunk cleared the raw similarity floor — check whether the document you expect is uploaded, approved, and indexed.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/search" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "How long do annual-plan returns take?",
  "limit": 3
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/search",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "How long do annual-plan returns take?",
      limit: 3,
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "query": "How long do annual-plan returns take?",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "results": [
      {
        "content": "Annual-plan returns are processed within 5–7 business days of approval.",
        "score": 0.87,
        "documentId": "doc_8fb2d1b7c00c4ec9",
        "document_name": "returns-policy.md",
        "chunkIndex": 2
      },
      {
        "content": "Pro-rated refunds apply to annual subscriptions cancelled mid-term.",
        "score": 0.81,
        "documentId": "doc_8fb2d1b7c00c4ec9",
        "document_name": "returns-policy.md",
        "chunkIndex": 4
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_search",
    "timestamp": "2026-08-26T12:08:00.000Z"
  }
}

5.6 Delete a document and re-approve publication

A document stuck in moderation, or one the team retires, goes away in one call; anything that carries a public help-center article keeps its status through the same record — flip is_public on the publication endpoint once status is ready. Deleting returns 204 with no body.

curl -X DELETE \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f",
  {
    method: "DELETE",
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(res.status); // 204

204

(null body — the document and its chunks are removed from retrieval)

Then re-publish the surviving document the public help center should keep. The body is { is_public: boolean, slug?, summary? }; flipping public requires the document’s ingestion be done (status: ready), and the slug is unique across every published article in your workspace — a slug collision returns 409 CONFLICT.

curl -X PATCH \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/publication" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "is_public": true,
  "slug": "returns-policy",
  "summary": "How to return an order and when refunds land."
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/publication",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      is_public: true,
      slug: "returns-policy",
      summary: "How to return an order and when refunds land.",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "doc_8fb2d1b7c00c4ec9",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "returns-policy.md",
    "status": "ready",
    "is_public": true,
    "slug": "returns-policy",
    "summary": "How to return an order and when refunds land."
  },
  "meta": {
    "request_id": "req_kb_publication",
    "timestamp": "2026-08-26T12:09:00.000Z"
  }
}

A document deleted after approval had its chunks removed from the vector index — a re-upload restarts the moderation queue from pending.

Moderation & sync round-trips

The samples above walk one document through upload and retrieval; this section walks the round trips a review pipeline automates: decide a pending document, roll a published version back when an eval regresses, queue refreshes and syncs as jobs, and read the drift and retrieval previews that tell you why. Every body keeps the { data, meta } envelope (errors keep { error, meta }), and each response echoes enough state that your pipeline does not need a follow-up read to know what changed.

1. Approve a pending document

Send the reviewer’s rationale in notes; the 200 echoes the decision and the document’s status transition out of pending:

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Reviewed against the current returns policy." }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      notes: "Reviewed against the current returns policy.",
    }),
  },
);
console.log(await res.json());

import os, requests

headers = {
    "X-API-Key": os.environ["ORBIT_API_KEY"],
    "Content-Type": "application/json",
}
r = requests.post(
    "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve",
    headers=headers,
    json={"notes": "Reviewed against the current returns policy."},
)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"notes": "Reviewed against the current returns policy."}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { notes: 'Reviewed against the current returns policy.' }.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/approve');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'notes' => 'Reviewed against the current returns policy.',
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);

echo curl_exec($ch);

200

{
  "data": {
    "id": "doc_3c9d0e2f4b5e8a1f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "Returns policy draft",
    "status": "approved",
    "previous_status": "pending",
    "moderation": {
      "decision": "approved",
      "reviewer_note": "Reviewed against the current returns policy.",
      "decided_at": "2026-08-26T12:10:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_kb_mr_approve",
    "timestamp": "2026-08-26T12:10:00.000Z"
  }
}

A document that already carries a decision does not accept a second one. Re-posting approve (or reject) against it returns 409:

409

{
  "error": {
    "code": "CONFLICT",
    "message": "Document doc_3c9d0e2f4b5e8a1f is already approved. Only documents pending review accept a moderation decision.",
    "status": 409
  },
  "meta": {
    "request_id": "req_kb_mr_approve_conflict",
    "timestamp": "2026-08-26T12:10:05.000Z"
  }
}

2. Reject a pending document

The reject round trip mirrors approve: the same notes body, the same 409 once decided, and a 200 that echoes the transition to rejected so the submitter sees the rationale on the document:

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Superseded by the 2026-08 policy revision." }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      notes: "Superseded by the 2026-08 policy revision.",
    }),
  },
);
console.log(await res.json());

import os, requests

headers = {
    "X-API-Key": os.environ["ORBIT_API_KEY"],
    "Content-Type": "application/json",
}
r = requests.post(
    "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject",
    headers=headers,
    json={"notes": "Superseded by the 2026-08 policy revision."},
)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"notes": "Superseded by the 2026-08 policy revision."}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { notes: 'Superseded by the 2026-08 policy revision.' }.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_3c9d0e2f4b5e8a1f/reject');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'notes' => 'Superseded by the 2026-08 policy revision.',
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);

echo curl_exec($ch);

200

{
  "data": {
    "id": "doc_3c9d0e2f4b5e8a1f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "Returns policy draft",
    "status": "rejected",
    "previous_status": "pending",
    "moderation": {
      "decision": "rejected",
      "reviewer_note": "Superseded by the 2026-08 policy revision.",
      "decided_at": "2026-08-26T12:10:30.000Z"
    }
  },
  "meta": {
    "request_id": "req_kb_mr_reject",
    "timestamp": "2026-08-26T12:10:30.000Z"
  }
}

3. Roll back with version pointers

The rollback 202 names the restore explicitly: from_version is the retained snapshot you restore, to_version the head it replaces, and version the new head the restore creates. The replaced head is snapshotted into history first, so rolling forward again uses the same call.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/rollback" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1 }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/documents/doc_8fb2d1b7c00c4ec9/rollback",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ version: 1 }),
  },
);
console.log(await res.json());

202

{
  "data": {
    "id": "doc_8fb2d1b7c00c4ec9",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "returns-policy.md",
    "status": "processing",
    "version": 3,
    "from_version": 1,
    "to_version": 2
  },
  "meta": {
    "request_id": "req_kb_mr_rollback",
    "timestamp": "2026-08-26T12:11:00.000Z"
  }
}

4. Refresh and sync enqueue jobs

POST .../refresh and POST .../connectors/{connectorId}/sync both answer 202 with a job handle rather than blocking on the pull. Keep the job_id; the follow-up status read below echoes it.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/refresh" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/refresh",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

202

{
  "data": {
    "job_id": "kbjob_5d2c9a7e41b08f36",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "kind": "refresh",
    "status": "queued",
    "queued_at": "2026-08-26T12:11:30.000Z"
  },
  "meta": {
    "request_id": "req_kb_mr_refresh",
    "timestamp": "2026-08-26T12:11:30.000Z"
  }
}

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connectors/kbc_4b5e8a1f3c9d0e2f/sync" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connectors/kbc_4b5e8a1f3c9d0e2f/sync",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

202

{
  "data": {
    "job_id": "kbjob_8a4f1c6d29e73b50",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "connector_id": "kbc_4b5e8a1f3c9d0e2f",
    "kind": "sync",
    "status": "queued",
    "queued_at": "2026-08-26T12:11:45.000Z"
  },
  "meta": {
    "request_id": "req_kb_mr_sync",
    "timestamp": "2026-08-26T12:11:45.000Z"
  }
}

Follow up with GET /api/v1/knowledge-bases/{id}: the knowledge-base record carries the job’s terminal state, and last_refresh_at only moves when the pull succeeds. A sync job settles the same way on the connector record (GET .../connectors), where last_synced_at advances on success.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "kb_8fb2d1b7c00c4ec9",
    "name": "Checkout troubleshooting",
    "refresh_schedule": "weekly",
    "last_refresh_at": "2026-08-26T12:12:10.000Z",
    "last_refresh_job": {
      "job_id": "kbjob_5d2c9a7e41b08f36",
      "status": "succeeded",
      "finished_at": "2026-08-26T12:12:10.000Z"
    }
  },
  "meta": {
    "request_id": "req_kb_mr_status",
    "timestamp": "2026-08-26T12:12:20.000Z"
  }
}

5. Drift report entries per connector

The drift report’s per-connector entries list exactly which documents diverged since the last successful sync: added, removed, and changed carry document ids, and detected_at names the check that first saw the divergence. An in_sync connector returns empty arrays and a null detected_at.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connector-drift-report" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/connector-drift-report",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "connectors": [
      {
        "id": "kbc_4b5e8a1f3c9d0e2f",
        "provider": "notion",
        "display_name": "Returns & refunds space",
        "drift_status": "drifted",
        "detected_at": "2026-08-26T11:55:00.000Z",
        "documents": {
          "added": ["doc_9e8d7c6b5a4f3021"],
          "removed": [],
          "changed": ["doc_8fb2d1b7c00c4ec9"]
        }
      },
      {
        "id": "kbc_7e2a9d1c4f8b5e6a",
        "provider": "confluence",
        "display_name": "Checkout help",
        "drift_status": "in_sync",
        "detected_at": null,
        "documents": {
          "added": [],
          "removed": [],
          "changed": []
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_mr_drift",
    "timestamp": "2026-08-26T12:13:00.000Z"
  }
}

6. Search returns scored hits with citation spans

Each hit carries its similarity score plus citation_spans: the character offsets inside content the retriever actually matched, so you can underline the grounded passage in your own UI before a customer ever asks.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/search" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "How long do annual-plan returns take?",
  "limit": 3
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9/search",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "How long do annual-plan returns take?",
      limit: 3,
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "query": "How long do annual-plan returns take?",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "results": [
      {
        "content": "Annual-plan returns are processed within 5–7 business days of approval.",
        "score": 0.87,
        "documentId": "doc_8fb2d1b7c00c4ec9",
        "document_name": "returns-policy.md",
        "chunkIndex": 2,
        "citation_spans": [{ "start": 0, "end": 66 }]
      },
      {
        "content": "Pro-rated refunds apply to annual subscriptions cancelled mid-term.",
        "score": 0.81,
        "documentId": "doc_8fb2d1b7c00c4ec9",
        "document_name": "returns-policy.md",
        "chunkIndex": 4,
        "citation_spans": [{ "start": 27, "end": 63 }]
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_mr_search",
    "timestamp": "2026-08-26T12:14:00.000Z"
  }
}

An empty results array means no chunk cleared the similarity floor; check that the document you expect is uploaded, approved, and indexed before debugging the query.

7. Poll a reindex job until it settles

The refresh and sync kick-offs above answer 202 with a job_id; the poll then reads the owning record — GET /api/v1/knowledge-bases/{id} for a refresh, GET .../connectors for a sync. The knowledge-base record carries the job’s terminal state exactly as the Orby endpoints page’s Trigger an Orby knowledge-base reindex does for the operator docs index: the trigger answers scheduled, and the follow-up status read reports the run’s terminal state. Same status vocabulary — queued → succeeded with a finished timestamp — so one polling helper serves both surfaces:

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_8fb2d1b7c00c4ec9",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "kb_8fb2d1b7c00c4ec9",
    "name": "Checkout troubleshooting",
    "last_refresh_job": {
      "job_id": "kbjob_5d2c9a7e41b08f36",
      "kind": "refresh",
      "status": "succeeded",
      "queued_at": "2026-08-26T12:11:30.000Z",
      "finished_at": "2026-08-26T12:12:10.000Z"
    },
    "last_refresh_at": "2026-08-26T12:12:10.000Z"
  },
  "meta": {
    "request_id": "req_kb_mr_poll",
    "timestamp": "2026-08-26T12:12:30.000Z"
  }
}

last_refresh_at only moves when the pull succeeds; a job that ends failed leaves it at the previous value and puts the reason on last_refresh_job.error, mirroring how the Orby reindex read reports a failed run.

Per-operation response envelopes

The numbered sections above narrate the loops; this section gives every operation on this page its own response body, in page order, so each operation’s reference entry and its worked sample show the same envelope. Identifiers stay the ones used throughout this overlay — kb_8fb2d1b7c00c4ec9, doc_8fb2d1b7c00c4ec9, doc_9e8d7c6b5a4f3021, doc_3c9d0e2f4b5e8a1f, kbc_4b5e8a1f3c9d0e2f — and statuses stay pending → approved / rejected, processing → indexed / failed, jobs queued → succeeded. The operator-side copilot indexes the product docs the same way your agents index these bases: the Orby endpoints page’s Trigger an Orby knowledge-base reindex and its index-status read use the identical trigger-then-poll contract: the kick-off acknowledges the queued run, and the follow-up read carries the terminal status plus the finished timestamp. Where that page names operator-docs chunks, this page names your tenant’s knowledge bases; the envelopes below keep the same field names and status vocabulary so a pipeline written against one ports to the other.

`GET /api/v1/knowledge-bases`

200

{
  "data": {
    "knowledge_bases": [
      {
        "id": "kb_8fb2d1b7c00c4ec9",
        "name": "Checkout troubleshooting",
        "description": "Returns/ refund rules / payment errors",
        "refresh_schedule": "weekly",
        "document_count": 3
      }
    ],
    "pagination": { "cursor": null, "has_more": false }
  },
  "meta": {
    "request_id": "req_kb_op_list",
    "timestamp": "2026-08-26T12:20:00.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}`

200

{
  "data": {
    "id": "kb_8fb2d1b7c00c4ec9",
    "name": "Checkout troubleshooting",
    "description": "Returns/ refund rules / payment errors",
    "refresh_schedule": "weekly",
    "document_count": 3,
    "last_refresh_at": "2026-08-26T12:12:10.000Z",
    "last_refresh_job": {
      "job_id": "kbjob_5d2c9a7e41b08f36",
      "status": "succeeded",
      "finished_at": "2026-08-26T12:12:10.000Z"
    }
  },
  "meta": {
    "request_id": "req_kb_op_get",
    "timestamp": "2026-08-26T12:20:10.000Z"
  }
}

A knowledge base id from another workspace is invisible to yours and answers 404, the same envelope a deleted base returns:

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Knowledge base kb_0000000000000001 does not belong to this workspace.",
    "status": 404
  },
  "meta": {
    "request_id": "req_kb_op_get_foreign",
    "timestamp": "2026-08-26T12:20:15.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}/connector-drift-report`

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "detection_active": true,
    "totals": { "connectors": 2, "in_sync": 1, "drifted": 1, "unknown": 0 },
    "connectors": [
      {
        "id": "kbc_4b5e8a1f3c9d0e2f",
        "provider": "notion",
        "display_name": "Returns & refunds space",
        "drift_status": "drifted",
        "detected_at": "2026-08-26T11:55:00.000Z",
        "documents": {
          "added": ["doc_9e8d7c6b5a4f3021"],
          "removed": [],
          "changed": ["doc_8fb2d1b7c00c4ec9"]
        }
      },
      {
        "id": "kbc_7e2a9d1c4f8b5e6a",
        "provider": "confluence",
        "display_name": "Checkout help",
        "drift_status": "in_sync",
        "detected_at": null,
        "documents": { "added": [], "removed": [], "changed": [] }
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_op_drift",
    "timestamp": "2026-08-26T12:20:20.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}/connectors`

200

{
  "data": {
    "connectors": [
      {
        "id": "kbc_4b5e8a1f3c9d0e2f",
        "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
        "provider": "notion",
        "display_name": "Returns & refunds space",
        "sync_schedule": "hourly",
        "auto_refresh_on_drift": true,
        "enabled": true,
        "status": "running",
        "last_sync_started_at": "2026-08-26T12:04:30.000Z",
        "last_synced_at": "2026-08-26T10:00:00.000Z"
      },
      {
        "id": "kbc_7e2a9d1c4f8b5e6a",
        "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
        "provider": "confluence",
        "display_name": "Checkout help",
        "sync_schedule": "daily",
        "auto_refresh_on_drift": false,
        "enabled": true,
        "status": "idle",
        "last_sync_started_at": "2026-08-26T11:00:00.000Z",
        "last_synced_at": "2026-08-26T11:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_op_connectors",
    "timestamp": "2026-08-26T12:20:30.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}/documents`

200

{
  "data": {
    "documents": [
      {
        "id": "doc_9e8d7c6b5a4f3021",
        "name": "annual-plan-faq.md",
        "type": "markdown",
        "status": "processing",
        "version": 1,
        "created_at": "2026-08-26T12:02:00.000Z"
      },
      {
        "id": "doc_8fb2d1b7c00c4ec9",
        "name": "returns-policy.md",
        "type": "markdown",
        "status": "indexed",
        "version": 2,
        "created_at": "2026-08-01T12:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_op_documents",
    "timestamp": "2026-08-26T12:20:40.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}/documents/{docId}/versions`

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "document_id": "doc_8fb2d1b7c00c4ec9",
    "current": {
      "version": 2,
      "name": "returns-policy.md",
      "type": "markdown",
      "char_count": 1820,
      "is_current": true
    },
    "history": [
      {
        "version": 1,
        "name": "returns-policy.md",
        "type": "markdown",
        "char_count": 1740,
        "is_current": false
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_op_versions",
    "timestamp": "2026-08-26T12:20:50.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}/documents/{docId}/versions/diff`

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "document_id": "doc_8fb2d1b7c00c4ec9",
    "from_version": 1,
    "to_version": 2,
    "added": 4,
    "removed": 2,
    "unchanged": 61,
    "truncated": false,
    "hunks": [
      "- Refunds take up to 10 business days.",
      "+ Returns are processed within 5–7 business days of approval.",
      "+ Enterprise contracts follow the contractual SLA instead."
    ]
  },
  "meta": {
    "request_id": "req_kb_op_diff",
    "timestamp": "2026-08-26T12:21:00.000Z"
  }
}

`GET /api/v1/knowledge-bases/{id}/staleness`

200

{
  "data": {
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "totals": {
      "fresh": 2,
      "stale": 1,
      "critical": 0,
      "documents_scanned": 3,
      "never_verified": 1
    },
    "attention_required": [
      {
        "id": "doc_8fb2d1b7c00c4ec9",
        "name": "returns-policy.md",
        "status": "stale",
        "last_verified_at": "2026-05-15T09:00:00.000Z"
      }
    ],
    "default_threshold_days": 90,
    "scanned_at": "2026-08-26T12:21:10.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_staleness",
    "timestamp": "2026-08-26T12:21:10.000Z"
  }
}

`POST /api/v1/knowledge-bases`

200

{
  "data": {
    "id": "kb_8fb2d1b7c00c4ec9",
    "name": "Checkout troubleshooting",
    "description": "Returns/ refund rules / payment errors",
    "refresh_schedule": "manual",
    "document_count": 0,
    "created_at": "2026-08-01T11:00:00.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_create",
    "timestamp": "2026-08-26T12:21:20.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/connectors`

200

{
  "data": {
    "id": "kbc_4b5e8a1f3c9d0e2f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "provider": "notion",
    "display_name": "Returns & refunds space",
    "scope": { "space_keys": ["RETURNS"] },
    "sync_schedule": "hourly",
    "auto_refresh_on_drift": true,
    "enabled": true,
    "created_at": "2026-08-26T12:04:00.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_connector_create",
    "timestamp": "2026-08-26T12:21:30.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/connectors/{connectorId}/sync`

200

{
  "data": {
    "job_id": "kbjob_8a4f1c6d29e73b50",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "connector_id": "kbc_4b5e8a1f3c9d0e2f",
    "kind": "sync",
    "status": "queued",
    "queued_at": "2026-08-26T12:11:45.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_sync",
    "timestamp": "2026-08-26T12:21:40.000Z"
  }
}

Poll the connector list above until the connector’s status settles and last_synced_at advances — the same trigger-then-poll shape the Orby endpoints page shows for the operator docs reindex.

`POST /api/v1/knowledge-bases/{id}/documents`

200

{
  "data": {
    "id": "doc_9e8d7c6b5a4f3021",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "annual-plan-faq.md",
    "status": "pending",
    "version": 1
  },
  "meta": {
    "request_id": "req_kb_op_upload",
    "timestamp": "2026-08-26T12:21:50.000Z"
  }
}

The ingest pipeline accepts the text, code, and image formats the upload schema lists; anything else is rejected before indexing:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unsupported file type \"application/zip\". Upload one of the supported text, code, or image formats.",
    "status": 422
  },
  "meta": {
    "request_id": "req_kb_op_upload_unsupported",
    "timestamp": "2026-08-26T12:21:55.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/documents/{docId}/approve`

200

{
  "data": {
    "id": "doc_3c9d0e2f4b5e8a1f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "Returns policy draft",
    "status": "approved",
    "previous_status": "pending",
    "moderation": {
      "decision": "approved",
      "reviewer_note": "Reviewed against the current returns policy.",
      "decided_at": "2026-08-26T12:10:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_kb_op_approve",
    "timestamp": "2026-08-26T12:22:00.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/documents/{docId}/reject`

200

{
  "data": {
    "id": "doc_3c9d0e2f4b5e8a1f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "Returns policy draft",
    "status": "rejected",
    "previous_status": "pending",
    "moderation": {
      "decision": "rejected",
      "reviewer_note": "Superseded by the 2026-08 policy revision.",
      "decided_at": "2026-08-26T12:10:30.000Z"
    }
  },
  "meta": {
    "request_id": "req_kb_op_reject",
    "timestamp": "2026-08-26T12:22:10.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/documents/{docId}/rollback`

200

{
  "data": {
    "id": "doc_8fb2d1b7c00c4ec9",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "returns-policy.md",
    "status": "processing",
    "version": 3,
    "from_version": 1,
    "to_version": 2
  },
  "meta": {
    "request_id": "req_kb_op_rollback",
    "timestamp": "2026-08-26T12:22:20.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/refresh`

200

{
  "data": {
    "job_id": "kbjob_5d2c9a7e41b08f36",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "kind": "refresh",
    "status": "queued",
    "queued_at": "2026-08-26T12:11:30.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_refresh",
    "timestamp": "2026-08-26T12:22:30.000Z"
  }
}

`POST /api/v1/knowledge-bases/{id}/search`

200

{
  "data": {
    "query": "How long do annual-plan returns take?",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "results": [
      {
        "content": "Annual-plan returns are processed within 5–7 business days of approval.",
        "score": 0.87,
        "documentId": "doc_8fb2d1b7c00c4ec9",
        "document_name": "returns-policy.md",
        "chunkIndex": 2,
        "citation_spans": [{ "start": 0, "end": 66 }]
      },
      {
        "content": "Pro-rated refunds apply to annual subscriptions cancelled mid-term.",
        "score": 0.81,
        "documentId": "doc_8fb2d1b7c00c4ec9",
        "document_name": "returns-policy.md",
        "chunkIndex": 4,
        "citation_spans": [{ "start": 27, "end": 63 }]
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_op_search",
    "timestamp": "2026-08-26T12:22:40.000Z"
  }
}

`PUT /api/v1/knowledge-bases/{id}`

200

{
  "data": {
    "id": "kb_8fb2d1b7c00c4ec9",
    "name": "Checkout troubleshooting",
    "description": "Returns / refund rules / payment errors (2026-08 revision)",
    "refresh_schedule": "weekly",
    "document_count": 3,
    "updated_at": "2026-08-26T12:22:50.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_put",
    "timestamp": "2026-08-26T12:22:50.000Z"
  }
}

`PATCH /api/v1/knowledge-bases/{id}/connectors/{connectorId}`

200

{
  "data": {
    "id": "kbc_4b5e8a1f3c9d0e2f",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "provider": "notion",
    "display_name": "Returns & refunds space",
    "sync_schedule": "hourly",
    "auto_refresh_on_drift": true,
    "enabled": false,
    "updated_at": "2026-08-26T12:23:00.000Z"
  },
  "meta": {
    "request_id": "req_kb_op_connector_patch",
    "timestamp": "2026-08-26T12:23:00.000Z"
  }
}

Setting enabled: false pauses scheduled syncs; the connector keeps its lineage so re-enabling resumes from the last successful pull.

`PATCH /api/v1/knowledge-bases/{id}/documents/{docId}/publication`

200

{
  "data": {
    "id": "doc_8fb2d1b7c00c4ec9",
    "knowledge_base_id": "kb_8fb2d1b7c00c4ec9",
    "name": "returns-policy.md",
    "status": "ready",
    "is_public": true,
    "slug": "returns-policy",
    "summary": "How to return an order and when refunds land."
  },
  "meta": {
    "request_id": "req_kb_op_publication",
    "timestamp": "2026-08-26T12:23:10.000Z"
  }
}

Document status transitions

A document moves pending → processing → indexed when the analysis, moderation, and vector-indexing stages all pass; a stage that fails leaves the document at failed with the reason on the row, and the document stays out of retrieval until it is re-uploaded. The transitions read (GET /api/v1/knowledge-bases//documents, no backticks needed here — this section narrates rather than paints):

200

{
  "data": {
    "documents": [
      {
        "id": "doc_9e8d7c6b5a4f3021",
        "name": "annual-plan-faq.md",
        "type": "markdown",
        "status": "indexed",
        "version": 1,
        "indexed_at": "2026-08-26T12:16:00.000Z",
        "created_at": "2026-08-26T12:02:00.000Z"
      },
      {
        "id": "doc_5a6b7c8d9e0f1a2b",
        "name": "legacy-pricing.pdf",
        "type": "pdf",
        "status": "failed",
        "version": 1,
        "error": {
          "code": "INGEST_FAILED",
          "message": "OCR transcription produced no text layer; re-upload as markdown or a text-based PDF.",
          "failed_at": "2026-08-26T12:15:00.000Z"
        },
        "created_at": "2026-08-26T12:14:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_kb_op_transitions",
    "timestamp": "2026-08-26T12:23:20.000Z"
  }
}

A moderation verdict lands the same way: approve moves a pending document into the indexing queue (processing, then indexed), reject moves it to rejected, and both echo the decision in moderation as shown on the approve and reject operations above.

​Worked knowledge-bases samples

​1. List knowledge bases

​2. Read a knowledge base’s documents

​3. Upload one document

​4. Errors

​5. Worked sequences — advanced lifecycle

​5.1 Create a connector and start its initial sync

​5.2 Read the connector drift report and staleness

​5.3 Approve or reject the assistant’s proposed document

​5.4 Roll back a published version

​5.5 Search the knowledge base

​5.6 Delete a document and re-approve publication

​Moderation & sync round-trips

​1. Approve a pending document

​2. Reject a pending document

​3. Roll back with version pointers

​4. Refresh and sync enqueue jobs

​5. Drift report entries per connector

​6. Search returns scored hits with citation spans

​7. Poll a reindex job until it settles

​Per-operation response envelopes

​GET /api/v1/knowledge-bases

​GET /api/v1/knowledge-bases/{id}

​GET /api/v1/knowledge-bases/{id}/connector-drift-report

​GET /api/v1/knowledge-bases/{id}/connectors

​GET /api/v1/knowledge-bases/{id}/documents

​GET /api/v1/knowledge-bases/{id}/documents/{docId}/versions

​GET /api/v1/knowledge-bases/{id}/documents/{docId}/versions/diff

​GET /api/v1/knowledge-bases/{id}/staleness

​POST /api/v1/knowledge-bases

​POST /api/v1/knowledge-bases/{id}/connectors

​POST /api/v1/knowledge-bases/{id}/connectors/{connectorId}/sync

​POST /api/v1/knowledge-bases/{id}/documents

​POST /api/v1/knowledge-bases/{id}/documents/{docId}/approve

​POST /api/v1/knowledge-bases/{id}/documents/{docId}/reject

​POST /api/v1/knowledge-bases/{id}/documents/{docId}/rollback

​POST /api/v1/knowledge-bases/{id}/refresh

​POST /api/v1/knowledge-bases/{id}/search

​PUT /api/v1/knowledge-bases/{id}

​PATCH /api/v1/knowledge-bases/{id}/connectors/{connectorId}

​PATCH /api/v1/knowledge-bases/{id}/documents/{docId}/publication

​Document status transitions