Documents API: upload and manage files

The Documents API manages files in your cf0 research workspace. Uploaded files are stored in cf0’s document store and made available to the AI in your Lab sessions. You can also share documents across your organisation. All Documents endpoints are prefixed with /api/documents.

Supported file types

Extension	MIME type
`pdf`	`application/pdf`
`docx`	Word document
`xlsx`	Excel spreadsheet
`csv`	`text/csv`
`pptx`	PowerPoint presentation
`png`, `jpg`, `jpeg`	Images
`txt`	Plain text
`md`	Markdown
`html`	HTML

Maximum file size: 50 MB.

Upload a document

POST /api/documents/upload

Upload a file to your personal document store. Accepts multipart/form-data.

Scanned PDFs are automatically queued for OCR processing after upload. The status field in the response reflects the current processing state.

Form fields

file

required

The file to upload.

entity

string

Optional entity name or ticker to associate the document with (e.g. "NVDA").

Response

Upload returns immediately with a job handle — the actual ingestion (text extraction, OCR, indexing) runs asynchronously. Poll GET /api/documents/{doc_id}/status until status: "ready" before using the document in Lab.

boolean

Always true if the upload was accepted.

doc_id

string

Document ID. Use this to poll status, fetch content, or reference the document in Lab.

workflow_id

string

Identifier for the async ingestion workflow.

run_id

string

Identifier for this specific workflow run.

curl -X POST https://api.cf0.ai/api/documents/upload \
  -H "Authorization: Bearer <your-token>" \
  -F "[email protected]" \
  -F "entity=NVDA"

Example response:

{
  "ok": true,
  "doc_id": "a1b2c3d4e5f6g7h8",
  "workflow_id": "wf-doc-ingest-9p7q3",
  "run_id": "run-2026-05-17T10-23-00Z-xyz"
}

Poll status

GET /api/documents/{doc_id}/status

Returns the current ingestion state. Poll every 1–3 seconds until status is "ready" (or "failed").

doc_id

string

Document ID.

status

string

"queued", "running", "ready", or "failed".

filename

string

Original filename.

file_type

string

Detected file extension (available once status is "ready").

error

string

Failure reason (only present when status is "failed").

curl https://api.cf0.ai/api/documents/a1b2c3d4e5f6g7h8/status \
  -H "Authorization: Bearer <your-token>"

This is a breaking change from earlier API versions, which returned the full document object synchronously. Clients on the old contract ({ id, filename, file_type, ... }) need to switch to { ok, doc_id, ... } plus polling.

List documents

GET /api/documents/

Returns all documents uploaded by the authenticated user.

Response

documents

array

Array of document objects. Each includes:

id — document ID
filename — original filename
file_type — file extension
size_bytes — file size in bytes
status — "ready", "needs_ocr", or "ocr_running"
created_at — upload timestamp
page_count — page count (PDF only)
sheet_names — sheet names (XLSX only)

curl https://api.cf0.ai/api/documents/ \
  -H "Authorization: Bearer <your-token>"

Search documents

GET /api/documents/search

Search your documents by entity name or filename.

Query parameters

string

required

Search query. Minimum 1 character.

curl "https://api.cf0.ai/api/documents/search?q=nvidia" \
  -H "Authorization: Bearer <your-token>"

Get document content (preview)

GET /api/documents/{doc_id}/content

Returns the document content suitable for preview.

CSV / XLSX: returns structured table data with columns and rows
TXT / MD / HTML: returns raw content string
PDF / other: returns any extracted text stored at ingest time

Response

string

Document ID.

filename

string

Filename.

file_type

string

File type.

content

string

Extracted text content (non-tabular formats).

table

object

Structured table data for CSV/XLSX. Contains a sheets array, each with name, columns, and rows. Capped at 500 data rows per sheet.

curl https://api.cf0.ai/api/documents/a1b2c3d4e5f6g7h8/content \
  -H "Authorization: Bearer <your-token>"

Download raw file

GET /api/documents/{doc_id}/file

Download the original file bytes with the correct Content-Type. Use this for rendering PDFs in a viewer or displaying images. The response includes:

Content-Type — the detected MIME type
Content-Disposition: inline; filename="..." — for direct browser display
Cache-Control: private, max-age=3600

curl https://api.cf0.ai/api/documents/a1b2c3d4e5f6g7h8/file \
  -H "Authorization: Bearer <your-token>" \
  -o downloaded.pdf

List documents for an entity

GET /api/documents/entity/{entity_id}

Returns all documents associated with a specific entity (e.g. company ticker or ID).

Delete a document

DELETE /api/documents/{doc_id}

Permanently deletes a document from storage.

success

boolean

true if the document was deleted.

curl -X DELETE https://api.cf0.ai/api/documents/a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer <your-token>"

Shared documents

cf0 supports an org-level shared document library. Members can request to share their personal documents with the organisation; admins approve or deny these requests.

List shared documents

GET /api/documents/shared

Returns active shared documents for the authenticated user’s organisation.

tag

string

Filter by tag.

POST /api/documents/share-request

Request that one of your documents be shared with the organisation. Requires the doc_id as a form field.

GET /api/documents/share-requests/mine

Returns all share requests submitted by the authenticated user.

Admin: list pending requests

GET /api/documents/share-requests/pending

Requires org admin role. Returns all pending share requests for the organisation.

Admin: approve a request

POST /api/documents/share-requests/{request_id}/approve

Copies the document to shared org storage and marks the request as approved.

Admin: deny a request

POST /api/documents/share-requests/{request_id}/deny

Marks the request as denied. Optionally accepts a deny_reason form field.

Admin: upload directly to shared

POST /api/documents/upload-shared

Org admins can upload files directly to the shared document library without going through the approval flow. Accepts multipart/form-data with file and optional tags (comma-separated string).

Admin: revoke a shared document

DELETE /api/documents/shared/{doc_id}

Revokes a shared document — removes the file from shared storage and marks the record as revoked.

Overview

Endpoints

Documents API: upload and manage files

Supported file types

Upload a document

Form fields

Response

Poll status

List documents

Response

Search documents

Query parameters

Get document content (preview)

Response

Download raw file

List documents for an entity

Delete a document

Shared documents

List shared documents

Admin: list pending requests

Admin: approve a request

Admin: deny a request

Admin: upload directly to shared

Admin: revoke a shared document

Overview

Endpoints

Documentation Index

​Supported file types

​Upload a document

​Form fields

​Response

​Poll status

​List documents

​Response

​Search documents

​Query parameters

​Get document content (preview)

​Response

​Download raw file

​List documents for an entity

​Delete a document

​Shared documents

​List shared documents

​Request sharing

​List your share requests

​Admin: list pending requests

​Admin: approve a request

​Admin: deny a request

​Admin: upload directly to shared

​Admin: revoke a shared document

Supported file types

Upload a document

Form fields

Response

Poll status

List documents

Response

Search documents

Query parameters

Get document content (preview)

Response

Download raw file

List documents for an entity

Delete a document

Shared documents

List shared documents

Request sharing

List your share requests

Admin: list pending requests

Admin: approve a request

Admin: deny a request

Admin: upload directly to shared

Admin: revoke a shared document