Browsing Documents & Metadata

View knowledge base documents, system fields, extracted metadata, and sharing origin

In Knowledge Bases, select a knowledge base to browse its document list: search by name, filter by status (pending/processing/completed/error) or type, and open a document to inspect its chunks and metadata. Knowledge bases shared into your team carry an origin badge and are read-only throughout.

Document list and filters

The document list endpoint supports three filter dimensions, usable together:

Parameter	Type	Notes
`search`	string	Fuzzy match on the document name
`status`	string array	`pending`, `processing`, `completed`, `error`
`doc_type`	string array	`pdf`, `docx`, `doc`, `pptx`, `txt`, `markdown`, `html`, `csv`, `xlsx`, `xls`, `json`, `url`
`page` / `page_size`	integer	Defaults `1` / `20`

The UI status and type filters are single-select, but the endpoint accepts arrays — scripts can filter on several statuses or types at once.

Document system fields

Field	Notes
`name`	Document name (the filename by default; URL imports may set a custom name)
`doc_type`	Document type: `pdf`, `docx`, `doc`, `pptx`, `txt`, `markdown`, `html`, `csv`, `xlsx`, `xls`, `json`, `url`
`file_size`	File size in bytes; empty for URL documents
`file_path`	Whether the file is stored server-side (empty for URL documents)
`source_url`	Origin URL (URL documents only)
`status`	`pending`, `processing`, `completed`, `error`
`error_message`	Failure reason (`error` status only)
`chunk_count`	Number of chunks generated
`token_count`	Estimated token count (sum of chunk characters ÷ 4)
`metadata`	Automatically extracted JSON metadata (see below)
`processed_at`	When processing completed
`created_at` / `updated_at`	Timestamps

Extracted metadata

metadata is a JSON object written by the processing pipeline during text extraction. It is not editable field by field and is regenerated on reprocessing. Common keys:

format: markdown means the content was converted to Markdown by the document converter (PDF/Office/HTML take this path).
char_count: character count of the cleaned text.
file_size, doc_type: file information captured during extraction.
media_assets: the list of embedded images that were extracted from the document (images are served through the document media endpoint).

Chunks carry their own metadata as well:

section: the heading breadcrumb of a Markdown document (for example Chapter 1 > Section 2), telling you which section a chunk came from.
chunk_type: table, code, list, or text (written only when it is not text).

This metadata is returned with search results and RAG context, so answers can cite their source.

What the document detail page does

Action	Notes	Permission
Preview / edit chunks	Inspect, modify, and delete chunks; tune settings and process an unprocessed document	Write
Retry failed chunks	Available only when status is `error` and failed chunks exist	Write
Reprocess	Deletes old chunks and vectors, then re-runs with new settings (manual edits are lost)	Write
Download original	Downloads the uploaded file (URL documents have no original)	Read
View source URL	Opens the origin address of a URL document	Read
Delete	Deletes the document and its chunks	Write

A knowledge base shared into your team (is_owned = false) is marked read-only in the UI: upload, import, edit, and delete entry points are hidden or disabled.

Two badges in the list and detail page tell ownership apart:

Badge	Shown when	Meaning
From `{team}` (`sharedFrom`)	`is_owned = false`	The knowledge base belongs to another team and is shared with yours; read-only, with all write actions and settings entry points unavailable
Shared with `{N}` teams (`sharedCount`)	`is_owned ≠ false` and `shared_with_count > 0`	Your team owns it and has shared it with N other teams

The list endpoint's include_shared and own_only decide whether shared-in knowledge bases appear:

Request	Result
Default (`include_shared=true`, `own_only=false`)	Includes TEAM/PUBLIC knowledge bases shared into your teams
`include_shared=false` or `own_only=true`	Returns only the knowledge bases you can normally see (your own teams); shared-in ones are dropped
`own_only=true` (non-superuser)	On top of the previous rule, limits to `created_by = current user`

For the cross-team sharing steps, read-only semantics, and how to revoke, see Create a Knowledge Base (the sharing section).

Editing documents

The only editable document field is the name (the frontend currently offers no rename action, so use the API). Knowledge base endpoints accept a JWT user session only, never an API key:

curl -X PUT "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/$DOC_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Employee Handbook (2026)"}'

metadata is regenerated during reprocessing and there is no dedicated metadata editing endpoint; tags, categories, and folders are not implemented either.

Usage in retrieval

Search results and RAG context carry each chunk's metadata, used to cite the source.
Search requests do not support metadata-based filtering or boosting — the only search filter is filter_doc_ids (restrict results to specific document IDs).
Images inside chunk content are served through the document media endpoint (/api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/media/{filename}) and require an authenticated request.

Import Documents — upload, URL import, and status transitions
Chunking and Document Processing — chunk preview, editing, and failure retries
Create a Knowledge Base — sharing, permissions, and read-only scope
Retrieval & Quality Tuning — the retrieval lab and diagnostics

Browsing Documents & Metadata

On this page