Binary Data (Blobs)
/_api/blob/:db/:collection
Upload a blob. The collection is automatically created if it does not exist.
Request Body Options
Requires multipart/form-data with a single field named file containing the binary data.
Response
/_api/blob/:db/:collection/:key
Download a blob.
Response
/_api/database/:db/document/:collection/:key
Delete a blob.
Uses the standard document deletion endpoint. This removes the metadata document and cleans up the associated binary data from storage.
Response
Resumable Chunked Upload
Upload large files in chunks with resume support. Sessions expire after 24 hours of inactivity.
/_api/blob/:db/:collection/upload
Create a new resumable upload session. The collection is auto-created as a blob collection if it does not exist.
Request Body
{
"total_size": 10485760, // Required. Total file size in bytes
"file_name": "video.mp4", // Optional. Original file name
"mime_type": "video/mp4", // Optional. MIME type
"chunk_size": 1048576 // Optional. Chunk size in bytes (default: 1MB)
}
Response
{
"upload_id": "019579a3-...", // Session ID for subsequent requests
"blob_key": "019579a3-...", // The blob key that will be used
"chunk_size": 1048576, // Negotiated chunk size
"total_chunks": 10 // Number of chunks to upload
}
/_api/blob/:db/:collection/upload/:upload_id/:chunk_index
Upload a single chunk. The body is raw binary data. Chunks can be uploaded in any order and re-uploaded (idempotent). Max body size: 6MB.
Request Body
Raw binary data (application/octet-stream). The chunk index is zero-based.
Response
{
"upload_id": "019579a3-...",
"chunk_index": 3,
"received_chunks": 4,
"total_chunks": 10,
"complete": false,
"missing_chunks": [4, 5, 6, 7, 8, 9]
}
/_api/blob/:db/:collection/upload/:upload_id/status
Get upload session status. Use this to resume an upload after a disconnect — the response tells you which chunks are still missing.
Response
{
"upload_id": "019579a3-...",
"blob_key": "019579a3-...",
"db": "_system",
"collection": "videos",
"file_name": "video.mp4",
"mime_type": "video/mp4",
"total_size": 10485760,
"chunk_size": 1048576,
"total_chunks": 10,
"received_chunks": 4,
"bytes_received": 4194304,
"complete": false,
"missing_chunks": [4, 5, 6, 7, 8, 9]
}
/_api/blob/:db/:collection/upload/:upload_id/complete
Finalize the upload. Promotes temporary chunks to permanent storage, creates the metadata document, and triggers cluster replication. Fails if any chunks are missing.
Response
{
"_key": "019579a3-...",
"name": "video.mp4",
"type": "video/mp4",
"size": 10485760,
"chunks": 10,
"created": "2026-03-13T14:00:00Z"
}
/_api/blob/:db/:collection/upload/:upload_id/abort
Cancel an upload session and clean up all temporary chunks from storage.
Response
{
"upload_id": "019579a3-...",
"status": "aborted"
}