Upload Files

Endpoint

POST /api/public/vectors/:id/files

The :id is the folder (vector) ID. Get it from List Folders. The request must be multipart/form-data with the file in a field namedfile.

Upload a file

curl -X POST BOX_URL/api/public/vectors/550e8400-e29b-41d4-a716-446655440000/files \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/report.pdf"

Request

Send one file per request as multipart/form-data.

Response

A successful upload returns 202 Accepted -- the file is saved and queued for ingestion (indexing happens in the background, it is not finished when the request returns).

{
  "status": "ok",
  "message": "File queued for ingestion pipeline",
  "collection": "550e8400-e29b-41d4-a716-446655440000",
  "files": [
    {
      "filename": "report.pdf",
      "originalFilename": "report.pdf",
      "client_id": "report-2026-q4",
      "path": "/data/dataai/550e8400-.../report.pdf",
      "size": 248173,
      "mimetype": "application/pdf",
      "relativePath": "550e8400-e29b-41d4-a716-446655440000/report.pdf"
    }
  ],
  "task_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

Upload into a sub-folder

Pass relativePath to place the file in a nested sub-folder. The last segment is treated as the filename, and any missing folders are created automatically.

curl -X POST BOX_URL/api/public/vectors/550e8400-e29b-41d4-a716-446655440000/files \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./q4-results.pdf" \
  -F "relativePath=reports/2026/q4.pdf"

Supported file types

Most folders use the full ingestion pipeline, which accepts a wide range of formats:

• Documents: pdf, doc, docx, rtf, odt, ppt, pptx
• Spreadsheets: xlsx, xls, ods, csv
• Text & markup: txt, md, markdown, html, json, xml
• Email: msg, p7m
• Images (OCR): png, jpg, jpeg, gif, webp, bmp, tiff
• Source code & config: most common languages and config formats (py, js, ts, java, go, rs, sql, yaml, toml, and more)

The maximum size is 1 GiB per file. Oversized and unsupported file types are rejected with422. Some folders are configured for a lightweight pipeline that only accepts PDF and image files -- in that case other formats are rejected.

List files in a folder

List the files in a folder and their ingestion status. Use this to confirm an upload finished indexing (status: "completed").

GET /api/public/vectors/:id/files

Query parameters

Response

{
  "collection": "550e8400-e29b-41d4-a716-446655440000",
  "total": 12,
  "limit": 100,
  "offset": 0,
  "files": [
    {
      "id": "f1e2d3c4-...",
      "name": "report.pdf",
      "folder": "reports/2026",
      "relativePath": "550e8400-.../reports/2026/report.pdf",
      "size": 248173,
      "status": "completed",
      "phase": "done",
      "progress": 100,
      "error": null,
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:35:00Z"
    }
  ]
}

Get, download, replace & delete a file

All of these are scoped to a single file by its fileId (from the list above).

Get file metadata

GET /api/public/vectors/:id/files/:fileId

Returns { "file": { ... } } with the same fields as a list entry.

Download file contents

curl BOX_URL/api/public/vectors/:id/files/:fileId/content \
  -H "x-api-key: YOUR_API_KEY" \
  -o report.pdf

Streams the raw bytes with a Content-Disposition filename. Files stored only in the cloud cannot be downloaded and return 415.

Replace a file

Uploads a new version in place: the old file (and its index data) is removed and the replacement is re-ingested into the same sub-folder. Returns 202 Accepted, like an upload.

curl -X PUT BOX_URL/api/public/vectors/:id/files/:fileId \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/report-v2.pdf"

Delete a file

curl -X DELETE BOX_URL/api/public/vectors/:id/files/:fileId \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "status": "ok",
  "deleted": true,
  "file_id": "f1e2d3c4-...",
  "errors": []
}

Errors