Documents

What's actually available today via the public API, and what's dashboard-only for now — no guessing.

Uploading (dashboard only, for now)

Uploading is a dashboard feature: drag a PDF, DOCX, TXT, Markdown, or HTML file into a knowledge base, and it moves through QUEUED → EXTRACTING → CHUNKING → EMBEDDING → READY in the background — visible in real time, with a clear failure reason and a retry action if any stage fails. Programmatic upload via API key isn't on the public API yet — if you need it sooner, this is worth telling us.

Listing documents

GET/v1/knowledge-bases/:id/documents

Returns every non-deleted document in a knowledge base, most recent first, with its current status. Use this to poll ingestion progress for documents your team uploaded via the dashboard.

bash

curl "https://api.nexus.chaitanya-bajpai.xyz/v1/knowledge-bases/kb_123/documents?limit=20" \
  -H "Authorization: Bearer rk_live_..."

Response:

json

{
  "data": [
    {
      "id": "doc_01h...",
      "fileName": "product-handbook.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 482913,
      "status": "READY",
      "failureReason": null,
      "retryCount": 0,
      "createdAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "nextCursor": null
}

A knowledge base that doesn't exist — or belongs to a different organization than your key — returns a plain 404, never a 403: whether it's missing or just not yours isn't something a caller without access should be able to distinguish.

Document status values

PENDING_UPLOAD — a presigned URL was issued, bytes haven't arrived yet
QUEUED · EXTRACTING · CHUNKING · EMBEDDING — actively processing
READY — chunked, embedded, and included in chat retrieval
FAILED — check failureReason; retryable from the dashboard up to a small attempt cap