# Knowledge

Manage knowledge bases and upload documents over /knowledge/* with an API key scoped knowledge:read / knowledge:write.

Source: https://docs.polimorf.app/docs/api/knowledge

Manage knowledge bases and their documents with an API key. Every route is
scoped to the **key's own workspace** — you never pass an organization or
workspace id. Reads require the `knowledge:read` scope; writes require
`knowledge:write` (see [Authentication](/docs/authentication)). For a guided
walkthrough and SDK snippets, see [Knowledge bases](/docs/knowledge).

## Sources

### `POST /knowledge/sources`

Create a knowledge base. Requires `knowledge:write`.

| Field         | Type   | Required | Description               |
| ------------- | ------ | -------- | ------------------------- |
| `name`        | string | yes      | Display name of the base. |
| `description` | string | no       | Optional description.     |

```bash
curl https://api.polimorf.app/knowledge/sources \
  -H "Authorization: Bearer $POLIMORF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product FAQ" }'
```

### `GET /knowledge/sources`

List the bases in the workspace (`knowledge:read`).

### `DELETE /knowledge/sources/:sourceId`

Delete a base **and all of its documents** (`knowledge:write`).

## Documents

### `GET /knowledge/sources/:sourceId/documents`

List a base's documents with their ingestion `status` (`PENDING`, `PROCESSING`,
`READY`, `FAILED`). Requires `knowledge:read`.

### Direct upload — `POST /knowledge/sources/:sourceId/documents/upload`

The one-shot path: send the document bytes **base64-encoded inline** and the
server stores and ingests it. Best for small documents; large binaries should
use the presigned flow below. Requires `knowledge:write`.

| Field           | Type   | Required | Description                                                         |
| --------------- | ------ | -------- | ------------------------------------------------------------------- |
| `filename`      | string | yes      | Filename with a supported extension (see [types](/docs/knowledge)). |
| `contentBase64` | string | yes      | The document bytes, base64-encoded.                                 |
| `contentType`   | string | no       | Derived from the filename extension when omitted.                   |

```bash
curl https://api.polimorf.app/knowledge/sources/$SOURCE_ID/documents/upload \
  -H "Authorization: Bearer $POLIMORF_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"filename\": \"faq.md\", \"contentBase64\": \"$(base64 < faq.md)\" }"
```

Returns the created document (`status: "PENDING"`); ingestion runs in the
background.

### Presigned upload (large files)

Use this three-step flow to stream large binaries straight to object storage
without routing the bytes through the API. The SDK's
`client.knowledge.uploadDocument` performs all three steps for you.

1. **Request a presigned URL** — `POST /knowledge/sources/:sourceId/documents`

   | Field         | Type   | Required | Description                           |
   | ------------- | ------ | -------- | ------------------------------------- |
   | `filename`    | string | yes      | Filename with a supported extension.  |
   | `contentType` | string | yes      | Must match the filename's extension.  |
   | `byteSize`    | number | yes      | Size of the file in bytes (≤ 25 MiB). |

   Returns `{ document, upload: { url, method: "PUT", headers, expiresAt } }`.

2. **Upload the bytes** — `PUT` the file to `upload.url` with the returned
   `upload.headers`. This request goes to object storage, not the API, and
   carries no API key.

3. **Complete** — `POST /knowledge/sources/:sourceId/documents/:documentId/complete`
   confirms the upload and enqueues ingestion. Returns the document.

### `POST /knowledge/sources/:sourceId/documents/:documentId/retry`

Re-run ingestion for a `FAILED` document (`knowledge:write`).

### `DELETE /knowledge/sources/:sourceId/documents/:documentId`

Delete a single document and its stored bytes (`knowledge:write`).

## Errors

| Status | Code               | Meaning                                                       |
| ------ | ------------------ | ------------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR` | Unsupported extension, type/extension mismatch, or too large. |
| `403`  | `FORBIDDEN`        | The key lacks `knowledge:read`/`knowledge:write`.             |
| `404`  | `NOT_FOUND`        | No such source or document in the key's workspace.            |

See [Errors](/docs/errors) for the full catalog.