Skip to main content

Knowledge

Upload documents an agent can ground its answers in — a pricing sheet, an FAQ, a policy doc — instead of relying entirely on the model's own training.

Uploading a document​

curl -X POST https://convostack.ai/api/knowledge/documents \
  -H "Authorization: Bearer cak_live_..." \
  -F "[email protected]" \
  -F "name=Pricing Sheet 2026"

file is required (multipart), name is optional — it defaults to the uploaded file's original filename if omitted. Ingestion (text extraction + archival) happens synchronously, inside this request — the response already reflects the final outcome, not an intermediate "accepted" state:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Pricing Sheet 2026",
  "sourceFilename": "pricing-sheet.pdf",
  "mimeType": "application/pdf",
  "status": "ready",
  "charCount": 4213,
  "failureReason": null,
  "createdAt": "2026-01-15T10:00:00Z"
}

status is either ready (usable immediately — no need to poll) or failed, with failureReason explaining why (e.g. no extractable text). Because extraction runs before the response is sent, a very large file will make the request itself take longer rather than returning early.

Listing and retrieving documents​

curl https://convostack.ai/api/knowledge/documents \
  -H "Authorization: Bearer cak_live_..."

curl https://convostack.ai/api/knowledge/documents/{id} \
  -H "Authorization: Bearer cak_live_..."

Both are org-scoped — you only ever see your own organization's uploads.

Using a document on an agent​

Reference the document's id in an agent's knowledgeDocumentIds — see Agents. An agent can be grounded in multiple documents at once.