Themes

Define and manage visual themes for your SaaS applications. Themes control colors, typography, layout spacing, border radius, shadows, and branding.

List Themes

GET /v1/themes

Returns all themes for the organization. The organization is taken from the authenticated session; no query parameters are required.

Response

{
  "data": {
    "themes": [
      {
        "id": "...",
        "name": "Corporate Blue",
        "description": "Professional blue theme for enterprise clients",
        "is_default": true,
        "created_at": "2026-02-15T10:00:00Z",
        "updated_at": "2026-04-01T14:30:00Z"
      }
    ]
  }
}

Create Theme

POST /v1/themes

The organization is taken from the authenticated session. Provide either the structured colors/typography/layout fields together, or a full theme_data object. Extended sections such as spacing, radius, shadows, and branding are supplied under theme_data.

Request Body

{
  "name": "Corporate Blue",
  "description": "Professional blue theme for enterprise clients",
  "is_dark": false,
  "is_default": true,
  "status": "active",
  "colors": {
    "primary": "#1a56db",
    "secondary": "#6b7280",
    "background": "#ffffff",
    "card": "#f9fafb",
    "text": "#111827",
    "border": "#e5e7eb",
    "accent": "#3b82f6",
    "danger": "#ef4444",
    "success": "#10b981",
    "warning": "#f59e0b"
  },
  "typography": {
    "font_family": "Inter, system-ui, sans-serif",
    "base_size": 16,
    "heading_weight": "700",
    "line_height_ratio": 1.5
  },
  "layout": {
    "border_radius": "md",
    "density": "comfortable",
    "sidebar_position": "left"
  },
  "theme_data": {
    "spacing": { "md": "1rem" },
    "radius": { "md": "8px" },
    "shadows": { "md": "0 4px 6px rgba(0, 0, 0, 0.07)" },
    "branding": {
      "logo_url": "https://cdn.example.com/logo.svg",
      "favicon_url": "https://cdn.example.com/favicon.ico",
      "app_name": "Acme Build"
    }
  }
}

Do not send id, created_at, or updated_at in the request body; these are assigned by the server.

Response

A successful create returns 201 Created with the complete theme record inside the standard envelope.

{
  "success": true,
  "data": {
    "theme": {
      "id": "...",
      "name": "Corporate Blue",
      "description": "Professional blue theme for enterprise clients",
      "is_dark": false,
      "is_default": true,
      "status": "active",
      "colors": {
        "primary": "#1a56db",
        "secondary": "#6b7280",
        "background": "#ffffff",
        "card": "#f9fafb",
        "text": "#111827",
        "border": "#e5e7eb",
        "accent": "#3b82f6",
        "danger": "#ef4444",
        "success": "#10b981",
        "warning": "#f59e0b"
      },
      "typography": {
        "font_family": "Inter, system-ui, sans-serif",
        "base_size": 16,
        "heading_weight": "700",
        "line_height_ratio": 1.5
      },
      "layout": {
        "border_radius": "md",
        "density": "comfortable",
        "sidebar_position": "left"
      },
      "theme_data": { "spacing": { "md": "1rem" } },
      "created_at": "2026-04-12T15:30:00Z",
      "updated_at": "2026-04-12T15:30:00Z"
    }
  }
}

Response Codes

Get Theme

GET /v1/themes/:id

Update Theme

PUT /v1/themes/:id

Update any combination of theme properties. Only the provided sections are modified; omitted sections retain their current values.

Request Body

{
  "name": "Corporate Green",
  "colors": {
    "primary": "#059669",
    "accent": "#10b981"
  },
  "theme_data": {
    "branding": {
      "app_name": "Acme Build Pro"
    }
  }
}

Delete Theme

DELETE /v1/themes/:id

The default theme cannot be deleted (reassign the default first), and a theme that is active, published, or referenced by an active package or data bundle is rejected with 409.

Theme Properties