knowledge.process

Index an uploaded document.

Reference

POST/api/v1/knowledge-base/process-document

Auth

API key in X-API-Key

Content

application/json

Returns

200 · DocumentResponseSchema

Trigger asynchronous processing of an uploaded document. This endpoint should be called after successfully uploading a file to the presigned URL. It will: 1. Create a document record in the database with the specified UUID 2. Enqueue a background task to process the document (chunking and embedding) The document status will be updated from 'pending' -> 'processing' -> 'completed' or 'failed'. Embedding: Uses OpenAI text-embedding-3-small (1536-dimensional embeddings, requires API key configured in Model Configurations). Access Control: * Users can only process documents in their organization.

Arguments

Argument	In	Type	Required	Description
scope	body	string	default "library"	library: read only by a node that names it. org: every agent in the organisation. channel: the agents answering in folder_id. agent: the one agent in workflow_id.
folder_id	body	integer	optional	For scope=channel.
workflow_id	body	integer	optional	For scope=agent.
file_folder_id	body	integer	optional	The Files-page folder to put the file in (none: the top level). Organises only; it does not change who reads the file.
document_uuid	body	string	required	Document UUID to process
s3_key	body	string	required	S3 key of the uploaded file
retrieval_mode	body	string	default "chunked"	Retrieval mode: 'chunked' for vector search or 'full_document' for full text retrieval

Example request

curl -X POST "https://api.decibyl.ai/api/v1/knowledge-base/process-document" \
  -H "X-API-Key: dcb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"scope":"library","folder_id":1,"workflow_id":1,"file_folder_id":1,"document_uuid":"string","s3_key":"string","retrieval_mode":"chunked"}'

Response

{
  "id": 1,
  "document_uuid": "string",
  "filename": "string",
  "file_size_bytes": 1,
  "file_hash": "string",
  "mime_type": "string",
  "processing_status": "string",
  "processing_error": "string",
  "needs_reingest": false,
  "total_chunks": 1,
  "retrieval_mode": "chunked",
  "custom_metadata": {},
  "docling_metadata": {},
  "source_url": "string",
  "scope": "library",
  "folder_id": 1,
  "workflow_id": 1,
  "file_folder_id": 1,
  "created_at": "2026-09-14T09:30:00Z",
  "updated_at": "2026-09-14T09:30:00Z",
  "organization_id": 1,
  "created_by": 1,
  "is_active": true,
  "version": 1,
  "versions": [
    {
      "version": 1,
      "uploaded_at": "string",
      "uploaded_by": 1,
      "file_size_bytes": 1,
      "current": false
    }
  ],
  "state": "ready",
  "state_detail": "string"
}

Errors

Status	When
404	Not found
422	Validation Error