Knowledge

4 operations. {prefix} is the route prefix passed to MapTracon; the template uses /tracon.

GET {prefix}/api/knowledge/{collection}/documents

Operation ID: TraconListKnowledgeDocuments

Lists the sources in a collection.

The response is a flat list of source identifiers, not the chunks or their text: a source is the unit a document was uploaded and is deleted as. An unknown collection is not an error — it simply has no sources and returns an empty list. Knowledge storage requires PostgreSQL; without it the response is 501.

Authorization: bearer authentication; Reader role policy when that policy is registered; KnowledgeRead API-key scope.

Parameter	In	Required	Type	Description and rules
collection	path	yes	string	—

Response	Body	Headers
200 OK	application/json → array of string	—
501 Not Implemented	application/problem+json → ProblemDetails	—

POST {prefix}/api/knowledge/{collection}/documents

Operation ID: TraconUploadKnowledgeDocument

Uploads a document to the knowledge base.

The body carries either ‘text’ (the server chunks and embeds it) or ‘chunks’ (pre-chunked). PostgreSQL only: UsePostgreSql and an IEmbeddingGenerator must be registered. Text that is embedded passes the tenant’s provider checks first: a tenant whose egress policy does not name the embedding provider (Tracon:Knowledge:EmbeddingProvider), or that has its own credential for it, gets 403 and nothing is embedded.

Authorization: bearer authentication; Operator role policy when that policy is registered; KnowledgeAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
collection	path	yes	string	—

Request body (required):

• application/json → UploadDocumentRequest

Response	Body	Headers
200 OK	application/json → UploadDocumentResponse	—
400 Bad Request	application/problem+json → ProblemDetails	—
403 Forbidden	application/problem+json → ProblemDetails	—
501 Not Implemented	application/problem+json → ProblemDetails	—

DELETE {prefix}/api/knowledge/{collection}/documents/{sourceId}

Operation ID: TraconDeleteKnowledgeDocument

Deletes all chunks of a source.

Every chunk and embedding produced from the source is removed; re-uploading the document is the only way back, and it costs a fresh round of embedding calls. The call is idempotent: an unknown source id still answers 204, because the requested end state — no such source — already holds. Knowledge storage requires PostgreSQL; without it the response is 501.

Authorization: bearer authentication; Operator role policy when that policy is registered; KnowledgeAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
collection	path	yes	string	—
sourceId	path	yes	string	—

Response	Body	Headers
204 No Content	—	—
501 Not Implemented	application/problem+json → ProblemDetails	—

POST {prefix}/api/knowledge/{collection}/search

Operation ID: TraconSearchKnowledge

Performs a semantic search in a collection (for diagnostics and calibration).

This runs the same retrieval an agent performs, so it is how a retrieval problem is separated from a prompt problem: if the right chunk does not come back here, the agent was never going to see it. The query is embedded, which costs one embedding call per request. Each hit carries its distance — smaller is closer — along with the chunk text and its metadata, so a relevance threshold can be calibrated from real values. The query passes the tenant’s provider checks before it is embedded, as an upload does (403). Knowledge storage requires PostgreSQL; without it the response is 501.

Authorization: bearer authentication; Reader role policy when that policy is registered; KnowledgeRead API-key scope.

Parameter	In	Required	Type	Description and rules
collection	path	yes	string	—

Request body (required):

• application/json → SearchKnowledgeRequest

Response	Body	Headers
200 OK	application/json → array of SearchKnowledgeHit	—
403 Forbidden	application/problem+json → ProblemDetails	—
501 Not Implemented	application/problem+json → ProblemDetails	—