Knowledge Bases API

Upload documents (PDFs, Word, plain text, web pages) into per-tenant vector stores. AI agents query these stores at run time to ground their responses. Each knowledge base is an independent index — you’d typically have one per topic (“Product manuals”, “HR policies”, “Refund flow”). Base path: /api/v1/knowledge-bases Authentication: API key (X-API-Key) or session JWT. Upload limits: 10 MB per document. PDF, DOCX, TXT, MD, and HTML supported.

Knowledge bases

Method	Path	Purpose
`GET`	`/api/v1/knowledge-bases`	List knowledge bases
`POST`	`/api/v1/knowledge-bases`	Create a knowledge base
`GET`	`/api/v1/knowledge-bases/{id}`	Get a knowledge base
`PUT`	`/api/v1/knowledge-bases/{id}`	Update name / description
`DELETE`	`/api/v1/knowledge-bases/{id}`	Delete (purges all documents)

Documents

Method	Path	Purpose
`GET`	`/api/v1/knowledge-bases/{id}/documents`	List documents
`POST`	`/api/v1/knowledge-bases/{id}/documents`	Upload (multipart)
`DELETE`	`/api/v1/knowledge-bases/{id}/documents/{docId}`	Remove a document
`POST`	`/api/v1/knowledge-bases/{id}/documents/{docId}/retry`	Retry a failed indexing job
`POST`	`/api/v1/knowledge-bases/{id}/documents/{docId}/approve`	Approve a document pending review
`POST`	`/api/v1/knowledge-bases/{id}/documents/{docId}/reject`	Reject a document pending review
`GET`	`/api/v1/knowledge-bases/{id}/documents/{docId}/versions`	List a document’s version history
`GET`	`/api/v1/knowledge-bases/{id}/documents/{docId}/versions/diff`	Diff two versions of a document
`POST`	`/api/v1/knowledge-bases/{id}/documents/{docId}/rollback`	Restore a retained earlier version
`PATCH`	`/api/v1/knowledge-bases/{id}/documents/{docId}/publication`	Publish or unpublish a document on the public help center

Indexing happens asynchronously. A document goes through processing → ready (or failed). Poll GET /:id/documents to track status, and re-run a failed job with POST /:id/documents/{docId}/retry. Documents that require moderation move through a publish lifecycle: they start as pending, then become approved or rejected. While a document sits in pending its chunks are not retrievable by agents. Approve it with POST /:id/documents/{docId}/approve to promote it to ground-truth and start indexing, or reject it with POST /:id/documents/{docId}/reject to keep it out of retrieval. Both accept an optional body { "notes": "…" } to record a reviewer note on the document, and both require the knowledge:write scope. Every re-upload of a document retains the superseded copy as an immutable snapshot. GET /:id/documents/{docId}/versions returns the current head plus every retained snapshot so you can audit how the RAG ground-truth has changed over time. Compare any two retained versions with GET /:id/documents/{docId}/versions/diff?from={n}&to={m} — it returns added / removed / unchanged line counts plus unified-style hunk lines (+ added, - removed, context). A version whose content was not retained (it exceeded the retention size cap) returns 422. Restore an earlier version with POST /:id/documents/{docId}/rollback (body { "version": n }). Rollback is non-destructive — the target version’s content is re-uploaded as a new head version (the current head is snapshotted into history first), so the operation is fully reversible. It returns 202 with the freshly-minted head document.

Public help-center publication

Publish a document to your public help center with PATCH /:id/documents/{docId}/publication. This toggles whether a single document is exposed on the public help surface, independent of its indexing status for agents.

Field	Type	Description
`is_public`	boolean	Required. `true` exposes the document on the public help center; `false` removes it.
`slug`	string	URL segment the public page routes by. Lowercase letters, digits, and hyphens only (max 200 chars). Required when `is_public` is `true` — the public surface cannot resolve a page without one.
`summary`	string	Optional public-facing summary (max 2000 chars).

The PATCH verb lets the operator UI flip publication with a partial body without re-stating the slug on every change. This is a write action — it requires the knowledge:write scope and an admin, owner, or developer seat, and both publishing and unpublishing are audit-logged, because setting is_public=true exposes the article to the open web. It returns the updated document.

curl -X PATCH https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_abc/documents/doc_123/publication \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "is_public": true, "slug": "international-refunds", "summary": "How refunds work for international orders." }'

Freshness

Method	Path	Purpose
`GET`	`/api/v1/knowledge-bases/{id}/staleness`	Freshness scorecard across all documents

Stale ground-truth is a leading cause of wrong agent answers. GET /:id/staleness scans every document in a knowledge base and classifies each one by age into a fresh, stale, or critical bucket, so you can find and re-verify outdated content before agents cite it. A document’s age is measured from its last operator verification (last_verified_at) if present, otherwise its last update (updated_at). A document is stale once its age reaches the threshold, critical once it reaches twice the threshold, and fresh below it. A document with no verifiable timestamp is reported as critical. The default threshold is 90 days; override it for one call with ?default_threshold_days={n} (1–3650). A per-document threshold, when set, always takes precedence over the default. The response is a scorecard:

Field	Description
`knowledge_base_id`	The scanned knowledge base.
`totals.fresh` / `totals.stale` / `totals.critical`	Document counts per bucket.
`totals.documents_scanned`	Total documents classified.
`totals.never_verified`	Documents never operator-verified.
`attention_required`	Documents not in the `fresh` bucket, oldest-first. Each entry carries `id`, `name`, `type`, `status`, `bucket`, `age_days`, `threshold_days`, `last_verified_at`, `last_cited_at`, and `updated_at`.
`default_threshold_days`	The threshold applied to documents without a per-document override.
`scanned_at`	When the scan ran (ISO-8601).

