Knowledge bases

Worked sequences

The twenty operations below are the full knowledge-base surface, but four round trips cover the document lifecycle most integrations actually run: upload a document, moderate it once the review queue picks it up, search the base to preview what an agent would retrieve, and diff two versions when the ground truth changed. Each sequence shows the body you send and the body the API returns. For the prose walkthrough of the whole lifecycle (create → load → attach → tune → maintain), read Build and Maintain an AI Knowledge Base. You need the knowledge:write scope (owner / admin / developer role) for uploads and moderation, and knowledge:read for search and diffs.

1. Upload a document

Binary files (PDF, DOCX, images — OCR-extracted) go up as multipart/form-data. Send the file bytes plus the name and type fields; the accepted document comes back in processing status because chunking and embedding run asynchronously. Poll GET /knowledge-bases/kb_abc123/documents until the status reaches ready.

curl -X POST "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_abc123/documents" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -F "file=@refund-policy.pdf" \
  -F "name=Refund Policy" \
  -F "type=pdf"

Node.js

import { readFileSync } from "node:fs";

const form = new FormData();
form.append("file", new Blob([readFileSync("refund-policy.pdf")]), "refund-policy.pdf");
form.append("name", "Refund Policy");
form.append("type", "pdf");

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

202

{
  "data": {
    "id": "doc_9a1c3e5b7d",
    "knowledge_base_id": "kb_abc123",
    "name": "Refund Policy",
    "type": "pdf",
    "status": "processing",
    "version": 1
  },
  "meta": {
    "request_id": "req_01H2T4W6YF8E9K3Z0VX5QAB7CJ",
    "timestamp": "2026-08-22T11:41:00.000Z"
  }
}

A 422 on a multipart upload means a missing name/type field or raw JSON carrying binary bytes — binary formats are multipart-only (inline text under the 10 MB cap may go up as a JSON content body instead; see the operation below).

2. Approve or reject a pending document

A document submitted for moderation (for example, a gap-cluster draft) sits pending until a reviewer acts. Approving flips its publish lifecycle to approved and starts deferred vector indexing so its chunks become retrievable; rejecting flips it to rejected and its chunks are never indexed. Optional notes are stored on the document for the submitter. Approve:

curl -X POST "https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_abc123/documents/doc_9a1c3e5b7d/approve" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Reviewed against the 2026-08 returns update." }'

200

{
  "data": {
    "id": "doc_9a1c3e5b7d",
    "knowledge_base_id": "kb_abc123",
    "name": "Refund Policy",
    "status": "approved",
    "notes": "Reviewed against the 2026-08 returns update."
  },
  "meta": {
    "request_id": "req_01H2T4X1PF3E9K0ZVX6QCB8DK",
    "timestamp": "2026-08-22T12:10:00.000Z"
  }
}

Reject:

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

200

{
  "data": {
    "id": "doc_9a1c3e5b7d",
    "knowledge_base_id": "kb_abc123",
    "name": "Refund Policy",
    "status": "rejected",
    "notes": "Superseded by the 2026-08 policy revision."
  },
  "meta": {
    "request_id": "req_01H2T4X4RG4F9L1ZVY7RDC9EM",
    "timestamp": "2026-08-22T12:12:00.000Z"
  }
}

Both actions are audit-logged — approval promotes a document to RAG ground-truth, which is an admin-class decision.

3. Search the knowledge base

This is the same retrieval an attached 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. Results are relevance-ranked chunks; when a per-base search config is active, recency, source weighting, and category filters apply before the list is truncated to limit (default 5).

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

200

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

An empty results array means no chunk cleared the raw similarity floor — check whether the document you expect is uploaded, approved, and indexed.

4. Diff two document versions

Every re-upload retains the prior copy as an immutable snapshot, so you can always ask what changed. GET /knowledge-bases/kb_abc123/documents/doc_9a1c3e5b7d/versions/diff takes from and to 1-based version numbers and returns added / removed / unchanged line counts plus unified-style hunk lines (+ added, - removed, context). truncated: true means the inputs were too large for a line-level diff. A 422 here means one of those versions isn’t in the retained lineage.

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

200

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

To restore an earlier version, POST /knowledge-bases/kb_abc123/documents/doc_9a1c3e5b7d/rollback with { "version": 1 } — non-destructive, since the current head is snapshotted first.

API Reference

All Endpoints

Worked sequences

1. Upload a document

2. Approve or reject a pending document

3. Search the knowledge base

4. Diff two document versions

​Worked sequences

​1. Upload a document

​2. Approve or reject a pending document

​3. Search the knowledge base

​4. Diff two document versions

Worked sequences

1. Upload a document

2. Approve or reject a pending document

3. Search the knowledge base

4. Diff two document versions