Render worker API

The render worker (crates/desyn-worker) is an internal Axum service. The Convex backend calls it for exports, thumbnails, AI previews, server-side layout and text measurement. It is not a public API: keep it on a private network and never expose its port. For programmatic access to designs, use the Agent API.

Authentication#

Every request must carry the shared secret in the x-desyn-secret header. The value is RENDER_WORKER_SECRET, set identically on the backend and the worker. GET /healthz is the only unauthenticated route.

Endpoints#

All bodies JSON unless noted. design is a full Design; large designs may be sent gzip-compressed.

POST /v1/render { design, pageId?, region?:{x,y,w,h}, scale?: number, format: "png"|"jpeg"|"webp"|"svg"|"pdf"|"pptx"|"gif"|"mp4", quality?, background?: Color|"transparent", pdf?: {bleed:boolean, cropMarks:boolean, cmyk:boolean}, assetUrls?: Record<Id,string> } -> bytes (content-type per format). pageId: "all" for multi-page pdf/pptx.
POST /v1/describe { design, pageId?, selection?, maxDepth? } -> Description.
POST /v1/layout { design } -> { design } with derived geometry recomputed (text boxes, auto-layout, groups).
POST /v1/measure { items: { text: TextRun[]; style: TextStyle; paragraph: ParagraphStyle; width?: number }[] } -> { sizes: {w,h,lines}[] }.
POST /v1/apply { design, tx } -> { design, inverse, applied, dropped } (full core semantics including layout).
POST /v1/imageops/remove-background|upscale|... are NOT in the worker; those are AI provider calls made from Convex/AI package. The worker also exposes POST /v1/thumbnail { design, pageId, width } -> webp bytes.
GET /healthz. Fonts: worker loads fonts from FONTS_DIR (bundled OFL set) and from assetUrls for design assets and custom fonts.

Example#

Render the first page of a design to a 2× PNG from inside the Compose network:

Shell

curl -sS http://worker:8080/v1/render \
  -H "x-desyn-secret: $RENDER_WORKER_SECRET" \
  -H "content-type: application/json" \
  --data @- --output page.png <<'EOF'
{ "design": { "schema": 1, "id": "d3k5m7p9r1t3", "...": "..." }, "format": "png", "scale": 2 }
EOF

Print-ready PDF of all pages with bleed and crop marks:

JSON

{ "design": { "...": "..." }, "pageId": "all", "format": "pdf", "pdf": { "bleed": true, "cropMarks": true, "cmyk": false } }

Operations#

Health: GET /healthz for container health checks.
Fonts: the worker loads a bundled set of open-licensed fonts from FONTS_DIR at start, and fetches design-specific and custom fonts from assetUrls per request.
Resources: renders run in parallel; MP4 and large multi-page exports are the heaviest. Give the worker enough memory for your largest designs and limit it with container resource limits.