API ReferenceKnowledge Base
Process a document
POST /api/v1/knowledge-base/process-document — register a previously-uploaded file for chunking and embedding.
POST /api/v1/knowledge-base/process-documentStep 3 of the upload flow. Call this after PUTting your file to a presigned URL (from upload-url). zoxaAI creates the document record and enqueues background processing.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
document_uuid | UUID | ✓ | The UUID returned by upload-url. |
s3_key | string | ✓ | The S3 key returned by upload-url. |
retrieval_mode | "chunked" / "full_document" | — | Default "chunked". |
Response
A document record with processing_status="pending". File size, hash, and MIME type are populated by the background task — they may show as 0 / "" / application/octet-stream until processing runs.
Examples
curl -X POST https://dashboard.zoxa.ai/api/v1/knowledge-base/process-document \
-H "X-API-Key: zsk_..." \
-H "Content-Type: application/json" \
-d '{
"document_uuid": "abc12345-...",
"s3_key": "knowledge_base/12/abc12345-.../faq.pdf",
"retrieval_mode": "chunked"
}'Errors
| Status | detail | When |
|---|---|---|
500 | "Failed to process document" | Document or enqueue failed. |
Related
POST /knowledge-base/upload-url— steps 1–2GET /knowledge-base/documents/{uuid}— poll for status