Theme

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

State	What it is	How it changes
Draft	The working theme returned by `GET /theme`.	Every `PATCH` produces a new draft version.
Live	The 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.

Overview

Resources

A theme in shape

Endpoints

Patching tokens

Draft vs live

Common errors

Theme in PageBlocks

​A theme in shape

​Endpoints

​Patching tokens

​Draft vs live

​Common errors

​Related

Theme in PageBlocks

A theme in shape

Endpoints

Patching tokens

Draft vs live

Common errors

Related