Knowledge Bases API

Knowledge Bases endpoints exposed by the Devotel CPaaS API Base path: /api/v1/knowledge-bases Endpoint count: 3

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.

Get knowledge-base search config

GET /api/v1/knowledge-bases/{id}/search-config

Read a knowledge base’s retrieval re-rank / relevance-boost config — recency boost, per-source weights, category include/exclude, and the minimum-score threshold that govern which chunks ground every agent answer for this KB. A KB that has never been tuned reads back as the neutral default (every field a no-op, identical to legacy raw-similarity ordering). Read-only; requires the knowledge:read scope.

string

required

Knowledge base ID (kb_…).

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

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

Node.js

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

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

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

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


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

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "min_score": 0,
    "recency_boost": 0,
    "recency_half_life_days": 0,
    "source_weights": {},
    "include_categories": [
      "string"
    ],
    "exclude_categories": [
      "string"
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Retry document indexing

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

Re-queue a failed knowledge-base document for indexing. Use when a document upload reported an error indexing status and you fixed the underlying cause — the document’s chunks are re-extracted and re-indexed so the AI agent can retrieve them again. The retry is asynchronous: the endpoint returns 202 immediately with an empty body, and the document’s status transitions through pending to indexed (or back to error if it fails again) — poll GET /knowledge-bases/:id/documents for the outcome. Only failed documents are meaningfully retried. Requires an admin-class role and the knowledge:write scope; the call is audit-logged.

string

required

Knowledge base id, as returned by GET /knowledge-bases.

string

required

Document id within that knowledge base, as returned by GET /knowledge-bases/:id/documents.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/documents/doc_9a1c3e5b7d/retry" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/documents/doc_9a1c3e5b7d/retry', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/documents/doc_9a1c3e5b7d/retry", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/documents/doc_9a1c3e5b7d/retry", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/documents/doc_9a1c3e5b7d/retry')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/documents/doc_9a1c3e5b7d/retry');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "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"
  }
}

Update knowledge-base search config

PUT /api/v1/knowledge-bases/{id}/search-config

Replace a knowledge base’s retrieval re-rank / relevance-boost config. Every field has a no-op default, so a PUT of {} resets the KB to legacy raw-similarity ordering and an omitted knob never silently changes the others. Values are range-clamped server-side. Returns the normalised config. Requires the knowledge:write scope (admin / owner / developer).

string

required

Knowledge base ID (kb_…).

string

string (enum: true|false)

any

Minimum raw vector similarity (0..1) a chunk must clear to reach the agent. 0 = no floor (default).

any

Recency multiplier strength (0..5). 0 = off (default); fresher docs get up to ×(1 + boost).

any

Half-life in days of the recency decay (1..3650). Default 30.

object

Map of source label → score multiplier (0..20, keys matched case-insensitively). Default .

string[]

Allow-list of categories; empty = allow all (default).

string[]

Deny-list of categories. Default [].

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/knowledge-bases/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/search-config');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "min_score": 0,
    "recency_boost": 0,
    "recency_half_life_days": 0,
    "source_weights": {},
    "include_categories": [
      "string"
    ],
    "exclude_categories": [
      "string"
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

API Reference

All Endpoints

Knowledge Bases API

Knowledge Bases API

Worked sequences

1. Upload a document

2. Approve or reject a pending document

3. Search the knowledge base

4. Diff two document versions

Get knowledge-base search config

Retry document indexing

Update knowledge-base search config

​Knowledge Bases API

​Worked sequences

​1. Upload a document

​2. Approve or reject a pending document

​3. Search the knowledge base

​4. Diff two document versions

​Get knowledge-base search config

​Retry document indexing

​Update knowledge-base search config

Knowledge Bases API

Worked sequences

1. Upload a document

2. Approve or reject a pending document

3. Search the knowledge base

4. Diff two document versions

Get knowledge-base search config

Retry document indexing

Update knowledge-base search config