API reference

Folders

A folder is a collection of documents plus the settings that decide how they are parsed, chunked and embedded. Everything retrieval-related starts here: you create a folder, upload files into it, and then either search it directly or attach it to an assistant.

Folders are called vectors on the wire

The endpoints live under /api/public/vectors — the original internal name for a collection. The desktop app calls the same object a folder.

List folders#

GET/api/public/vectorsAPI key

Every folder the key owner can access, newest first.

Query

limitinteger: How many to return, 1–200.Default: 50.
offsetinteger: Rows to skip, for paging.Default: 0.
searchstring: Case-insensitive filter on the folder name.

Shell

curl BOX_URL/api/public/vectors \
  -H "x-api-key: YOUR_API_KEY"

JSON

{
  "vectors": [
    {
      "id": "9c8a2b31-7f45-4d10-8e6a-1b3f0d2c4a58",
      "name": "Contracts 2026",
      "description": "Signed customer agreements",
      "iconName": "FileText",
      "accentColor": "#E0F2FE",
      "strategy": "CHUNK",
      "createdAt": "2026-05-14T08:22:10.114Z"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false }
}

This is where IDs come from

The id here is what you pass as vectorId in chat requests, as the path segment when uploading files, and in vectorIds when creating an assistant.

Create a folder#

POST/api/public/vectorsAPI key

Creates the folder, provisions its vector collection and its storage directory. The caller becomes its owner.

curl -X POST BOX_URL/api/public/vectors \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support tickets",
    "description": "Exported Zendesk tickets, refreshed nightly",
    "strategy": "CHUNK",
    "topK": 8,
    "iconName": "LifeBuoy",
    "accentColor": "#E0F2FE"
  }'

Request body

Field

namestringrequired: Display name. Max 200 characters.
descriptionstring: What the folder holds. Shown in the app and used as context when the AI decides which folder to search.
strategy"CHUNK" | "DOCUMENT" | "TABULAR": How documents are indexed — see strategies. Cannot be changed later.Default: "CHUNK".
resume"NONE" | "SHORT" | "MEDIUM" | "FULL": Generate a per-document summary at ingest time. Longer summaries cost more processing but improve retrieval on long documents.Default: "NONE".
topKinteger: How many passages retrieval returns by default when this folder is used in chat. 1–100.Default: 5.
filternumber: Minimum similarity score, 0–1. Raise it to trade recall for precision.Default: 0.
iconNamestring: Lucide icon name shown on the folder card.
accentColorstring: Hex tint for the folder card, e.g. #E0F2FE.
enableGraphRAGboolean: Build a knowledge graph of entities and relations alongside the vectors. Slower to ingest; much better at questions that span documents.Default: false.
enableTableExtractionboolean: Extract tables from PDFs into queryable structures.Default: false.
enableVisualAnalysisboolean: Render pages as images and index them. Needed for scans and diagrams.Default: false.
enableImageDescriptionboolean: Generate text descriptions for embedded images so they become searchable.Default: false.
pageLimitinteger: Stop parsing each document after this many pages.

Choosing a strategy

Strategy	Use it when
`CHUNK`	The default. Splits documents into passages and embeds each one. Best for question answering over reports, contracts, manuals and email.
`DOCUMENT`	Embeds whole files. Good for short, self-contained documents where a passage would lose the point — product sheets, CVs, single-page policies.
`TABULAR`	Loads spreadsheets and CSVs into SQL so the AI can aggregate and filter instead of guessing from text. Queried through chat, not through semantic search.

Strategy is fixed at creation

It decides where the data physically lives, so changing it later would leave the folder pointing at storage that was never provisioned. A PATCH that includes strategy is rejected with a 400 — create a new folder instead.

Response

JSON

{
  "vector": {
    "id": "3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21",
    "name": "Support tickets",
    "description": "Exported Zendesk tickets, refreshed nightly",
    "strategy": "CHUNK",
    "topK": 8,
    "embeddingProvider": "qwen",
    "pipelineVersion": "v2",
    "createdAt": "2026-08-03T09:41:07.882Z"
  }
}

201Folder created and ready to receive files.

Get a folder#

GET/api/public/vectors/:idAPI key

The folder with its full pipeline settings and a count of the documents in it.

JSON

{
  "vector": {
    "id": "3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21",
    "name": "Support tickets",
    "strategy": "CHUNK",
    "topK": 8,
    "filter": 0,
    "enableGraphRAG": false,
    "embeddingProvider": "qwen",
    "syncEnabled": false,
    "fileCount": 1284
  }
}

Update a folder#

PATCH/api/public/vectors/:idAPI key

Changes metadata and retrieval settings. Fields you leave out are untouched.

Shell

curl -X PATCH BOX_URL/api/public/vectors/3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topK": 12, "filter": 0.35 }'

Indexing settings apply going forward

Retrieval settings like topK and filter take effect immediately. Ingestion settings — enableTableExtraction, enableGraphRAG and the rest — only affect documents uploaded after the change. Re-upload existing files to apply them retroactively.

Delete a folder#

DELETE/api/public/vectors/:idAPI key

Removes the folder, its documents, its vectors, its knowledge graph and its stored files.

This cannot be undone

There is no soft delete and no trash. Everything indexed in the folder is destroyed, and any assistant that referenced it simply loses that source.

JSON

{
  "success": true,
  "id": "3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21",
  "details": {
    "pgvectorDeleted": true,
    "graphDocumentsDeleted": 1284,
    "graphEntitiesDeleted": 8931,
    "imagesDeleted": 402,
    "foldersDeleted": ["/dataai/3d7e1a04-25c9-4f6b-9a12-8e0c5b7d3f21"]
  },
  "errors": []
}

Deletion touches several storage systems. errors is non-empty when one of them failed while the rest succeeded — the folder row is gone either way, so treat entries there as cleanup to check, not as a failed call to retry.

Next steps#

Upload files into the folder so there is something to retrieve.
Search it directly if you want the passages without an LLM answer.
Attach it to an assistant so every conversation with that assistant can use it.