Binary Payloads: MessagePack and Protobuf

Devices, transit feeds and internal services often send binary bodies. A bin decodes them to JSON when they arrive. The decoded JSON is what you see, search, filter, route and (if you choose) forward. The bytes as received stay stored and you can download them.

MessagePack

Send Content-Type: application/msgpack (or application/x-msgpack, application/vnd.msgpack). No set-up. Binary values show as {"$bytes": "<base64>"}, extension types as {"$ext": code, "$bytes": …}.

Protobuf

1. Open a bin, then Binary bodies → schemas in the Destinations panel (or /b/<bin-id>/schemas).
2. Upload all .proto files of one schema together. Imports between the files and the Google well-known types work.
3. Write the path map: which message type decodes which path.

/telemetry acme.telemetry.Reading
/vehicles  transit_realtime.FeedMessage
*          acme.Envelope

• Content types: application/protobuf, application/x-protobuf, application/vnd.google.protobuf. application/octet-stream is decoded only when a rule or the sender gives a type.
• The sender can name the type: Content-Type: application/x-protobuf; proto=acme.telemetry.Reading. This wins over the map.
• GTFS-realtime is built in: use transit_realtime.FeedMessage (alias gtfs-realtime) for vehicle positions, trip updates and alerts.
• Fields that your schema does not know are kept under _unknown with their field numbers.
• Without a type, a Protobuf body shows its fields under their numbers, so you can read a message before you have the schema.
• A body that does not parse is stored as received, with $decode_error in the decoded view.

What uses the decoded JSON

• The bin page shows the decoded JSON. Press Raw for the bytes; /b/<bin>/requests/<id>/raw downloads them.
• Search finds text in decoded fields.
• Filters in actions, alerts and routes read body.<field> from the decoded JSON. A route can forward only readings above a limit: body.temp > 80.
• Destinations get the bytes as received, or the decoded JSON when you select Send the decoded JSON on the destination.
• API, export and MCP return decoded and decoded_as on each request.

Limits

A schema is at most 20 files of 256 KB each.

API and MCP

GET    /api/v1/bins/{id}/schemas
POST   /api/v1/bins/{id}/schemas          {"name", "files": {"acme/reading.proto": "syntax = \"proto3\"; …"}}
PUT    /api/v1/bins/{id}/schemas/map      {"map": "/telemetry acme.Reading\n* acme.Envelope"}
DELETE /api/v1/bins/{id}/schemas/{schema_id}

MCP tools: list_schemas, add_schema, set_schema_map, delete_schema.