Wire Format

The compact wire format is a strict binary upload contract used by the official Honch SDKs and accepted by Capture. It produces smaller payloads than JSON and is designed for one chunk transport that works across direct HTTP, relay, BLE, and gateway flows.

For most integrations you should use the HTTP JSON API instead. JSON expands into the exact same canonical event as the binary format, so you give up nothing on the analytics side, and it is far easier to build and debug. Reach for the wire format only when the device transport is severely bandwidth- or power-constrained, where every byte and wakeup matters.

This page is an orientation. The full byte grammar — header bits, varint encoding, the string table, value tags, and CRC — is defined in the canonical spec: Compact Wire Format v2.

When To Use It

Endpoint

POST https://i.honch.io/capture
Content-Type: application/vnd.honch.chunk
X-Honch-Project-Key: <project_api_key>
X-Honch-Stream-Id: <stream_id>        # required for multi-chunk HTTP uploads

This is the same URL the JSON path uses (aliases /e and /chunks also accept it). Capture branches on the Content-Type. The project key is a transport credential and is not encoded inside the device message body. Content-Encoding is not allowed on this binary path. X-Honch-Stream-Id must be present and at most 128 bytes for any multi-frame upload; a missing or oversized stream id is rejected with 400.

Chunk Frame And Compact Message

The format has two layers:

• Chunk frame — the transport envelope. The request body is exactly one frame. A frame carries a header byte (protocol version, source type, continuation/more bits), a message id, optional offset or total length, the payload bytes, and a trailing CRC16 on final frames.
• Compact message — the payload assembled from one or more frames. It encodes a string table, the device context (the same promoted keys as the JSON path: distinct_id, $device_id, and so on), and the event batch with delta-encoded timestamps and tagged property values.

A direct upload that fits in one request sends a single final frame. Constrained links split the same compact message into an init frame plus continuation frames, which Capture reassembles by stream id and message id before decoding. Once decoded, a compact message expands into the identical canonical events the JSON path produces.

The header's source type distinguishes what the frame carries: source type 0 is an event batch (the compact message above); source type 1 is a raw coredump blob (the ESP-IDF crash pipeline) streamed in the same CRC-checked, resumable chunks. Coredump frames are reassembled by stream id (the crash's crash_id) and stored as an opaque blob for backend symbolication rather than decoded into events.

Response Codes

Retry on 409, 408, 429, 5xx, and network errors; treat 400, 413, 415, and 422 as permanent. This matches the SDK upload policy described in Shared Concepts.

Debugging Binary Payloads

The binary path returns bare status codes, which can be opaque. To inspect what a frame decodes to, send a single complete frame to POST https://i.honch.io/capture/validate with Content-Type: application/vnd.honch.chunk. It returns the decoded and expanded events (or a description of the decode failure) without storing anything. See Validate Before You Send.

Next Steps