Knowledge Bases: Grounding Assistants in Your Content

A knowledge base (KB) is an indexed collection of documents that an assistant searches at runtime to ground its answers. You ingest content once, Feather chunks and embeds it asynchronously, and assistants retrieve the most relevant passages during a conversation.

Knowledge-base routes are nested under a doubled path: /v1/knowledge-base/knowledge-bases/.... Semantic search is the exception — it lives at /v1/knowledge-base/search.

Creating a knowledge base

Create a KB with POST /v1/knowledge-base/knowledge-bases. Only name is required; the embedding model, chunking, and retrieval settings all have sensible defaults.

Request

{
  "name": "Product Docs",
  "description": "Public help-center articles",
  "default_sensitivity_level": 0
}

The response includes the id, the resolved embedding_model and embedding_dimensions, document_count, and the default_sensitivity_level floor (defaults to 10 = internal).

Ingesting content

All ingestion goes through one unified endpoint: POST /v1/knowledge-base/knowledge-bases/{kb_id}/ingest. It accepts a multipart/form-data request with two parts:

manifest (required) — a JSON array describing each item to ingest.
files (optional, repeatable) — file uploads, referenced from the manifest by file_index.

Each manifest item is either a file or inline text:

manifest

[
  { "type": "file", "file_index": 0, "title": "Billing FAQ" },
  { "type": "text", "title": "Refund policy", "content": "Refunds are processed within..." },
  { "type": "file", "file_index": 1, "title": "Updated Terms", "document_id": "<existing-doc-id>" }
]

Pass document_id to ingest a new version of an existing document. To pull in web pages, use a connector (below) rather than the ingest endpoint — the manifest supports only file and text. The endpoint returns 202 with an ingestion_job_id and a per-item result of queued or duplicate.

Tracking ingestion

Ingestion is asynchronous. Poll progress two ways:

Endpoint	Returns
`GET /v1/knowledge-base/ingestion-jobs/{job_id}`	Job progress: per-state document counts and `progress_pct`
`GET /v1/knowledge-base/knowledge-bases/{kb_id}/ingestion-status`	Aggregate document-state counts for the whole KB

A job moves through queued → processing → a terminal state of completed, partial_failure, failed, duplicate, or quarantined. Retry a failed or partially failed job with POST /v1/knowledge-base/ingestion-jobs/{job_id}/retry.

ingestion-status returns counts of documents in each state (pending, processing, active, draft, archived, failed, quarantined, total) — not a per-document list. For per-document detail, call GET .../ingestion-jobs/{job_id}/documents.

Semantic search

Query a KB with POST /v1/knowledge-base/search:

Request

{
  "query": "How do I cancel my subscription?",
  "kb_ids": ["<kb-id>"],
  "limit": 10,
  "rerank": true
}

Field	Type	Notes
`query`	string (required)	The natural-language query
`kb_ids`	string[] (required)	One or more KBs to search
`limit`	integer	Number of chunks to return (default `30`, max `100`)
`rerank`	boolean	Apply a reranking pass (default `false`)
`alpha`	number	Hybrid dense/sparse weighting, `0.1`–`1.0` (default `0.5`; `1.0` = dense-only)
`prefer_draft`	boolean	Search the latest draft of each document

Each result carries content (the chunk text), a score, and the source document_id, document_title, and chunk_index. The response also includes an answerability verdict — a label of answerable, low_confidence, not_answerable, or unknown — so you can tell whether the KB actually covers the question rather than just returning the closest chunks.

Sensitivity and access control

Feather grades every document with a sensitivity level, and every assistant revision with a matching clearance. Retrieval only returns documents at or below the assistant’s clearance.

Level	Value	Meaning
`public`	0	Anyone can retrieve it
`internal`	10	Default floor for new documents
`confidential`	20	Sensitive business content
`restricted`	30	Most sensitive content

A document’s stamped sensitivity_level is the maximum of three signals: the KB’s default_sensitivity_level floor, a PII-based floor, and an LLM classifier. An assistant revision’s kb_clearance_level (one of 0, 10, 20, 30) then gates retrieval: it sees any document whose sensitivity_level is less than or equal to its clearance. So a restricted (30) assistant sees everything, while a public (0) assistant sees only public documents.

Sensitivity is per document, not per knowledge base — a KB only sets a default floor. New documents can enter a review queue (classification_status of pending_review); approve them with POST .../documents/{doc_id}/classification/approve.

Organization ACL

Beyond per-document sensitivity, an organization-level ACL maps your Clerk roles to clearance levels and audience groups (GET/PUT /v1/knowledge-base/acl/config). Enforcement is gated behind a rollout you control with a preflight check and explicit enable/disable (POST .../acl/rollout/preflight, .../enable, .../disable).

External sources (connectors)

Instead of uploading files, connect an external source and let Feather sync it. Sources live under a KB: POST /v1/knowledge-base/knowledge-bases/{kb_id}/sources. Supported providers:

Notion

Sync pages and databases. Requires an active Notion integration connection.

Google Drive

Sync files and folders. Requires an active Google Drive integration connection.

Amazon S3

Sync objects from a bucket. Provide access-key or role credentials inline.

Web (URL)

Crawl and index web pages. No connection required.

Within a source you define roots — the specific pages, folders, buckets, or URLs to sync. Trigger a manual sync with POST .../sources/{source_id}/sync, or schedule automatic syncs with PATCH .../sources/{source_id}/schedule by setting auto_sync_enabled and a sync_interval_seconds.

Attaching a KB to an assistant

Add a KB to an assistant revision via the knowledge_base_refs field. Each ref is { id, description?, clearance_level? }. The optional per-ref clearance_level can only lower the effective clearance for that KB below the revision’s kb_clearance_level — never raise it.

{
  "knowledge_base_refs": [
    { "id": "<kb-id>", "description": "Product help center" }
  ]
}

Next steps

Ingest documents

A hands-on guide to the unified ingest endpoint, polling jobs, and connecting external sources.

Knowledge base API reference

Full reference for KB, document, ingestion, search, and connector endpoints.

Get Started

Core Concepts

Guides

Channels

Knowledge Bases: Grounding Assistants in Your Content

Creating a knowledge base

Ingesting content

Tracking ingestion

Semantic search

Sensitivity and access control

Organization ACL

External sources (connectors)

Notion

Google Drive

Amazon S3

Web (URL)

Attaching a KB to an assistant

Next steps

Ingest documents

Knowledge base API reference

​Creating a knowledge base

​Ingesting content

​Tracking ingestion

​Semantic search

​Sensitivity and access control

​Organization ACL

​External sources (connectors)

Notion

Google Drive

Amazon S3

Web (URL)

​Attaching a KB to an assistant

​Next steps

Ingest documents

Knowledge base API reference

Creating a knowledge base

Ingesting content

Tracking ingestion

Semantic search

Sensitivity and access control

Organization ACL

External sources (connectors)

Attaching a KB to an assistant

Next steps