Documents

Upload a document, then read its tree, its pages and its metadata. List and delete documents, and build an outline later.

For authentication, errors and rate limits, see the API overview.

Upload a document

POST /doc · WRITE key

Uploads a file and starts reading its pages. The document is ready once its pages are read. Its outline is built after that, in the background.

NameTypeRequiredDefaultDescription
filefile (form)YesThe document: PDF, Word (.docx, .doc), PowerPoint (.pptx, .ppt), Excel (.xlsx, .xls), CSV, TXT or Markdown (.md, .markdown). Or a ZIP of them.
algorithmstring (form)NooutlineHow the tree is built: outline, flash or none. See Algorithm.
outline_modestring (form)NoparallelWith outline. parallel makes each heading a node of a flat tree. sequential nests the headings by level.
folder_idstring (form)NoThe folder to put it in.
collection_idstring (form)NoThe collection to put it in.
metadatastring (form)NoWith collection_id: your own fields, as a JSON object, such as {"year": 2024}. See Metadata.
waitinteger (form)No0Seconds, 0 to 60, to wait for the document to be completed or failed before answering.
if_add_node_summarystring (form)NoyesWith flash: yes writes a summary for each node.
if_add_doc_descriptionstring (form)NoyesWith flash: yes writes a description of the document.
if_add_node_textstring (form)NoyesWith flash: yes stores each node's text.
if_add_node_idstring (form)NoyesWith flash: yes numbers the nodes.
curl https://api.pageindex.ai/doc \
  -H "api_key: $PAGEINDEX_API_KEY" \
  -F "file=@2023-annual-report.pdf" \
  -F "collection_id=cm3ka1b7r0002l508x9w3e7tq" \
  -F 'metadata={"year": 2023}' \
  -F "wait=30"
{
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "name": "2023-annual-report.pdf",
  "status": "completed"
}
  • name is the stored name. A name already taken gets a numeric suffix, such as 2023-annual-report_1.pdf.
  • status is the document's status when the wait ends.
  • Uploading the same file to the same place again answers with the stored document and "duplicate": true, and is not charged.
StatusWhen
400No file name. A format that is not supported. An empty file. A file that is not a valid PDF. An encrypted PDF. A PDF with no pages, or only blank pages. metadata that is not a JSON object, or does not fit the schema. collection_id with folder_id or a ZIP.
402insufficient_credits: your balance does not cover the upload.
403subscription_required, or a key below WRITE.
404The folder or the collection does not exist.
413A ZIP over 500 MB.

SDK: Python PageIndexClient.submit_document(). JavaScript client.api.submitDocument().

Algorithm

algorithmWhat it doesPrice
outline (default)Builds the tree from the headings printed on the pages.$1 per 1,000 pages
flashBuilds the tree with PageIndex Flash, from the PDF's text layer. A PDF Flash cannot read, such as a scan, gets no tree.$1 per 1,000 pages
noneStores the pages without a tree.$0.10 per 1,000 pages

none is for the Page Search API and the Page Extract API. PageIndex Agent can still search and read such a document, but it cannot follow a tree. Build one later with Build a document's outline, at $1 per 1,000 pages, charged when it completes.

See Pricing.

ZIP files

A ZIP is unpacked into a new folder, named after the ZIP, inside folder_id or at the root. Its own folders become subfolders. The answer is 202:

{
  "root_folder_id": "cm3k8z0aa0000l508k2m4n6p8",
  "items": [
    {
      "path": "2024/report.pdf",
      "folder_id": "cm3k8z1bb0001l508q7r9s1t3",
      "file_name": "report.pdf",
      "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
      "status": "queued"
    }
  ],
  "skipped": [
    { "path": "notes/image.png", "reason": "unsupported_format" }
  ],
  "failed": []
}

Metadata

Metadata is your own fields on a document, to filter and sort by.

  • A flat JSON object: each value is a string, a number or a boolean.
  • Up to 16 fields. A name is 1 to 64 characters and does not start with $. A string is up to 512 characters.
  • Only a document in a collection has metadata. Until the collection declares a schema, it learns new fields from the documents.

