> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sempera.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge

> Knowledge sources and processing state.

A Knowledge Source is a document an Agent can answer from. Sources belong to an agent's library and are grouped into collections; the Agent's draft names which collections are attached.

* `GET /v1/knowledge-sources?agent_id=...` lists sources, one page at a time, beside the agent's `collections` (each with whether it is attached and how it stands against the last build) and `pdf_supported` (whether a PDF upload can be read on this deployment).
* `POST /v1/knowledge-sources?agent_id=...` uploads one document as `multipart/form-data` (`file`, optional `collection`). Plain text, Markdown, CSV, saved web pages, Word documents and PDF are accepted (a PDF is read only where `pdf_supported` is true); the file is read at once and the response (`201`) is the source exactly as a read of it answers. If reading the library back fails after the file is saved, the upload still answers `201`, from the saved record, with `collections` and `attached` `null`; a read of the source a moment later fills them.
* `GET /v1/knowledge-sources/{id}?agent_id=...` reads one source.
* `POST /v1/knowledge-sources/{id}/reparse?agent_id=...` reads the stored file again and answers the `processing` state that re-read left (`parsed`, or `failed` with the reason).
* `DELETE /v1/knowledge-sources/{id}?agent_id=...` removes it from the library; the versions already built with it keep naming it.

A source carries `id`, `name`, `content_type` (the media type of what Sempera read the file as, which can differ from what the uploader claimed), `size_bytes`, `processing` (`state` is `queued`, `parsed` or `failed`, with `error`), `collections` (the ids of this agent's collections that hold it), `attached` (whether one of those collections is attached in the agent's draft) and `added_at` (when the file now on record was uploaded; an in-place edit through `PATCH /v1/knowledge/{id}/content` moves it). An id this agent's library does not hold, another agent's included, is `404 not_found` on every route. A source already removed reads as `404`, but `DELETE` and reparse answer it `409 conflict` with the reason ("that document was already removed"), and a library that cannot be read answers `DELETE` and reparse `409 conflict` with the reason, never `404`.

Processing state is tracked apart from the Agent's configuration: uploading never changes what the Agent says until the collection is attached in the draft and a version is published.

## Source testing

`PATCH /v1/knowledge-sources/{id}?agent_id=...` updates a text source with `content` and optional `expect_revision` from the library reading. Stale revisions return 409 and do not overwrite the newer reading. This uses library document ids, not the workspace UUIDs returned by the source testing context.

`POST /v1/knowledge/crawl` takes `agent_id`, `url` and optional `collection` to read one public HTTPS page (201). To refresh, send `agent_id` and `source_id` instead (200). This is a bounded single-page read, not a recursive site crawler. The existing private-address, redirect, size, timeout and quota checks apply. Both operations require `knowledge:write` and the configure-integration role. Neither attaches a source or publishes an agent.

`POST /v1/knowledge/chat` exposes the source-testing contract below to API clients and the console composer. It returns cited retrieved passages, not a generated conversational answer. Each request is independent; it has no hidden conversation history. Model-generated knowledge chat remains outside this contract.

`GET /v1/knowledge/testing-context?agent_id=...` requires `knowledge:read` and the read role capability in the selected workspace. It lists only sources visible to this credential (`sources`: id, name, parse status and owning agent), plus the requested agent's actual pathway nodes (`nodes`: id, label, prompt) and any `node_note`. Nodes are agent configuration: a credential without `agents:read` gets an empty `nodes` list and a note saying why. A foreign agent is not found. Loading a node in the console copies its recorded prompt into the composer; it does not simulate node execution, infer unrecorded per-node source bindings, or change source selection.

`POST /v1/knowledge/test` takes `agent_id`, `question`, and optional `source_ids` (at most 50 canonical source UUIDs from the context response). It requires `knowledge:write`, because a published test adds to the ask log, plus the read role and the same workspace/agent isolation. Omitting `source_ids` searches the built version; an explicit empty array searches nothing. An explicit selection searches those sources' latest parsed readings, without attaching or publishing them. Foreign or missing sources return 404, malformed ids or invalid questions return 400, and sources that cannot be read or are not ready return 409. Paused workspaces retain the context read but cannot run the POST, following the neighboring action guard and partner entitlement policy.

