Uploads

Creates an empty file and returns a file_id to use for chunk uploads. Use this endpoint when uploading files via JSON (e.g. from MCP clients). After creating the session, send file data in chunks via PUT /uploads/{file_id}.

For direct file uploads, use POST /files (multipart/form-data) instead.

Appends a Base64-encoded chunk of data to an existing upload session. Repeat this request until all chunks have been sent. Each chunk must not exceed 5MB of the original (pre-encoded) data.

The response reflects the current total file size after each chunk is appended.

Idempotency

This endpoint is not idempotent. Calling it multiple times with the same chunk will append the data repeatedly, producing a corrupted file. If you are unsure whether a previous request succeeded (e.g. due to a network error or client-side retry), call GET /files/{file_id} first to check the current size before retrying.

Note for AI / MCP clients

If your MCP runtime returns a client-side error (such as a tool definition validation error) before sending the request, the underlying HTTP request may still have been transmitted in some implementations. Always verify the current size via GET /files/{file_id} before retrying — do not rely on the absence of a successful response to conclude that no data was sent.