See Collections with metadata and Folders and collections.

Get a document's tree

GET /doc/{doc_id} · READ key

Returns the document's status and, once it is completed, its tree. For the text of its pages, see Get page text.

NameTypeRequiredDefaultDescription
doc_idstring (path)YesThe document's id.
summaryboolean (query)NofalseInclude each node's summary, where the tree has them.
include_textboolean (query)NotrueInclude each node's text, where the tree has it.
curl https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f \
  -H "api_key: $PAGEINDEX_API_KEY"
{
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "status": "completed",
  "result": [
    {
      "title": "Financial Stability",
      "node_id": "0006",
      "page_index": 21,
      "start_index": 21,
      "end_index": 28,
      "nodes": [
        {
          "title": "Monitoring Financial Vulnerabilities",
          "node_id": "0007",
          "page_index": 22,
          "start_index": 22,
          "end_index": 27
        }
      ]
    }
  ],
  "index_status": "completed",
  "metadata": { "year": 2023 },
  "collection_id": "cm3ka1b7r0002l508x9w3e7tq"
}
FieldWhat it is
statusqueued, processing, completed or failed. result is there only when completed.
index_statusThe outline's status: queued, processing, completed, failed, or skipped for a document without a tree.
resultThe tree: each node has title, node_id, page_index (its first page), start_index, end_index, and its child nodes. With summary or include_text, also summary and text where the tree has them. A node whose summary covers only its opening pages has prefix_summary instead.
metadataYour own fields.
collection_idIts collection, or null.
StatusWhen
403The document is not yours.
404The document does not exist.

SDK: Python get_tree() and get_document_structure(). JavaScript client.api.getTree().

Get a document's details

GET /doc/{doc_id}/metadata · READ key

Returns the document's name, status, size, place and metadata, without its tree.

NameTypeRequiredDefaultDescription
doc_idstring (path)YesThe document's id.
curl https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f/metadata \
  -H "api_key: $PAGEINDEX_API_KEY"
{
  "id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "name": "2023-annual-report.pdf",
  "description": null,
  "status": "completed",
  "indexStatus": "completed",
  "createdAt": "2026-11-18T09:30:12",
  "pageNum": 64,
  "folderId": null,
  "collectionId": "cm3ka1b7r0002l508x9w3e7tq",
  "metadata": { "year": 2023 },
  "path": null
}
  • This endpoint names its fields in camelCase. GET /doc/{doc_id} uses snake_case.
  • path is the folder path and file name, such as Reports/2023/2023-annual-report.pdf. It is null for a document in a collection.
StatusWhen
403The document is not yours.
404The document does not exist.

SDK: Python get_document(). JavaScript client.api.getDocument().

Replace a document's metadata

PUT /doc/{doc_id}/metadata · WRITE key

Replaces the document's metadata with the object you send. Send {} to clear it.

NameTypeRequiredDefaultDescription
doc_idstring (path)YesThe document's id.
bodyobject (JSON)YesThe whole new metadata. See Metadata.
curl -X PUT https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f/metadata \
  -H "api_key: $PAGEINDEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year": 2023, "region": "EU"}'
{
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "metadata": { "year": 2023, "region": "EU" }
}
StatusWhen
400The metadata breaks the rules, or does not fit the schema.
403The document is not yours.
404The document does not exist.

SDK: Python update_document(doc_id, metadata=...). It changes only the keys you name.

Delete a document

DELETE /doc/{doc_id} · WRITE key

Deletes the document and everything stored for it.

NameTypeRequiredDefaultDescription
doc_idstring (path)YesThe document's id.
curl -X DELETE https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f \
  -H "api_key: $PAGEINDEX_API_KEY"
{ "message": "Document deleted successfully." }
StatusWhen
403The document is not yours.
404The document does not exist.
409The document is still queued or processing. Try again when it is done.