The result is a deterministic local retrieval diagnostic: question, verdict, reason, scored passages with source attribution, and `mode` (`published` or `selected_sources`). The `published` mode records an ask in the existing knowledge log; a `selected_sources` test records nothing, so it cannot close a caller's open question or change coverage. It is not a model-generated answer or a live call, contacts no provider, and leaves the agent's draft and published artifacts unchanged.

## Console source inventory and query filters

`GET /v1/knowledge/sources` and `/v1/knowledge/sources/picker` accept `agent_id` to narrow the credential's workspace-visible sources. Parsed source inventory rows normally return `COMPLETED`. `STALE` means a verified published snapshot binds an older reading of that document; an unbuilt or unattached source alone is not evidence of staleness. Failed and processing rows retain `FAILED` and `PROCESSING`.

`GET /v1/knowledge/queries` supports `source_id`, case-insensitive question search `q`, `status` (`all`, `answered`, `question_answered`, `question_open`), inclusive ISO 8601 `start_date` and `end_date`, `agent_id`, `take` (1 to 100), and `cursor`. These filters apply before pagination. Each row includes workspace-visible canonical `source_ids`; legacy asks without document attribution do not match a source filter. Foreign or missing source filters return 404. A question resolved by a later answer keeps that status even when the answer is outside the requested date window. The console sends local calendar-day boundaries as UTC instants.

The console's Export CSV downloads the currently filtered source inventory, with quoted cells and spreadsheet-formula escaping. Add sources at workspace level chooses the agent that owns the library, then uses the same upload, collection, web-page and Drive workflows as the agent page. Drive authorization and web fetching still require their configured owner permissions and network access; the console never claims a connection or import succeeded without the actual outcome.

## Recorded question lifecycle

`GET /v1/knowledge/queries` includes `question_id`, `question_revision`, `question_state`, `answer` and `answer_source_id`. Question identity is bound to the workspace, agent and normalized question text. Owner annotations are separate from the retrieval diagnostic's `status`; the original query history is retained.

Both mutation routes require `knowledge:write` and the configure-integration role capability. Read-only CI keys and runtime keys cannot use them. Send the recorded `agent_id`, `question` text and current integer `revision` (`question_revision` from the query row, initially 0). A stale revision returns `409 conflict`; an invented question or a question outside the credential's workspace is not found.

* `PATCH /v1/knowledge/questions/{question_id}` takes `action`: `link`, `dismiss` or `delete`. Linking also requires a `source_id` naming a ready source in the workspace and marks the question resolved. Dismiss and delete update only the annotation, not the query history or source library. The response includes `id`, `state`, the new `revision` and `note`.
* `PUT /v1/knowledge/questions/{question_id}/answer` also takes `answer`, a nonblank string of at most 20,000 characters. It ingests the answer as a text source through the ordinary quota and credit checks, then marks the question resolved. The response also includes the canonical `source_id`. A failed ingestion does not resolve the question; retrying the same content reuses its source rather than creating another one.

Neither route changes published knowledge. Attach the source's collection and publish a version before callers can use the answer. Question changes require the workspace database; an unavailable database is not a successful save.

## Retrieval settings

`GET /v1/agents/{agent_id}/knowledge/retrieval-settings` needs `knowledge:read` and answers `{settings, revision, applies_to, note}`. `PUT /v1/agents/{agent_id}/knowledge/retrieval-settings` needs `knowledge:write` and the `owner` role. It takes `settings` and `expect_revision`, the draft revision you read. `settings` is `{boost_columns, exclude_fields}`: up to 50 boost columns with weights from 1 to 20, and up to 50 excluded fields, none of which may also be boosted. Field names are labels in the extracted rows (1 to 64 letters, digits, spaces, underscores or hyphens). A stale draft is `409 conflict`.

Save stages the settings in the agent draft, and they apply from the next published version. Exclusions drop labelled fields only, not unlabelled prose, and never delete source data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.