Knowledge API

The knowledge API manages knowledge bases, documents, ingestion state, connector sources, document restrictions, and retrieval resources used by agents and workflows.

Prefix

/api/v1/knowledge

Endpoint families

Sources and sync runs

New in v1.5.0. Sources keep a knowledge base in step with an S3-compatible bucket (s3) or a website (web). See Knowledge connectors for the connectors' settings, change detection, scheduling, and limits.

Read and Update are access to the knowledge base, with its visibility applied: a private knowledge base's sources are as hidden as the base itself.

A source is created with:

A source response carries the effective limits, next_sync_at, last_sync_at, last_status, last_error, last_counts, and the active_run_id of a queued or running sync, never credentials. A sync run carries its trigger (manual or schedule), status, added_count, updated_count, unchanged_count, removed_count, failed_count, skipped_count, truncated, and error_code / error_message.

Document restrictions

New in v1.6.0. A restricted document is readable only by the workspace's Owners and Admins, the knowledge base's creator, and holders of a knowledge_document read grant. Everyone else does not see it in the document listing, gets 404 for it and its content, download, chunks, and versions, and never gets it from retrieval. See Restricted documents.

A restriction names a document by its doc_key, so it holds for every version. PUT takes:

PUT /api/v1/knowledge/knw_01JBX3K9Q4Z8M2V6T7R5N0PA1C/document-restrictions
Content-Type: application/json

{"doc_key": "payroll", "restricted": true}

and answers the base's restrictions the caller may read:

[
  {
    "knowledge_id": "knw_01JBX3K9Q4Z8M2V6T7R5N0PA1C",
    "doc_key": "payroll",
    "created_by": "u_01JBWZ7H2D5F8K3M6P9R1T4V7X",
    "created_at": "2026-10-02T09:14:03Z",
    "grant_resource_id": "knw_01JBX3K9Q4Z8M2V6T7R5N0PA1C:payroll"
  }
]

• {"doc_key": "...", "restricted": false} lifts the restriction. Sending the state a document already has changes nothing.
• A doc_key with no document in the base answers 404. A caller who may update the base but is not a workspace Owner or Admin or its creator gets 403.
• Each change is audited as knowledge.document.restricted or knowledge.document.unrestricted.
• GET leaves out restrictions on documents the caller may not read, so a reader is not told which documents are kept from them.

Granting read on a restricted document

To open a restricted document to one member or service principal, a workspace Owner or Admin creates a resource grant whose resource_id is the restriction's grant_resource_id ("{knowledge_id}:{doc_key}"):

POST /api/v1/resource-grants
Content-Type: application/json

{
  "resource_type": "knowledge_document",
  "resource_id": "knw_01JBX3K9Q4Z8M2V6T7R5N0PA1C:payroll",
  "user_id": "u_01JBX0M4C7E9G2J5L8N1Q3S6U8",
  "actions": ["read"]
}

The grant is created or, when one exists for the same resource and member, its actions replaced. GET /api/v1/resource-grants?resource_type=knowledge_document&resource_id=... lists the grants on a document, and DELETE /api/v1/resource-grants/knowledge_document/{resource_id}/{user_id} revokes one. From v1.5.2 creating or revoking a grant takes a workspace Owner or Admin; anyone else gets 403. See the Identity API.

Related prefixes

• /api/v1/agents, /api/v1/responses — where retrieval results and citations surface
• /api/v1/runs — retrieval steps in the runtime ledger
• /api/v1/resource-grants — knowledge_document read grants on restricted documents

Notes

• Documents are versioned by doc_key; ingestion is asynchronous and status-tracked with retry/cancel control.
• source_kind is one of upload, crawler, api, manual, or connector (documents a source synced, from v1.5.0).
• From v1.5.2 a document's file_id must name a file under the same knowledge base's storage; any other is refused with 400.
• Retrieval queries appear as retrieval run steps with vector metrics and produce citation evidence. From v1.6.0 the step's restricted_documents_excluded metric counts the restricted documents retrieval left out, and the keyword fallback answers from the latest version of each document only.
• From v1.6.0, copies of retrieved content kept in runs, responses, threads, and tasks are read back by the reader's current access. See Copies kept in runs, responses, and threads.