The platform prefers CBOR (RFC 8949) on the wire: smaller payloads, faster parse/encode, native binary support (no base64 round-tripping for model bytes and previews), and deterministic encoding when canonicalisation is needed.
CBOR is the preferred encoding on:
application/cbor).Per state-server/docs/APP_DESCRIPTION.md the serialization stack documents CBOR as the primary efficient binary format and JSON as a universal-compatibility fallback (Protocol Buffers are on the roadmap). Both clients and servers should default to CBOR; JSON is a supported fallback when CBOR is impractical.
| Language / Runtime | Library | Notes |
|---|---|---|
| Go (server) | github.com/fxamacker/cbor/v2 v2.7.x |
Used by state-server and avvy-worker. |
| JavaScript / TypeScript | cbor-x |
Used by the JS SDK and avvy-app. |
IDs. All resource IDs are UUID v4 strings (8-4-4-4-12).
Timestamps. Unix seconds in timestamp fields. The WebSocket envelope's timestamp is integer seconds.
Binary data. CBOR byte strings (major type 2) for model bytes, preview images, and signed payload bodies. Avoid data: URIs and avoid base64.
Maps. Use string keys for public surfaces. Internal-only encodings may use integer keys to shave bytes; document them locally.
Floats. IEEE-754 double precision unless the field is documented as float32. Transform matrices are 16-element float64 arrays in row-major order.
Optionality. Optional fields are omitted (not present as null) unless null is semantically distinct.
Determinism. When canonicalisation matters (e.g. SHA-256 hashing for callback signatures), encode in CBOR canonical form (sorted keys, shortest length, definite-length encoding).
Content-Type: application/cbor
Accept: application/cbor
Authorization: Bearer <jwt>
Idempotency-Key: <uuid-v4> # required on mutating /object, /prototype, /users endpoints
For a JSON fallback request, set Content-Type: application/json and Accept: application/json. Mixing types in a single request (e.g. CBOR body, JSON Accept) is not guaranteed to behave consistently — pick one.
Each WebSocket frame is a single CBOR-encoded message map. See WebSocket protocol for the envelope shape and frame types.
REST errors follow the ErrorMessageResponse shape; WebSocket errors arrive as system.error frames with code, message, and request_id fields. Both layers share a common code namespace (for example OBJECT_001, AUTH_*, RATE_LIMIT_*).
gitlab.avvyland.com/avvy/state-server — docs/openapi-v2.yml, docs/WEBSOCKET_PROTOCOL.md. Server library: github.com/fxamacker/cbor/v2. Client library: cbor-x (also re-exported via the JS SDK).