Knowledge base API

The KB powers the in-process search_knowledge tool. Files can be scoped tenant-wide (every agent sees them) or to a specific agent (only that agent sees them). The two surfaces share a common file shape but live behind different routes.

List KB files (tenant-wide)

GET /api/kb

200 OK
{
  "items": [
    {
      "id": "kb_01",
      "name": "Pricing 2026.pdf",
      "agentSlug": null,
      "sizeBytes": 12345,
      "createdAt": "2026-05-25T10:00:00.000Z"
    }
  ]
}

Create a KB row

POST /api/kb — create a metadata row (no attachment). Useful when uploading a file's content via a separate signed URL.

Request body
{
  "name": "Pricing 2026.pdf",
  "agentSlug": null,
  "content": "..."   // optional inline text
}

200 OK
{ "id": "kb_02", "name": "Pricing 2026.pdf", ... }

Upload a file (multipart)

POST /api/kb/upload — multipart form with a file part and optional agentSlug form field. The platform parses text out of PDFs / .docx / .md / .txt and stores both the raw bytes and the parsed text.

200 OK
{
  "id": "kb_03",
  "name": "Onboarding Playbook.docx",
  "tokenEstimate": 2048
}

400 Bad Request
{ "error": "unsupported_file_type" }
{ "error": "file_too_large", "detail": "Max 10 MB" }

Update a KB file

PATCH /api/kb/:id

Request body (partial)
{ "name": "Pricing 2026 (v2).pdf" }

200 OK
{ "id": "kb_01", "name": "Pricing 2026 (v2).pdf", ... }

Delete a KB file

DELETE /api/kb/:id

200 OK
{ "id": "kb_01", "deleted": true }

Per-agent KB

See the Agents API for the per-agent KB routes:

• POST /api/agents/:slug/kb — create.
• POST /api/agents/:slug/kb/upload — upload.
• PATCH /api/agents/:slug/kb/:fileId — update.
• DELETE /api/agents/:slug/kb/:fileId — delete.

Search semantics

The search_knowledge tool is in-process: it runs a BM25-style ranker over the parsed text + the file name + any manual tags. It is not a vector / embedding search; the design call is documented in ADR-001.

Source: src/platform/kb-api.ts.