curl https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_abc/staleness?default_threshold_days=30 \
  -H "X-API-Key: dv_live_sk_your_key_here"

Connectors

A connector binds a knowledge base to an external content source (Notion, Confluence, Google Drive, SharePoint, or Zendesk) and keeps it in sync.

Connector management

Method	Path	Purpose
`GET`	`/api/v1/knowledge-bases/{id}/connectors`	List a knowledge base’s connectors
`POST`	`/api/v1/knowledge-bases/{id}/connectors`	Add a connector to a knowledge base
`PATCH`	`/api/v1/knowledge-bases/{id}/connectors/{connectorId}`	Update a connector
`DELETE`	`/api/v1/knowledge-bases/{id}/connectors/{connectorId}`	Remove a connector
`POST`	`/api/v1/knowledge-bases/{id}/connectors/{connectorId}/sync`	Trigger an immediate sync for a connector

Listing connectors needs knowledge:read. Adding, updating, deleting, and syncing a connector each require knowledge:write (admin, owner, or developer seat), since they bind a knowledge base to — or refresh it from — an external source. POST /:id/connectors/{connectorId}/sync runs the connector’s sync immediately instead of waiting for the next scheduled refresh.

Drift report

Method	Path	Purpose
`GET`	`/api/v1/knowledge-bases/{id}/connector-drift-report`	Content-drift scorecard for source connectors

When a knowledge base syncs from external sources, content can drift from the cached copy your agents ground on. GET /:id/connector-drift-report reports which sources have diverged since their last successful sync, so you can trigger a refresh before agents answer from stale content.

Search

Method	Path	Purpose
`POST`	`/api/v1/knowledge-bases/{id}/search`	Semantic search across documents
`GET`	`/api/v1/knowledge-bases/{id}/search-config`	Read the retrieval re-ranking config
`PUT`	`/api/v1/knowledge-bases/{id}/search-config`	Replace the retrieval re-ranking config

curl -X POST https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_abc/search \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How do refunds work for international orders?", "limit": 4 }'

Re-ranking configuration

Each knowledge base carries a re-ranking config that controls how retrieved chunks are scored and filtered before they ground an agent answer. The config applies to both the agent retrieval path and the POST /:id/search endpoint for that knowledge base. GET /api/v1/knowledge-bases/{id}/search-config returns the current config. Reading requires the knowledge:read scope. PUT /api/v1/knowledge-bases/{id}/search-config replaces it. Every field has a no-op default, so a PUT with {} resets the knowledge base to legacy raw-similarity ordering. Writing requires the knowledge:write scope and an owner, admin, or developer role.

Field	Type	Default	Range	Effect
`min_score`	number	`0`	0–1	Drop chunks whose raw vector similarity is below this floor.
`recency_boost`	number	`0`	0–5	Recency multiplier strength. `0` disables it; fresher documents are boosted up to ×(1 + `recency_boost`).
`recency_half_life_days`	number	`30`	1–3650	Half-life (in days) of the recency decay applied by `recency_boost`.
`source_weights`	object	`{}`	values 0–20	Map of source label → score multiplier. Keys are matched case-insensitively.
`include_categories`	string[]	`[]`	≤ 200 entries	Allow-list of categories. Empty allows all.
`exclude_categories`	string[]	`[]`	≤ 200 entries	Deny-list of categories.

curl -X PUT https://api.orbit.devotel.io/api/v1/knowledge-bases/kb_abc/search-config \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "min_score": 0.6,
        "recency_boost": 1.5,
        "recency_half_life_days": 14,
        "source_weights": { "product-manual": 2, "community-forum": 0.5 },
        "include_categories": ["refunds", "shipping"],
        "exclude_categories": ["internal"]
      }'

Retrieval tuning (operator)

When an AI agent grounds a reply, the executor retrieves KB chunks for that turn (see AI Agents API). Two platform environment variables control how many chunks each agent turn retrieves and how aggressively low-relevance chunks are filtered. They are platform-wide defaults set by the operator (not per-request), and matter most for tenants with noisy knowledge bases:

Variable	Default	Range	Effect
`DEVOTEL_KB_TOP_K`	`5`	1–50	Chunks retrieved per agent turn. Bigger = more context but more tokens billed per turn; smaller = tighter signal and faster turns.
`DEVOTEL_KB_SCORE_THRESHOLD`	`0.7`	0–1	Cosine-similarity cutoff; chunks scoring below this are dropped. Raise it to suppress weakly-related noise; lower it if relevant chunks are being filtered out.

These tune the agent retrieval path only. The POST /api/v1/knowledge-bases/{id}/search endpoint above takes its own per-request limit and is unaffected by these variables.

API Reference

All Endpoints

Knowledge Bases API

Knowledge Bases API

Knowledge bases

Documents

Public help-center publication

Freshness

Connectors

Connector management

Drift report

Search

Re-ranking configuration

Retrieval tuning (operator)

See also

​Knowledge Bases API

​Knowledge bases

​Documents

​Public help-center publication

​Freshness

​Connectors

​Connector management

​Drift report

​Search

​Re-ranking configuration

​Retrieval tuning (operator)

​See also

Knowledge Bases API

Knowledge bases

Documents

Public help-center publication

Freshness

Connectors

Connector management

Drift report

Search

Re-ranking configuration

Retrieval tuning (operator)

See also