# Knowledge

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/http-api/knowledge/
> Summary: The knowledge endpoints of the Tracon HTTP API — 4 operations.

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`](/http-api/schemas/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`](/http-api/schemas/uploaddocumentrequest/)

| Response | Body | Headers |
|---|---|---|
| **200** OK | `application/json` → [`UploadDocumentResponse`](/http-api/schemas/uploaddocumentresponse/) | — |
| **400** Bad Request | `application/problem+json` → [`ProblemDetails`](/http-api/schemas/problemdetails/) | — |
| **403** Forbidden | `application/problem+json` → [`ProblemDetails`](/http-api/schemas/problemdetails/) | — |
| **501** Not Implemented | `application/problem+json` → [`ProblemDetails`](/http-api/schemas/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`](/http-api/schemas/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`](/http-api/schemas/searchknowledgerequest/)

| Response | Body | Headers |
|---|---|---|
| **200** OK | `application/json` → array of [`SearchKnowledgeHit`](/http-api/schemas/searchknowledgehit/) | — |
| **403** Forbidden | `application/problem+json` → [`ProblemDetails`](/http-api/schemas/problemdetails/) | — |
| **501** Not Implemented | `application/problem+json` → [`ProblemDetails`](/http-api/schemas/problemdetails/) | — |