Upload a file

POST /api/v1/files

Upload a file in one multipart request. The returned id is what you reference from agent tools ({ "documentIds": ["<file id>"] } on a query tool, etc.).

Files vs. Knowledge Base

/files is the simpler single-call alternative to the Knowledge Base upload flow. Both store into the same underlying documents table — a file uploaded via /files is queryable via the KB tool, and vice versa. Use /files when your client already has the bytes; use KB upload URL when you want direct browser-to-S3 upload.

Request

Multipart form fields:

Field	Type	Required	Notes
`file`	file	✓	The file. Max 5 MB. Extension must be one of: `.pdf`, `.docx`, `.doc`, `.txt`, `.json`, `.md`, `.csv`.
`retrievalMode`	string	—	`"chunked"` (default) or `"full_document"`.

Headers:

X-API-Key: zsk_...
Content-Type: multipart/form-data

Response

201 Created:

{
  "id":           "abc12345-...",
  "name":         "product-faq.pdf",
  "originalName": "product-faq.pdf",
  "bytes":        532187,
  "mimeType":     "application/pdf",
  "status":       "pending",
  "error":        null,
  "retrievalMode": "chunked",
  "totalChunks":  0,
  "createdAt":    "2026-06-16T10:00:00Z",
  "updatedAt":    "2026-06-16T10:00:00Z"
}

Field	Notes
`id`	The document UUID. Reference this in tool configs.
`status`	`pending` → `processing` → `completed` / `failed`. Poll via `GET /files/{file_id}`.
`totalChunks`	`0` until processing completes.

Examples

curl -X POST https://dashboard.zoxa.ai/api/v1/files \
  -H "X-API-Key: zsk_..." \
  -F "[email protected]" \
  -F "retrievalMode=chunked"

import fs from "node:fs";

const form = new FormData();
form.append(
  "file",
  new Blob([fs.readFileSync("product-faq.pdf")]),
  "product-faq.pdf",
);
form.append("retrievalMode", "chunked");

const res = await fetch("https://dashboard.zoxa.ai/api/v1/files", {
  method: "POST",
  headers: { "X-API-Key": "zsk_..." },
  body: form,
});
const file = await res.json();

import httpx

with open("product-faq.pdf", "rb") as fh:
    resp = httpx.post(
        "https://dashboard.zoxa.ai/api/v1/files",
        headers={"X-API-Key": "zsk_..."},
        files={"file": ("product-faq.pdf", fh, "application/pdf")},
        data={"retrievalMode": "chunked"},
    )
file = resp.json()

Errors

Status	`detail`	When
`400`	`"Filename is required"`	The multipart `file` part has no filename.
`400`	`"Invalid retrievalMode '...'"`	Not `chunked` or `full_document`.
`400`	`"Unsupported file type '.xyz'..."`	Extension not in the allow-list.
`400`	`"File exceeds maximum size of 5MB"`	Larger than the 5 MB cap.
`500`	`"Failed to upload file to storage"`	Storage backend rejected the write.

POST /files/text — inline text path
GET /files/{file_id} — poll status
Tool types — query — reference the id in a query tool

Request

Response

Examples

Errors

Related

On this page