SDK: Python delete_document(). JavaScript client.api.deleteDocument().

List documents

GET /docs · READ key

Lists your documents, newest first.

NameTypeRequiredDefaultDescription
limitinteger (query)No50Documents to return, 1 to 10,000. With group_by: groups to return, default 1,000.
offsetinteger (query)No0Documents to skip. Ignored with group_by.
namestring (query)NoAn exact document name. Returns at most one document.
folder_idstring (query)NoA folder's id, or root for documents in no folder.
recursiveboolean (query)NofalseWith folder_id, also list the documents in its subfolders.
collection_idstring (query)NoList one collection's documents.
metadata_filterstring (query)NoA JSON filter on metadata. Operators: $eq, $ne, $in, $gt, $gte, $lt, $lte, $and, $or.
sortstring (query)Nonewest firstJSON: up to 5 metadata fields, 1 ascending, -1 descending, such as {"year": -1}.
aggregatesstring (query)NoJSON: up to 10 of $count, $sum, $avg, $max, $min over all matching documents, such as {"n": {"$count": {}}}.
group_bystring (query)NoJSON: a list of up to 5 metadata fields, such as ["region", "year"].
curl -G https://api.pageindex.ai/docs \
  -H "api_key: $PAGEINDEX_API_KEY" \
  --data-urlencode "limit=10" \
  --data-urlencode "collection_id=cm3ka1b7r0002l508x9w3e7tq" \
  --data-urlencode 'metadata_filter={"year": {"$gte": 2023}}'
{
  "documents": [
    {
      "id": "pi-cm3k9x2qv0001l50856dh4a2f",
      "name": "2023-annual-report.pdf",
      "description": null,
      "status": "completed",
      "createdAt": "2026-11-18T09:30:12",
      "pageNum": 64,
      "folderId": null,
      "metadata": { "year": 2023 },
      "collectionId": "cm3ka1b7r0002l508x9w3e7tq",
      "path": null
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

With aggregates, the answer adds aggregates, such as {"n": 1}. With group_by, it lists groups in place of documents:

{
  "groups": [
    { "region": "EU", "year": 2023, "n": 12 },
    { "region": "US", "year": 2023, "n": 9 }
  ],
  "total": 2,
  "truncated": false
}
StatusWhen
400A parameter that is not valid JSON, or a filter, sort or aggregate that is not valid. group_by without aggregates. collection_id with folder_id or recursive.
404The folder or the collection does not exist.

SDK: Python list_documents(). JavaScript client.api.listDocuments().

Build a document's outline

POST /doc/{doc_id}/index · WRITE key

Builds the outline of a document stored without one, such as one uploaded with algorithm=none. It is built as algorithm=outline builds it.

The price is $1 per 1,000 pages. It is held when you ask, and charged when the outline is built.

NameTypeRequiredDefaultDescription
doc_idstring (path)YesThe document's id.
curl -X POST https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f/index \
  -H "api_key: $PAGEINDEX_API_KEY"
{
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "index_status": "queued"
}

Read index_status from Get a document's tree until it is completed.

StatusWhen
402insufficient_credits: your balance does not cover the outline.
403The document is not yours.
404The document does not exist.
409The document's pages are not ready yet.
503The build could not be queued. Try again.

SDK: Python build_outline_index(). It waits for the outline by default.

Get page text

GET /doc/{doc_id}/text · READ key

Returns the text of the document's pages, one string a page.

NameTypeRequiredDefaultDescription
doc_idstring (path)YesThe document's id.
startinteger (query)No1The first page.
endinteger (query)Nolast pageThe last page, included.
curl "https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f/text?start=3&end=4" \
  -H "api_key: $PAGEINDEX_API_KEY"
{
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "pages": [3, 4],
  "text": ["## Letter to shareholders\n\n...", "## Highlights\n\n..."]
}
StatusWhen
403The document is not yours.
404The document does not exist, or has no page text yet.