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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
file | file (form) | Yes | The document: PDF, Word (.docx, .doc), PowerPoint (.pptx, .ppt), Excel (.xlsx, .xls), CSV, TXT or Markdown (.md, .markdown). Or a ZIP of them. | |
algorithm | string (form) | No | outline | How the tree is built: outline, flash or none. See Algorithm. |
outline_mode | string (form) | No | parallel | With outline. parallel makes each heading a node of a flat tree. sequential nests the headings by level. |
folder_id | string (form) | No | The folder to put it in. | |
collection_id | string (form) | No | The collection to put it in. | |
metadata | string (form) | No | With collection_id: your own fields, as a JSON object, such as {"year": 2024}. See Metadata. | |
wait | integer (form) | No | 0 | Seconds, 0 to 60, to wait for the document to be completed or failed before answering. |
if_add_node_summary | string (form) | No | yes | With flash: yes writes a summary for each node. |
if_add_doc_description | string (form) | No | yes | With flash: yes writes a description of the document. |
if_add_node_text | string (form) | No | yes | With flash: yes stores each node's text. |
if_add_node_id | string (form) | No | yes | With 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"
}
nameis the stored name. A name already taken gets a numeric suffix, such as2023-annual-report_1.pdf.statusis 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.
| Status | When |
|---|---|
| 400 | No 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. |
| 402 | insufficient_credits: your balance does not cover the upload. |
| 403 | subscription_required, or a key below WRITE. |
| 404 | The folder or the collection does not exist. |
| 413 | A ZIP over 500 MB. |
SDK: Python PageIndexClient.submit_document(). JavaScript client.api.submitDocument().
Algorithm
algorithm | What it does | Price |
|---|---|---|
outline (default) | Builds the tree from the headings printed on the pages. | $1 per 1,000 pages |
flash | Builds 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 |
none | Stores 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
doc_id | string (path) | Yes | The document's id. | |
summary | boolean (query) | No | false | Include each node's summary, where the tree has them. |
include_text | boolean (query) | No | true | Include 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"
}
| Field | What it is |
|---|---|
status | queued, processing, completed or failed. result is there only when completed. |
index_status | The outline's status: queued, processing, completed, failed, or skipped for a document without a tree. |
result | The 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. |
metadata | Your own fields. |
collection_id | Its collection, or null. |
| Status | When |
|---|---|
| 403 | The document is not yours. |
| 404 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
doc_id | string (path) | Yes | The 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. pathis the folder path and file name, such asReports/2023/2023-annual-report.pdf. It isnullfor a document in a collection.
| Status | When |
|---|---|
| 403 | The document is not yours. |
| 404 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
doc_id | string (path) | Yes | The document's id. | |
| body | object (JSON) | Yes | The 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" }
}
| Status | When |
|---|---|
| 400 | The metadata breaks the rules, or does not fit the schema. |
| 403 | The document is not yours. |
| 404 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
doc_id | string (path) | Yes | The document's id. |
curl -X DELETE https://api.pageindex.ai/doc/pi-cm3k9x2qv0001l50856dh4a2f \
-H "api_key: $PAGEINDEX_API_KEY"
{ "message": "Document deleted successfully." }
| Status | When |
|---|---|
| 403 | The document is not yours. |
| 404 | The document does not exist. |
| 409 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer (query) | No | 50 | Documents to return, 1 to 10,000. With group_by: groups to return, default 1,000. |
offset | integer (query) | No | 0 | Documents to skip. Ignored with group_by. |
name | string (query) | No | An exact document name. Returns at most one document. | |
folder_id | string (query) | No | A folder's id, or root for documents in no folder. | |
recursive | boolean (query) | No | false | With folder_id, also list the documents in its subfolders. |
collection_id | string (query) | No | List one collection's documents. | |
metadata_filter | string (query) | No | A JSON filter on metadata. Operators: $eq, $ne, $in, $gt, $gte, $lt, $lte, $and, $or. | |
sort | string (query) | No | newest first | JSON: up to 5 metadata fields, 1 ascending, -1 descending, such as {"year": -1}. |
aggregates | string (query) | No | JSON: up to 10 of $count, $sum, $avg, $max, $min over all matching documents, such as {"n": {"$count": {}}}. | |
group_by | string (query) | No | JSON: 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
}
| Status | When |
|---|---|
| 400 | A 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. |
| 404 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
doc_id | string (path) | Yes | The 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.
| Status | When |
|---|---|
| 402 | insufficient_credits: your balance does not cover the outline. |
| 403 | The document is not yours. |
| 404 | The document does not exist. |
| 409 | The document's pages are not ready yet. |
| 503 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
doc_id | string (path) | Yes | The document's id. | |
start | integer (query) | No | 1 | The first page. |
end | integer (query) | No | last page | The 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..."]
}
| Status | When |
|---|---|
| 403 | The document is not yours. |
| 404 | The document does not exist, or has no page text yet. |