State-server exposes a RESTful API under /api/v1/*. All bodies are CBOR (with JSON fallback supported by the server for select endpoints; clients should default to CBOR). The canonical contract is the OpenAPI 3.0.3 spec in the repo:
gitlab.avvyland.com/avvy/state-server → docs/openapi-v2.yml
This page is a navigable summary of the resource families, not the full contract — fetch the YAML for field-level detail and example payloads.
https://localhost:8443/api/v1https://api.<env>.../api/v1)Authorization: Bearer <jwt>).X-Admin-Token header — separate from user auth.Mutating routes (POST, PUT, PATCH, DELETE) under /object, /prototype, and /users require the Idempotency-Key header.
409 Conflict.The OpenAPI spec organizes endpoints under these tags:
private — owner-only.unlisted — readable without auth (visitor mode), excluded from public listing and search.public — readable without auth and listed.Public/unlisted objects are immutable; an update creates a new private draft version in the owner's inventory.
Three async pipelines submit work to avvy-worker, poll for state, and accept HMAC-signed CBOR callbacks via internal endpoints:
v2.7) — preview rendering + metadata.v2.8) — full object pipeline; stores processed CBOR in S3 and attaches to inventory.v2.9) — Tencent Hunyuan 3D 3.1 + PBR projection-derived model generation.See Signed Callbacks for the worker → server contract.
WebSocket protocol v2.0 for streaming and real-time mutations.
CBOR encoding for wire-format conventions.
Signed callbacks for worker callback HMAC.
JS SDK for the canonical client library that wraps both REST and WebSocket.
gitlab.avvyland.com/avvy/state-server — docs/openapi-v2.yml.