Skip to main content
The theme is a single workspace-level document holding color tokens, typography settings, and spacing values. Every block reads from it at render time, so changing one token re-skins every block instance in every page — no per-page patching required. The Theme resource lets you fetch the current draft, patch it with JSON Patch, and publish it live. By the end of this page you will know the endpoints, the draft vs live model, and how token changes propagate.

​
A theme in shape

{
  "colors": {
    "brand_primary":   "#6C2BD9",
    "brand_secondary": "#A78BFA",
    "surface":         "#0F0F10",
    "on_surface":      "#FAFAFA"
  },
  "typography": {
    "font_family_heading": "Inter",
    "font_family_body":    "Inter",
    "scale":               "default"
  },
  "spacing":    { "section_gap": "lg" },
  "updated_at": "2026-05-09T11:00:00Z"
}
Block props that reference a color name resolve through the colors map. Typography and spacing apply globally.

​
Endpoints

Fetch the current draft theme document. Apply RFC 6902 JSON Patch operations to the draft. Publish the current draft theme to live.

​
Patching tokens

The patch protocol is identical to patching a page — an RFC 6902 array of { op, path, value } objects. Paths target JSON Pointer locations inside the theme document. 
curl -X PATCH https://api.gavai.app/v1/workspaces/acme/theme \
  -H "Authorization: Bearer gak_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    { "op": "replace", "path": "/colors/brand_primary",          "value": "#7C3AED" },
    { "op": "replace", "path": "/typography/font_family_heading", "value": "Geist"   }
  ]'
A single token change re-skins every block instance that references it. Preview in a staging workspace before patching production.

​
Draft vs live

StateWhat it isHow it changes
DraftThe working theme returned by GET /theme.Every PATCH produces a new draft version.
LiveThe theme visitors render against.Updated only by POST /theme. Visitors see the change on their next page load.

​
Common errors

Theme in PageBlocks

How color tokens, typography, and spacing flow from the theme into individual block props.