Cortex API

Documents

Endpoint

Document upload and management

Upload a document

POST

http://localhost:8000

/api/upload

Upload a file for processing into the knowledge base

Upload a document › query Parameters

start_processing

boolean

Start processing immediately

Default: true

collection_id

string

Assign to a collection

source

string

Source identifier for the document (e.g. 'youtube-transcriber', 'slack-bot'). Defaults to 'upload'.

Default: upload

source_key

string · minLength: 1 · maxLength: 512

Stable identity of the file at its source (e.g. nextcloud:<server>:<fileId>, url:<url>). If a document with this key exists, it is replaced in place — same document id, and only changed content is re-extracted (entities, relationships and curation of unchanged parts are kept). Otherwise a new document is created and stores the key. Also accepted as a form field. An empty value is treated as absent. While a key is given, the same-filename-and-size duplicate guard (409) is skipped.

replace_document_id

string

Replace this existing document in place (takes precedence over source_key; sets source_key on it when both are given). If the document no longer exists the upload falls back to source_key resolution, then to a new document — it never 404s. 403 if the document is outside the caller's collection scope. Also accepted as a form field; empty = absent.

Upload a document › Request Body

file

string · required

File to upload (PDF, TXT, MD, DOCX, XLSX)

Upload a document › Responses

Document uploaded, replaced in place (replaced: true), or left untouched because the bytes are identical to a completed document (unchanged: true).

document_id

string

id

string

Alias of document_id

filename

string

status

string · enum

Enum values:

pending

processing

extracting

completed

failed

message

string

source

string

Default: upload

replaced

boolean

An existing document (source_key / replace_document_id) was updated in place; document_id is unchanged. Always present.

unchanged

boolean

The bytes were identical to an already-completed document, so nothing was reprocessed. Always present.

POST/api/upload

curl --request POST \
  --url http://localhost:8000/api/upload \
  --header 'Content-Type: multipart/form-data' \
  --form file=file

shell

Example Request Body

{
  "file": "file"
}

json

Example Responses

{
  "document_id": "document_id",
  "id": "id",
  "filename": "filename",
  "status": "pending",
  "message": "message",
  "source": "source",
  "replaced": true,
  "unchanged": true
}

json

application/json

List documents

GET

http://localhost:8000

/api/documents

List all documents with optional pagination and filtering

List documents › query Parameters

skip

integer

Default: 0

limit

integer

Default: 100

collection_id

string

List documents › Responses

200

Documents retrieved

object[]

total

integer

GET/api/documents

curl --request GET \
  --url http://localhost:8000/api/documents

shell

Example Responses

{
  "documents": [
    {
      "id": "id",
      "filename": "filename",
      "file_type": "file_type",
      "file_size": 0,
      "upload_date": "2024-08-25T15:00:00Z",
      "processing_status": "pending",
      "chunk_count": 0,
      "collection_id": "collection_id",
      "source": "source",
      "content_status": "empty",
      "content_note": "content_note"
    }
  ],
  "total": 0
}

json

application/json

Delete ALL documents

DELETE

http://localhost:8000

/api/documents

Warning: This permanently deletes all documents, chunks, and associated entities.

Delete ALL documents › Responses

200

All documents deleted

No data returned

DELETE/api/documents

curl --request DELETE \
  --url http://localhost:8000/api/documents

shell

Example Responses

No example specified for this content type

Get document details

GET

http://localhost:8000

/api/documents/{document_id}

Get document details › path Parameters

document_id

string · required

Get document details › Responses

Document retrieved

id

string

filename

string

file_type

string

file_size

integer

upload_date

string · date-time

processing_status

string · enum

Enum values:

pending

processing

extracting

completed

failed

chunk_count

integer

collection_id

string

source

string

Origin of the document (e.g. 'upload', 'custom_input', or a custom source set via API)

content_status

string | null · enum

Set when the source file yielded nothing to ingest — 'empty' (zero bytes / no pages / no text) or 'encrypted' (password-protected PDF). Such documents are 'completed', not 'failed': the outcome is terminal and no reprocess can change it. Absent for normal documents.

