I/O API specification reference

The I/O API provides high-throughput endpoints for working with multiple entries in a bucket using Batch Protocol v2. It is designed for batched reads, writes, label updates, and deletions across entries with minimal HTTP overhead.

Experimental

The I/O API is experimental and will be stabilized in the next releases.

The API uses the following endpoints:

• Write - write records to multiple entries in one request.
• Query + read - run a query across entries and stream results back in batches.
• Update - update labels for multiple records across entries.
• Remove - remove multiple records across entries.

Batch protocol v2

Batch Protocol v2 encodes record metadata in headers and concatenates record bodies without separators.

Metadata headers

• x-reduct-entries: comma-separated, percent-encoded entry names (index == position).
• x-reduct-start-ts: first timestamp in the batch (microseconds).
• x-reduct-labels (optional): comma-separated, percent-encoded label names (index == position).

Content is sorted by entry index in ascending order, then by timestamp (start + delta).

Per-record headers

Each record is described by one header:

x-reduct-<ENTRY-INDEX>-<TIME-DELTA-uS>: <HEADER-VALUE>

In error responses, the same suffix is used:

x-reduct-error-<ENTRY-INDEX>-<TIME-DELTA-uS>: <STATUS_CODE>,<ERROR_MESSAGE>

Header value format

The header value always starts with the record content-length (bytes) and may include a content-type and a label delta:

• "123": reuse previous content-type and labels for the entry.
• "123,<ct>": reuse previous labels; set content-type to <ct>.
• "123,,<label-delta>": reuse previous content-type; apply label delta.
• "123,<ct>,<label-delta>": set content-type and apply label delta.

Label delta sends only changed labels. Unset a label with k=. Unmentioned labels keep their previous value for the entry.

If x-reduct-labels is provided, label delta may use indexes instead of names (<IDX>=<VALUE>), where the index refers to the position in x-reduct-labels.

Example request (write)

This request writes three records to two entries (cam-1 and cam 2). The request body is the concatenation of record payloads in entry-index order, then by timestamp (hello + world + foo).

POST /api/v1/io/my-bucket/write HTTP/1.1
Host: localhost:8383
Authorization: Bearer <token>
Content-Type: application/octet-stream
Content-Length: 13
x-reduct-entries: cam-1,cam%202
x-reduct-start-ts: 1700000000000000
x-reduct-0-0: 5,text/plain,device=cam1
x-reduct-0-1000: 5
x-reduct-1-0: 3,text/plain,device=cam2

helloworldfoo

note

The Entry API batch endpoints (/api/v1/b/:bucket_name/:entry_name/batch) use an older batch format. See Batch protocol in the Entry API docs.

I/O API endpoints

📄️ Run query

HTTP endpoint to run a query across entries in a bucket and read results in batches.

📄️ Read data

HTTP endpoint to read batched query results across entries using Batch Protocol v2.

📄️ Write data

HTTP endpoint to write batched records to multiple entries using Batch Protocol v2.

📄️ Update data

HTTP endpoint to update labels for multiple records across entries using Batch Protocol v2.

📄️ Delete data

HTTP endpoint to remove multiple records across entries using Batch Protocol v2 header naming.