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). For a guided walkthrough and SDK snippets, see Knowledge bases.

Sources

POST /knowledge/sources

Create a knowledge base. Requires knowledge:write.

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.

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

See Errors for the full catalog.