Folders and collections
A document sits in the folder tree, or in exactly one collection. Folders nest, and suit PageIndex Agent. Collections are flat, and suit all three products. Metadata lives only in collections.
To put a document in one, pass folder_id or collection_id when you upload it. For how to choose, see Collections with metadata and File system with folders.
Folders
Create a folder
POST /folder · WRITE key
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
name | string (JSON) | Yes | The folder's name. | |
description | string (JSON) | No | A description of the folder. | |
parent_folder_id | string (JSON) | No | The folder to create it in. At the root when left out. |
A name:
- is up to 180 bytes in UTF-8;
- does not hold
/ \ : * ? " < >, a vertical bar, or a control character; - does not end with a period;
- is not already taken in the same place.
curl https://api.pageindex.ai/folder \
-H "api_key: $PAGEINDEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Reports", "description": "Annual reports"}'
{
"folder": {
"id": "cm3k8z0aa0000l508k2m4n6p8",
"name": "Reports",
"description": "Annual reports",
"parent_folder_id": null,
"created_at": "2026-11-18 09:30:12",
"file_count": 0,
"children_count": 0
}
}
| Status | When |
|---|---|
| 400 | The name breaks the rules or is taken. The parent folder does not exist or is not yours. |
SDK: Python create_folder(). JavaScript client.api.createFolder().
List folders
GET /folders · READ key
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
parent_folder_id | string (query) | No | root for the folders at the root, a folder's id for its subfolders. Every folder when left out. |
curl "https://api.pageindex.ai/folders?parent_folder_id=root" \
-H "api_key: $PAGEINDEX_API_KEY"
{
"folders": [
{
"id": "cm3k8z0aa0000l508k2m4n6p8",
"name": "Reports",
"description": "Annual reports",
"parent_folder_id": null,
"created_at": "2026-11-18 09:30:12",
"updated_at": "2026-11-18 09:30:12",
"file_count": 3,
"children_count": 1
}
],
"total": 1
}
| Status | When |
|---|---|
| 404 | The parent folder does not exist. |
SDK: Python list_folders(). JavaScript client.api.listFolders().
Delete a folder
DELETE /folder/{folder_id} · WRITE key
Deletes a folder, with every document and subfolder in it.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
folder_id | string (path) | Yes | The folder's id. |
curl -X DELETE https://api.pageindex.ai/folder/cm3k8z0aa0000l508k2m4n6p8 \
-H "api_key: $PAGEINDEX_API_KEY"
{
"folder_id": "cm3k8z0aa0000l508k2m4n6p8",
"deleted": true,
"deleted_documents": 3,
"deleted_folders": 2,
"surviving_folders": 0
}
When only part of a folder is deleted, the error's code is folder_delete_incomplete. Its detail holds deleted_documents, deleted_folders and surviving_folders.
| Status | When |
|---|---|
| 404 | The folder does not exist. |
| 409 | The folder is not fully deleted: some documents in it are still queued or processing. |
| 500 | A server error stopped the delete partway. Try again to delete what is left. |
Collections
Create a collection
POST /collection · WRITE key
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
name | string (JSON) | Yes | 1 to 255 characters, not taken by another of your collections. | |
description | string (JSON) | No | A description of the collection. |
curl https://api.pageindex.ai/collection \
-H "api_key: $PAGEINDEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Invoices", "description": "Supplier invoices, 2024 on"}'
{
"collection": {
"id": "cm3ka1b7r0002l508x9w3e7tq",
"name": "Invoices",
"description": "Supplier invoices, 2024 on"
}
}
| Status | When |
|---|---|
| 400 | The name is empty or longer than 255 characters. |
| 409 | You have a collection with this name already. |
SDK: Python create_collection().
List collections
GET /collections · READ key
Lists your collections, newest first.
curl https://api.pageindex.ai/collections \
-H "api_key: $PAGEINDEX_API_KEY"
{
"collections": [
{
"id": "cm3ka1b7r0002l508x9w3e7tq",
"name": "Invoices",
"description": "Supplier invoices, 2024 on",
"metadata_schema": null,
"created_at": "2026-11-18T09:31:40",
"document_count": 42
}
],
"total": 1
}
SDK: Python list_collections() and get_collection().
Delete a collection
DELETE /collection/{collection_id} · WRITE key
Deletes a collection, with every document in it.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
collection_id | string (path) | Yes | The collection's id. |
curl -X DELETE https://api.pageindex.ai/collection/cm3ka1b7r0002l508x9w3e7tq \
-H "api_key: $PAGEINDEX_API_KEY"
{
"collection_id": "cm3ka1b7r0002l508x9w3e7tq",
"deleted": true,
"deleted_documents": 42
}
When the collection is not fully deleted, the error's code is collection_delete_incomplete. Its detail holds deleted_documents.
| Status | When |
|---|---|
| 404 | The collection does not exist. |
| 409 | Some documents in it are still queued or processing. The others are deleted, and the collection is kept. Try again later. |
| 500 | A server error stopped the delete partway. Try again to delete what is left. |
SDK: Python delete_collection().
Declare a collection's metadata schema
PUT /collection/{collection_id}/metadata/schema · WRITE key
Declares the metadata fields for a collection's documents. Until you declare one, a collection learns its fields from the metadata you upload, up to 32 fields, each typed by its first value.
A schema is set once. To change it, delete it, then declare it again. Declaring it removes, from the collection's documents, the metadata fields it does not declare, or whose values have the wrong type.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
collection_id | string (path) | Yes | The collection's id. | |
fields | object (JSON) | Yes | Each field's name, with its type (string, number or boolean) and an optional description. Up to 16 KB in all. |
curl -X PUT https://api.pageindex.ai/collection/cm3ka1b7r0002l508x9w3e7tq/metadata/schema \
-H "api_key: $PAGEINDEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fields": {"supplier": {"type": "string"}, "total": {"type": "number"}}}'
{
"collection_id": "cm3ka1b7r0002l508x9w3e7tq",
"schema": {
"fields": {
"supplier": { "type": "string" },
"total": { "type": "number" }
}
}
}
| Status | When |
|---|---|
| 400 | The schema is not valid. |
| 404 | The collection does not exist. |
| 409 | The collection has a declared schema already. Delete it first. |
SDK: Python create_metadata_schema(collection_id=..., fields=...).
Get a collection's metadata schema
GET /collection/{collection_id}/metadata/schema · READ key
Returns the collection's schema, declared or learned, with the values its documents hold. A number field gives its least and greatest values. A string field gives its 20 commonest values.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
collection_id | string (path) | Yes | The collection's id. | |
metadata_filter | string (query) | No | A JSON filter, as for List documents. Counts only the documents it matches. |
curl https://api.pageindex.ai/collection/cm3ka1b7r0002l508x9w3e7tq/metadata/schema \
-H "api_key: $PAGEINDEX_API_KEY"
{
"collection_id": "cm3ka1b7r0002l508x9w3e7tq",
"documents": 42,
"schema": {
"fields": {
"supplier": {
"type": "string",
"documents": 40,
"values": [
{ "value": "Acme GmbH", "documents": 12 },
{ "value": "Globex", "documents": 9 }
]
},
"total": { "type": "number", "documents": 41, "min": 120.5, "max": 98000 }
}
}
}
documentsat the top counts the collection's documents. In a field, it counts those that hold the field.- A learned schema has
"learned": true.schemaisnullwhen there is none yet.
| Status | When |
|---|---|
| 400 | metadata_filter is not valid. |
| 404 | The collection does not exist. |
SDK: Python get_metadata_schema(collection_id=...).
Delete a collection's metadata schema
DELETE /collection/{collection_id}/metadata/schema · WRITE key
Replaces the declared schema with one learned from the documents' metadata. The documents keep their metadata.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
collection_id | string (path) | Yes | The collection's id. |
curl -X DELETE https://api.pageindex.ai/collection/cm3ka1b7r0002l508x9w3e7tq/metadata/schema \
-H "api_key: $PAGEINDEX_API_KEY"
{ "collection_id": "cm3ka1b7r0002l508x9w3e7tq", "deleted": true }
| Status | When |
|---|---|
| 404 | The collection does not exist. |
SDK: Python delete_metadata_schema(collection_id=...).