a2ui-compose

Composing and rendering an A2UI payload

The payload shape

{
  "title": "Weekly numbers",
  "theme": "light",
  "blocks": [
    { "type": "heading", "text": "This week" },
    { "type": "stat_card", "value": "1,234", "label": "Daily users", "delta": "+12%" }
  ]
}

blocks is an ordered array of atoms (the "blocks dialect"). A v1.0 createSurface envelope (templates + dataModel bindings) is also accepted wherever a payload is taken — theme is light, dark, or terminal (the catalog's own dark/monospace brand skin).

Render, by host capability

• MCP Apps-capable host (renders inline in the conversation, no URL, no size ceiling): render_surface(payload).
• Any other MCP host: preview_url(payload) — a shareable link on the shared demo renderer (rate-limited: 10 calls per client per 7 days).
• No rate limit, your own deployment: make_surface_url(payload, renderer_url) — renders against a renderer YOU deployed (see the self-hosting quickstart below), or omit renderer_url for the encoded-fragment + BYO guidance.
• Protocol-free, no MCP client at all: POST https://a2uicatalog.ai/api/render with the payload as the JSON body — returns a complete self-contained HTML page. Same guards, same 50-requests/day-per-IP limit as the MCP tools above. POST /api/render/batch does up to 25 payloads in one call with PARTIAL SUCCESS semantics (one malformed payload doesn't fail the batch).

Failure modes worth knowing before they surprise you

• Preview-stage or unpublished atoms aren't an error — they render as a visible "not published here" notice rather than being silently dropped, and are named in the X-A2UI-Unpublished response header.
• Atoms that need a render-time server fetch (data_source, firestore_read, doc_ai_summary, multi_doc_ai_brief, gemini_handoff) are refused with 400 on the public renderer — deploy your own renderer for those (see below).
• Limits: 256 KB body, 300 blocks, 12 levels of nesting on /api/render. An oversized or over-nested payload is a 400, not a silent truncation — check the error body for which limit was hit.
• A surface query param (?surface=web|mcp-apps|google-apps-script-web|google-meet-stage) applies that surface's declared compatibility policy: atoms marked degraded_on still render (named in X-A2UI-Degraded); atoms marked incompatible_on are replaced with a visible callout (named in X-A2UI-Incompatible) rather than rendering something wrong. pdf, email and google-chat are refused with 400 here — this endpoint emits HTML, and answering half-honestly about portability on those surfaces is worse than refusing.