> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weaverse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Theme Settings

> Retrieve theme configuration and static translations for a project

# 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

<Note>
  Requires a Content API key. See [Authentication](/content-api/overview#authentication).
</Note>

## 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](https://www.portabletext.org/) 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](/content-api/get-page#portable-text-format) for the conversion rules and a rendering example.

## Response

### Without locale

```json theme={null}
{
  "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
```

```json theme={null}
{
  "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. |

<Tip>
  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.
</Tip>

<Tip>
  Use the [List Languages](/content-api/list-languages) endpoint to discover available locales before requesting translations.
</Tip>

## 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.

```json theme={null}
{
  "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": []
        }
      ]
    }
  }
}
```

In the default `weaverse` format the same `copyright` field is returned as the original HTML string `"<p>&copy; 2026 <em>Acme Inc.</em></p>"`.

## 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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 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"
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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}` } }
    )
    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'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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", {})
    ```
  </Tab>
</Tabs>