Get Theme Settings

GET /api/v1/content/projects/:projectId/theme-settings

Returns the theme configuration for a project, including design tokens, colors, typography, and other global styling settings configured in the Weaverse Studio editor. When the locale query parameter is provided, also returns staticTranslations — the resolved static text translations for that locale (e.g., cart labels, button text, navigation strings).

Authentication

Requires a Content API key. See Authentication.

Path parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The project ID

Query parameters

Parameter	Type	Required	Description
`locale`	string	No	Locale code (e.g., `fr-fr`, `vi-vn`). When provided, includes `staticTranslations` in the response. Tries exact match first, then falls back to language prefix (e.g., `fr`).
`format`	`weaverse` \| `portable-text`	No (default `weaverse`)	Output format. With `portable-text`, any string value (in `theme` or `staticTranslations`) that contains HTML markup is replaced in place by a Portable Text block array. The envelope shape is unchanged.

The format can also be requested via Accept: application/portable-text+json. The query parameter takes precedence when both are present. See Get Page › Portable Text format for the conversion rules and a rendering example.

Response

Without locale

{
  "object": "theme_settings",
  "projectId": "clx1abc23def456ghij",
  "theme": {
    "colorSchemes": {
      "primary": {
        "background": "#ffffff",
        "foreground": "#1a1a1a",
        "accent": "#246aff"
      },
      "secondary": {
        "background": "#f5f5f5",
        "foreground": "#333333",
        "accent": "#10b981"
      }
    },
    "typography": {
      "headingFont": "Inter",
      "bodyFont": "Inter",
      "baseSize": 16
    },
    "layout": {
      "maxWidth": 1280,
      "containerPadding": 24
    }
  }
}

With locale

GET /projects/:projectId/theme-settings?locale=fr-fr

{
  "object": "theme_settings",
  "projectId": "clx1abc23def456ghij",
  "theme": {
    "colorSchemes": { "..." : "..." },
    "typography": { "..." : "..." }
  },
  "staticTranslations": {
    "cart": {
      "title": "Panier",
      "empty": {
        "message": "Votre panier est vide"
      }
    },
    "product": {
      "addToCart": "Ajouter au panier",
      "soldOut": "Rupture de stock"
    }
  }
}

Response fields

Field	Type	Description
`object`	string	Always `"theme_settings"`
`projectId`	string	The project ID
`theme`	object	Theme configuration object
`staticTranslations`	object	Nested translation keys with resolved values for the requested locale. Only present when `locale` query parameter is provided. Uses translated value when available, falls back to default value.

The theme object shape varies per project and depends on how theme settings are configured in the Weaverse Studio. Use the response data to apply consistent styling across your frontend.

Use the List Languages endpoint to discover available locales before requesting translations.

Portable Text format

With ?format=portable-text, the response carries Content-Type: application/portable-text+json and any HTML-valued leaf inside theme or staticTranslations is converted in place. Non-HTML strings, numbers, booleans, colors, and the surrounding object structure are preserved exactly — only richtext leaves change shape.

{
  "object": "theme_settings",
  "projectId": "clx1abc23def456ghij",
  "theme": {
    "colorSchemes": { "primary": { "background": "#ffffff" } },
    "footer": {
      "copyright": [
        {
          "_type": "block",
          "_key": "b1",
          "style": "normal",
          "children": [
            { "_type": "span", "_key": "s1", "text": "© 2026 " },
            { "_type": "span", "_key": "s2", "text": "Acme Inc.", "marks": ["em"] }
          ],
          "markDefs": []
        }
      ]
    }
  }
}

Errors

Code	Status	When
`INVALID_PARAMS`	400	Missing `projectId`, empty `locale`, or unsupported `format` value
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	API key does not have access to this project
`PROJECT_NOT_FOUND`	404	Project does not exist or was deleted
`INTERNAL_ERROR`	500	Unexpected server error

Examples

cURL
TypeScript
Python

# Without locale
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.weaverse.io/api/v1/content/projects/clx1abc23def456ghij/theme-settings"

# With locale
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.weaverse.io/api/v1/content/projects/clx1abc23def456ghij/theme-settings?locale=fr-fr"

const locale = 'fr-fr'
const res = await fetch(
  `https://studio.weaverse.io/api/v1/content/projects/${projectId}/theme-settings?locale=${locale}`,
  { headers: { Authorization: ['Bearer', API_KEY].join(' ') } }
)
const { theme, staticTranslations } = await res.json()

// Apply theme tokens
document.documentElement.style.setProperty(
  '--color-primary',
  theme.colorSchemes?.primary?.accent ?? '#246aff'
)

// Use translations
const cartTitle = staticTranslations?.cart?.title ?? 'Cart'

import requests

res = requests.get(
    f"https://studio.weaverse.io/api/v1/content/projects/{project_id}/theme-settings",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"locale": "fr-fr"},
)
data = res.json()
theme = data["theme"]
translations = data.get("staticTranslations", {})

Overview

Hooks

Components

Utilities & Types

Content API

Get Theme Settings

Get Theme Settings

Authentication

Path parameters

Query parameters

Response

Without locale

With locale

Response fields

Portable Text format

Errors

Examples

​Get Theme Settings

​Authentication

​Path parameters

​Query parameters

​Response

​Without locale

​With locale

​Response fields

​Portable Text format

​Errors

​Examples

Get Theme Settings

Authentication

Path parameters

Query parameters

Response

Without locale

With locale

Response fields

Portable Text format

Errors

Examples