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

Upload a document › Request Body

file

string · required

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

Upload a document › Responses

Document uploaded

id

string

filename

string

file_type

string

file_size

integer

upload_date

string · date-time

processing_status

string · enum

Enum values:

pending

processing

extracting_entities

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)

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

{
  "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"
}

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"
    }
  ],
  "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_entities

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)

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"
}

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"
    }
  ],
  "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

Upload a document › Request Body

file

string · required

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

Upload a document › Responses

Document uploaded

id

string

filename

string

file_type

string

file_size

integer

upload_date

string · date-time

processing_status

string · enum

Enum values:

pending

processing

extracting_entities

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)

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_entities

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)

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