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

NameTypeRequiredDefaultDescription
namestring (JSON)YesThe folder's name.
descriptionstring (JSON)NoA description of the folder.
parent_folder_idstring (JSON)NoThe 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
  }
}
StatusWhen
400The 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

NameTypeRequiredDefaultDescription
parent_folder_idstring (query)Noroot 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
}
StatusWhen
404The 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.

NameTypeRequiredDefaultDescription
folder_idstring (path)YesThe 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.

StatusWhen
404The folder does not exist.
409The folder is not fully deleted: some documents in it are still queued or processing.
500A server error stopped the delete partway. Try again to delete what is left.

Collections

Create a collection

POST /collection · WRITE key

NameTypeRequiredDefaultDescription
namestring (JSON)Yes1 to 255 characters, not taken by another of your collections.
descriptionstring (JSON)NoA 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"
  }
}
StatusWhen
400The name is empty or longer than 255 characters.
409You 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.

NameTypeRequiredDefaultDescription
collection_idstring (path)YesThe 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.

StatusWhen
404The collection does not exist.
409Some documents in it are still queued or processing. The others are deleted, and the collection is kept. Try again later.
500A 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.

NameTypeRequiredDefaultDescription
collection_idstring (path)YesThe collection's id.
fieldsobject (JSON)YesEach 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" }
    }
  }
}
StatusWhen
400The schema is not valid.
404The collection does not exist.
409The 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.

NameTypeRequiredDefaultDescription
collection_idstring (path)YesThe collection's id.
metadata_filterstring (query)NoA 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 }
    }
  }
}
  • documents at the top counts the collection's documents. In a field, it counts those that hold the field.
  • A learned schema has "learned": true. schema is null when there is none yet.
StatusWhen
400metadata_filter is not valid.
404The 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.

NameTypeRequiredDefaultDescription
collection_idstring (path)YesThe 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 }
StatusWhen
404The collection does not exist.

SDK: Python delete_metadata_schema(collection_id=...).