GET /v1/knowledge-sources?agent_id=...lists sources, one page at a time, beside the agent’scollections(each with whether it is attached and how it stands against the last build) andpdf_supported(whether a PDF upload can be read on this deployment).POST /v1/knowledge-sources?agent_id=...uploads one document asmultipart/form-data(file, optionalcollection). Plain text, Markdown, CSV, saved web pages, Word documents and PDF are accepted (a PDF is read only wherepdf_supportedis 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 answers201, from the saved record, withcollectionsandattachednull; 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 theprocessingstate that re-read left (parsed, orfailedwith the reason).DELETE /v1/knowledge-sources/{id}?agent_id=...removes it from the library; the versions already built with it keep naming it.
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}takesaction:link,dismissordelete. Linking also requires asource_idnaming 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 includesid,state, the newrevisionandnote.PUT /v1/knowledge/questions/{question_id}/answeralso takesanswer, 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 canonicalsource_id. A failed ingestion does not resolve the question; retrying the same content reuses its source rather than creating another one.
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.