Skip to main content

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.

Using the SDKs

The Python SDK doesn’t wrap knowledge bases — its client.request escape hatch creates a base and runs the same semantic search (source-only; vendor it from packages/sdk-python):
Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Knowledge bases

Documents

Indexing happens asynchronously. A document goes through processingready (or failed). Poll GET /:id/documents to track status, and re-run a failed job with POST /:id/documents/{docId}/retry.

Upload

Binary files (PDF, DOCX, images — OCR-extracted) go up as multipart/form-data: send the file bytes plus the name and type fields. Uploading returns 202 immediately because chunking and embedding run after the response ships; the accepted document comes back at processing status.
202
Poll the list until the status reaches ready (or failed):
200
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. Approve:
200
Reject (same endpoint shape, same response envelope — the moderation.status reads rejected):
200
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.
200
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.
200
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.
202

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. 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.
200

Freshness

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:
200

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

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. Create a connector:
201
Trigger an immediate sync (the returned connector flips to queued and the drain worker picks it up):
202

Drift report

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.
200
Treat the report as meaningful only once detection_active is true — before the worker has run a first drift check, every connector reads unknown and the zero-drift totals are not a clean bill.
200

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.
200

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: 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.

See also