Enum values:

empty

encrypted

content_note

string

Human-readable explanation of content_status (empty string when unset)

GET/api/documents/{document_id}

curl --request GET \
  --url http://localhost:8000/api/documents/:document_id

shell

Example Responses

{
  "id": "id",
  "filename": "filename",
  "file_type": "file_type",
  "file_size": 0,
  "upload_date": "2024-08-25T15:00:00Z",
  "processing_status": "pending",
  "chunk_count": 0,
  "collection_id": "collection_id",
  "source": "source",
  "content_status": "empty",
  "content_note": "content_note"
}

json

application/json

Delete a document

DELETE

http://localhost:8000

/api/documents/{document_id}

Delete a document › path Parameters

document_id

string · required

Delete a document › Responses

Document deleted

No data returned

DELETE/api/documents/{document_id}

curl --request DELETE \
  --url http://localhost:8000/api/documents/:document_id

shell

Example Responses

No example specified for this content type

Get document with chunk content

GET

http://localhost:8000

/api/documents/{document_id}/content

Get document with chunk content › path Parameters

document_id

string · required

Get document with chunk content › Responses

200

Document content retrieved

id

string

filename

string

object[]

GET/api/documents/{document_id}/content

curl --request GET \
  --url http://localhost:8000/api/documents/:document_id/content

shell

Example Responses

{
  "id": "id",
  "filename": "filename",
  "chunks": [
    {
      "id": "id",
      "content": "content",
      "chunk_index": 0
    }
  ]
}

json

application/json

Get original document file

GET

http://localhost:8000

/api/documents/{document_id}/file

Serve the original uploaded file for viewing or download. Returns the raw file with its stored filename and content type. For restricted API keys, access is validated against the document's collection.

Get original document file › path Parameters

document_id

string · required

Get original document file › Responses

Original file stream

No data returned

GET/api/documents/{document_id}/file

curl --request GET \
  --url http://localhost:8000/api/documents/:document_id/file

shell

Example Responses

No example specified for this content type

application/octet-stream

Reprocess a document

POST

http://localhost:8000

/api/documents/{document_id}/reprocess

Re-run processing pipeline on existing document

Reprocess a document › path Parameters

document_id

string · required

Reprocess a document › Responses

200

Reprocessing started

No data returned

POST/api/documents/{document_id}/reprocess

curl --request POST \
  --url http://localhost:8000/api/documents/:document_id/reprocess

shell

Example Responses

No example specified for this content type

Bulk delete documents

POST

http://localhost:8000

/api/documents/delete

Bulk delete documents › Request Body

document_ids

string[] · required

Bulk delete documents › Responses

200

Documents deleted

No data returned

POST/api/documents/delete

curl --request POST \
  --url http://localhost:8000/api/documents/delete \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_ids": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "document_ids": [
    "string"
  ]
}

json

Example Responses

No example specified for this content type

Bulk reprocess documents

POST

http://localhost:8000

/api/documents/reprocess

Bulk reprocess documents › Request Body

document_ids

string[] · required

Bulk reprocess documents › Responses

200

Reprocessing started

No data returned

POST/api/documents/reprocess

curl --request POST \
  --url http://localhost:8000/api/documents/reprocess \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_ids": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "document_ids": [
    "string"
  ]
}

json

Example Responses

No example specified for this content type

Move documents to collection

POST

http://localhost:8000

/api/documents/move

Move documents to collection › Request Body

document_ids

string[] · required

collection_id

string · required

Move documents to collection › Responses

200

Documents moved

No data returned

POST/api/documents/move

curl --request POST \
  --url http://localhost:8000/api/documents/move \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_ids": [
    "string"
  ],
  "collection_id": "collection_id"
}
'

shell

Example Request Body

{
  "document_ids": [
    "string"
  ],
  "collection_id": "collection_id"
}

json

Example Responses

No example specified for this content type

Download documents as ZIP

POST

http://localhost:8000

/api/documents/download-zip

Stream a ZIP archive of the original uploaded files for the given document IDs. Uses ZIP64 for large collections.

Download documents as ZIP › Request Body

