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

> ## Agent Instructions
> Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it.
> Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`.
> Before using any code sample, read `@weaverse/hydrogen` in the project's `package.json`: 6.x and 5.x import from different entries and use different type names, so code for one does not build on the other.
> `@weaverse/hydrogen` 6 (Shopify Hydrogen 2026.10 and later, the version these docs show) imports from `@weaverse/hydrogen/react-router` and uses `Weaverse*` types such as `WeaverseComponentProps`, `WeaverseComponentLoaderArgs` and `WeaverseComponentSchema`; the root `@weaverse/hydrogen` entry only exports `createSchema()`, data helpers and types.
> `@weaverse/hydrogen` 5.x (Hydrogen 2026.4 and earlier) imports everything from `@weaverse/hydrogen` and uses `HydrogenComponentProps`, `ComponentLoaderArgs` and `HydrogenComponentSchema`. On a 5.x project, convert samples to these names. Upgrade to 6 only when asked (`npx @weaverse/cli@latest migrate v6`, plus the Hydrogen 2026.10 upgrade). Do not mix major versions.
> Next.js themes use `@weaverse/hydrogen` 6.2.0 or later: import client and shared code from `@weaverse/hydrogen/next` and server-only code from `@weaverse/hydrogen/next/server`. `@weaverse/next` is deprecated; never install or import it.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://weaverse.io/docs/developer-tools/weaverse-mcp

# Get theme settings

> Returns the project's theme settings: the global design tokens, colors, typography and other settings configured in Studio. The shape of `theme` depends on the theme's schema; it is an empty object when nothing is configured.

- `locale` (for example `fr-fr`) adds `staticTranslations`: the theme's static text (cart labels, button text and so on) resolved for that locale. Each key uses the translated value when available and falls back to the default. An exact locale match is tried first, then the language prefix. An empty `locale` returns `400`. Discover locales with `GET /projects/{projectId}/languages`.
- `format=portable-text` (or `Accept: application/portable-text+json`) replaces every HTML string inside `theme` or `staticTranslations` with a Portable Text block array; everything else is unchanged.
- `view=own` (default) returns this project's own theme plus its `revision`, the baseline for `PATCH`. `view=effective` returns the parent theme merged under this project's overrides with inheritance metadata; it is read-only and carries no revision.

Required scope: `content:read`



## OpenAPI

````yaml https://studio.weaverse.io/api/v1/content/openapi.json get /projects/{projectId}/theme-settings
openapi: 3.1.0
info:
  title: Weaverse Content API
  version: 1.0.0
  description: >-
    Authenticated REST API for reading and editing Weaverse-managed content
    (projects, pages, drafts, global sections, theme settings, languages) and
    for reading and writing per-locale translations.


    ## Authentication


    Send a bearer token in the `Authorization` header: a shop API key
    (`WEAVERSE_API_KEY`), a scoped API key or a delegated MCP OAuth token.
    Translation-unit routes also accept a project-bound translation agent token.
    Each operation's description ends with the scope it requires.


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `content:read` | Read projects, pages, theme settings, versions, drafts
    and translation units |

    | `content:write` | Save drafts and make non-destructive edits (page items,
    metadata, SEO, assignments, languages, glossary). Never publishes or deletes
    |

    | `content:publish` | Publish drafts, schedule, reschedule or cancel
    publications, restore versions, publish global sections |

    | `content:delete` | Delete pages, global sections, languages and static
    keys, and revert overrides. Project deletion also needs `project:manage` |

    | `project:manage` | Create, copy and delete projects; settings, variants,
    hierarchy, backups, restore as new, previews and hostname policy |

    | `translations:read` | Read translation units only, with no general content
    access |

    | `translations:write` | Apply translation units only; never changes page
    content |


    A legacy API key without scopes keeps read, write and translation access and
    every endpoint that existed before scopes, but never gains publish, delete
    or project management.
servers:
  - url: https://studio.weaverse.io/api/v1/content
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: List, read, rename, create, copy and delete projects.
  - name: Pages
    description: List, read, create, update and delete the pages of a project.
  - name: Drafts and publishing
    description: >-
      Edit page drafts, then publish, schedule, restore and manage page
      versions.
  - name: Global sections
    description: Read, edit and publish sections shared across pages.
  - name: Page settings
    description: Read and edit page-level settings such as SEO metadata.
  - name: Assignments
    description: Map Shopify resources and routes to Weaverse pages and templates.
  - name: Theme settings
    description: Read and update a project's theme settings.
  - name: Languages and localization
    description: List project languages and manage locales, static text and glossary.
  - name: Translations
    description: >-
      Read and write per-locale translations, built for external translation
      agents.
  - name: Project structure
    description: Manage project variants and the project hierarchy.
  - name: Backups and portability
    description: Back up, restore, export and import project content.
  - name: Previews and hostnames
    description: Create preview links and manage the hostnames a project accepts.
  - name: Specification
    description: This OpenAPI document.
paths:
  /projects/{projectId}/theme-settings:
    get:
      tags:
        - Theme settings
      summary: Get theme settings
      description: >-
        Returns the project's theme settings: the global design tokens, colors,
        typography and other settings configured in Studio. The shape of `theme`
        depends on the theme's schema; it is an empty object when nothing is
        configured.


        - `locale` (for example `fr-fr`) adds `staticTranslations`: the theme's
        static text (cart labels, button text and so on) resolved for that
        locale. Each key uses the translated value when available and falls back
        to the default. An exact locale match is tried first, then the language
        prefix. An empty `locale` returns `400`. Discover locales with `GET
        /projects/{projectId}/languages`.

        - `format=portable-text` (or `Accept: application/portable-text+json`)
        replaces every HTML string inside `theme` or `staticTranslations` with a
        Portable Text block array; everything else is unchanged.

        - `view=own` (default) returns this project's own theme plus its
        `revision`, the baseline for `PATCH`. `view=effective` returns the
        parent theme merged under this project's overrides with inheritance
        metadata; it is read-only and carries no revision.


        Required scope: `content:read`
      operationId: getThemeSettings
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: locale
          in: query
          schema:
            type: string
          description: |
            Locale code (e.g. "fr-fr"). When provided, the response includes a
            `staticTranslations` field with resolved translation values.
            Tries exact locale match first, then falls back to language prefix.
        - $ref: '#/components/parameters/Format'
        - name: view
          in: query
          schema:
            type: string
            enum:
              - own
              - effective
            default: own
          description: >-
            own: this project's theme bucket plus its revision (the PATCH
            baseline). effective: the parent theme merged under this project's
            overrides plus inheritance metadata; read-only, carries no revision.
      responses:
        '200':
          description: Theme settings with optional static translations
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                      - theme_settings
                      - theme_settings_effective
                    description: >-
                      theme_settings for view=own; theme_settings_effective for
                      view=effective
                  projectId:
                    type: string
                  theme:
                    type: object
                    description: Theme configuration JSON. Empty object if not configured.
                  staticTranslations:
                    type:
                      - object
                      - 'null'
                    description: >
                      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.
                  revision:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: >-
                      Project revision captured together with the `theme` in
                      this response (they are cached as one snapshot). Pass back
                      as `expectedRevision` on PATCH: if the settings changed
                      since this snapshot — including when the snapshot itself
                      was served from cache — the PATCH is rejected with 409
                      STALE_PROJECT; re-read and reapply.
                  inheritance:
                    type: object
                    description: Only for view=effective (which carries no revision).
                    properties:
                      inherited:
                        type: boolean
                      sourceProjectIds:
                        type: array
                        items:
                          type: string
                      overrideCount:
                        type: integer
                      inheritedKeys:
                        type: array
                        items:
                          type: string
                      overriddenKeys:
                        type: array
                        items:
                          type: string
              example:
                object: theme_settings
                projectId: clz1k8m2n0000abcd1234efgh
                theme:
                  colorBackground: '#ffffff'
                  colorText: '#1a1a1a'
                  colorPrimary: '#246aff'
                  headingFont: Inter
                  bodyFont: Inter
                  pageWidth: 1280
                staticTranslations:
                  cart:
                    title: Panier
                    empty:
                      message: Votre panier est vide
                  product:
                    addToCart: Ajouter au panier
                    soldOut: Rupture de stock
                revision: '2026-10-12T09:41:27.000Z'
        '400':
          description: Invalid `format` value (must be `weaverse` or `portable-text`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    Format:
      name: format
      in: query
      description: >-
        Output format for rich-text fields.

        - `weaverse` (default): rich text returned as HTML strings — original
        behavior, no migration needed.

        - `portable-text`: rich text returned as structured Portable Text blocks
        for multi-channel rendering and AI consumption.


        Equivalent to setting `Accept: application/portable-text+json` on the
        request. The query parameter takes precedence over the header when both
        are provided. An invalid value returns `400 INVALID_PARAMS`.
      schema:
        type: string
        enum:
          - weaverse
          - portable-text
        default: weaverse
  schemas:
    Error:
      type: object
      required:
        - object
        - code
        - message
        - status
      properties:
        object:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - UNAUTHORIZED
            - FORBIDDEN
            - INSUFFICIENT_SCOPE
            - PROJECT_NOT_FOUND
            - PAGE_NOT_FOUND
            - STALE_PAGE
            - STALE_PROJECT
            - STALE_TRANSLATION
            - TRANSLATION_UNIT_NOT_FOUND
            - SERVICE_UNAVAILABLE
            - CONFLICT
            - PRECONDITION_REQUIRED
            - INVALID_PARAMS
            - INTERNAL_ERROR
        message:
          type: string
        status:
          type: integer
        details:
          description: >-
            Optional machine-readable context, for example the clashing handles
            of a 409 CONFLICT.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: WEAVERSE_API_KEY
      description: >-
        Bearer token: a shop API key (`WEAVERSE_API_KEY`), a scoped API key or a
        delegated MCP OAuth token; translation-unit routes also accept a
        project-bound translation agent token. Each operation lists the scope it
        requires; the scope table is in the API description.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.