document_ids

string[] · required

List of document IDs to include in the ZIP

Download documents as ZIP › Responses

ZIP archive streamed successfully

string

POST/api/documents/download-zip

curl --request POST \
  --url http://localhost:8000/api/documents/download-zip \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_ids": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "document_ids": [
    "string"
  ]
}

json

Example Responses

string

plain

application/zip

List pending documents

GET

http://localhost:8000

/api/documents/pending

List documents waiting to be processed

List pending documents › Responses

200

Pending documents retrieved

object[]

total

integer

GET/api/documents/pending

curl --request GET \
  --url http://localhost:8000/api/documents/pending

shell

Example Responses

{
  "documents": [
    {
      "id": "id",
      "filename": "filename",
      "file_type": "file_type",
      "file_size": 0,
      "upload_date": "2024-08-25T15:00:00Z",
      "processing_status": "pending",
      "chunk_count": 0,
      "collection_id": "collection_id",
      "source": "source",
      "content_status": "empty",
      "content_note": "content_note"
    }
  ],
  "total": 0
}

json

application/json

Process pending documents

POST

http://localhost:8000

/api/documents/process-pending

Start batch processing of all pending documents

Process pending documents › query Parameters

concurrency

integer

Number of documents to process concurrently

Default: 5

Process pending documents › Responses

200

Processing started

task_id

string

status

string

POST/api/documents/process-pending

curl --request POST \
  --url http://localhost:8000/api/documents/process-pending

shell

Example Responses

{
  "task_id": "task_id",
  "status": "status"
}

json

application/json

Health Custom Inputs

Upload a document

POST

http://localhost:8000

/api/upload

Upload a file for processing into the knowledge base

Upload a document › query Parameters

start_processing

boolean

Start processing immediately

Default: true

collection_id

string

Assign to a collection

source

string

Source identifier for the document (e.g. 'youtube-transcriber', 'slack-bot'). Defaults to 'upload'.

Default: upload

source_key

string · minLength: 1 · maxLength: 512

replace_document_id

string

Upload a document › Request Body

file

string · required

File to upload (PDF, TXT, MD, DOCX, XLSX)

Upload a document › Responses

Document uploaded, replaced in place (replaced: true), or left untouched because the bytes are identical to a completed document (unchanged: true).

document_id

string

id

string

Alias of document_id

filename

string

status

string · enum

Enum values:

pending

processing

extracting

completed

failed

message

string

source

string

Default: upload

replaced

boolean

An existing document (source_key / replace_document_id) was updated in place; document_id is unchanged. Always present.

unchanged

boolean

The bytes were identical to an already-completed document, so nothing was reprocessed. Always present.

Get document details

GET

http://localhost:8000

/api/documents/{document_id}

Get document details › path Parameters

document_id

string · required

Get document details › Responses

Document retrieved

id

string

filename

string

file_type

string

file_size

integer

upload_date

string · date-time

processing_status

string · enum

Enum values:

pending

processing

extracting

completed

failed

chunk_count

integer

collection_id

string

source

string

Origin of the document (e.g. 'upload', 'custom_input', or a custom source set via API)

content_status

string | null · enum

Enum values:

empty

encrypted

content_note

string

Human-readable explanation of content_status (empty string when unset)

Get original document file

GET

http://localhost:8000

/api/documents/{document_id}/file

Get original document file › path Parameters

document_id

string · required

Get original document file › Responses

Original file stream

No data returned

Download documents as ZIP

POST

http://localhost:8000

/api/documents/download-zip

Stream a ZIP archive of the original uploaded files for the given document IDs. Uses ZIP64 for large collections.

Download documents as ZIP › Request Body

document_ids

string[] · required

List of document IDs to include in the ZIP

Download documents as ZIP › Responses

ZIP archive streamed successfully

string

Process pending documents

POST

http://localhost:8000

/api/documents/process-pending

Start batch processing of all pending documents

Process pending documents › query Parameters

concurrency

integer

Number of documents to process concurrently

Default: 5

Process pending documents › Responses

200

Processing started

task_id

string

status

string