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

# Replace your whole branding layer at once

> A whole-layer replace, not a merge: the layer you send becomes the complete set of overrides, and anything you leave out falls back to the platform default.

This is a **whole-layer replace**, not a merge. The `layer` you send becomes the complete set of overrides. Any field you leave out, or send as `null`, has no override and falls back to the platform default. To clear one override, send the layer you last read with that field removed or set to `null`. If you omit `layer` entirely, every override is cleared.

The layer is sparse and uses the same camelCase shape `GET /branding` returns, so you can read it, edit it and send it back. Unknown keys are refused with `400` and named in the message, so a typo never saves silently. The whole request body is limited to 256 KiB, so large inline images count against that limit.

**Concurrency.** `revision` is required. Send the `revision` from your last read (`0` if branding has never been saved). If anyone has saved or reset branding since, the request fails with `409` and nothing is changed; read again and retry. A successful save returns the new state with `revision` increased by one.

**What becomes public.** `identity`, `assets`, `theme` and `surfaces` are shown to anyone who loads your [website widget](/channels/widget). `domains` and `legal` are not sent to the widget.

**Attribution.** The layer has no field for third-party attribution notices. They cannot be set, changed or removed through this API.

Replacing branding requires the owner or admin role. Other roles receive `403`. See [Branding](/administration/branding).

## Value rules

| Rule            | Accepted values                                                                                                                                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text            | 1 to 120 characters after trimming. No control, invisible formatting (such as zero-width or bidirectional-override), private-use or line-separator characters. An empty string is refused; use `null` to clear.                                          |
| Link            | An `https://` URL of at most 1,024 characters, with no whitespace, quotes, `<`, `>`, `\` or backticks. `http://` is refused.                                                                                                                             |
| Asset           | Either a URL following the link rule, or inline base64 image data `data:<type>;base64,<data>` where `<type>` is `image/svg+xml`, `image/png`, `image/jpeg`, `image/webp`, `image/gif` or `image/x-icon`. At most 262,144 characters.                     |
| Colour          | A hex value (`#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`), or `rgb()`, `rgba()`, `hsl()` or `hsla()` whose arguments contain only digits, spaces and `. , % / + -`, at most 64 characters inside the parentheses. Named colours such as `red` are refused. |
| Font stack      | 1 to 200 characters from letters, digits, spaces and `, . _ ' " ( ) -`.                                                                                                                                                                                  |
| Base size       | A whole number from 10 to 24.                                                                                                                                                                                                                            |
| Radius          | A CSS length such as `10px`: at most 16 characters of letters, digits, `.`, `_` and `%`.                                                                                                                                                                 |
| Appearance mode | `light`, `dark` or `system`.                                                                                                                                                                                                                             |
| Boolean         | A JSON `true` or `false`. Strings such as `"false"` are refused.                                                                                                                                                                                         |

<ParamField body="revision" type="integer" required>
  The `revision` from your last read, a whole number of at least `0`. A stale value returns `409`.
</ParamField>

<ParamField body="layer" type="object">
  The complete set of overrides. Every section and every field is optional.

  <Expandable title="properties">
    <ParamField body="identity" type="object">
      Names shown in the interface.

      <Expandable title="properties">
        <ParamField body="productName" type="string">
          Product name. Follows the text rule.
        </ParamField>

        <ParamField body="productShortName" type="string">
          Short product name. Follows the text rule.
        </ParamField>

        <ParamField body="companyName" type="string">
          Company name. Follows the text rule.
        </ParamField>

        <ParamField body="companyLegalName" type="string">
          Company legal name. Follows the text rule.
        </ParamField>

        <ParamField body="tagline" type="string">
          Tagline. Follows the text rule.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="assets" type="object">
      Logos and images.

      <Expandable title="properties">
        <ParamField body="logoLight" type="string">
          Logo for the light appearance. Follows the asset rule.
        </ParamField>

        <ParamField body="logoDark" type="string">
          Logo for the dark appearance. Follows the asset rule.
        </ParamField>

        <ParamField body="logoMark" type="string">
          Compact logo mark. Follows the asset rule.
        </ParamField>

        <ParamField body="favicon" type="string">
          Browser tab icon. Follows the asset rule.
        </ParamField>

        <ParamField body="ogImage" type="string">
          Social sharing image. Follows the asset rule.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="theme" type="object">
      Colours, typography, corner radii and default appearance.

      <Expandable title="properties">
        <ParamField body="colors" type="object">
          Colour palettes, one per appearance. Follows the colour rule.

          <Expandable title="properties">
            <ParamField body="light" type="object">
              Colour overrides for the light appearance. Each key takes a colour. Keys:
              `background`, `surface`, `surfaceRaised`, `surfaceSunken`, `border`, `borderStrong`,
              `textPrimary`, `textSecondary`, `textMuted`, `textInverted`, `brand`, `brandHover`,
              `brandContrast`, `brandSubtle`, `accent`, `accentContrast`, `focus`, `success`,
              `successSubtle`, `warning`, `warningSubtle`, `danger`, `dangerSubtle`, `info`,
              `infoSubtle`, `overlay`.
            </ParamField>

            <ParamField body="dark" type="object">
              Colour overrides for the dark appearance. Each key takes a colour. Keys: `background`,
              `surface`, `surfaceRaised`, `surfaceSunken`, `border`, `borderStrong`, `textPrimary`,
              `textSecondary`, `textMuted`, `textInverted`, `brand`, `brandHover`, `brandContrast`,
              `brandSubtle`, `accent`, `accentContrast`, `focus`, `success`, `successSubtle`,
              `warning`, `warningSubtle`, `danger`, `dangerSubtle`, `info`, `infoSubtle`, `overlay`.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="typography" type="object">
          Fonts.

          <Expandable title="properties">
            <ParamField body="fontFamilySans" type="string">
              CSS font stack for body text. Follows the font stack rule.
            </ParamField>

            <ParamField body="fontFamilyMono" type="string">
              CSS font stack for code. Follows the font stack rule.
            </ParamField>

            <ParamField body="baseSizePx" type="integer">
              Base font size in pixels. Follows the base size rule.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="shape" type="object">
          Corner radii. Follows the radius rule.

          <Expandable title="properties">
            <ParamField body="radiusSm" type="string">
              Small radius.
            </ParamField>

            <ParamField body="radiusMd" type="string">
              Medium radius.
            </ParamField>

            <ParamField body="radiusLg" type="string">
              Large radius.
            </ParamField>

            <ParamField body="radiusXl" type="string">
              Extra-large radius.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="modeDefault" type="string">
          Appearance the interface starts in. Follows the appearance mode rule.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="domains" type="object">
      Your own help links.

      <Expandable title="properties">
        <ParamField body="docsUrl" type="string">
          Documentation link. Follows the link rule.
        </ParamField>

        <ParamField body="supportUrl" type="string">
          Support link. Follows the link rule.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="legal" type="object">
      Your own legal links and notice. Third-party attribution notices are not part of the layer and
      cannot be set, changed or removed through this API.

      <Expandable title="properties">
        <ParamField body="termsUrl" type="string">
          Terms of service link. Follows the link rule.
        </ParamField>

        <ParamField body="privacyUrl" type="string">
          Privacy policy link. Follows the link rule.
        </ParamField>

        <ParamField body="copyrightNotice" type="string">
          Your copyright line. Follows the text rule.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="surfaces" type="object">
      Display toggles.

      <Expandable title="properties">
        <ParamField body="console" type="object">
          Console toggles.

          <Expandable title="properties">
            <ParamField body="showLogo" type="boolean">
              Show the logo in the console. Follows the boolean rule.
            </ParamField>

            <ParamField body="showPoweredBy" type="boolean">
              Show the powered-by line in the console. Follows the boolean rule.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="widget" type="object">
          Website widget toggles.

          <Expandable title="properties">
            <ParamField body="showBranding" type="boolean">
              Show branding in the widget. Follows the boolean rule.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns `200 OK` with the stored branding.

<ResponseField name="layer" type="object" required>
  Your organization's overrides. Sparse: only fields you have set appear, and an organization with
  no overrides returns `{}`. Anything absent falls back to the platform default.

  <Expandable title="properties">
    <ResponseField name="identity" type="object">
      Names shown in the interface.

      <Expandable title="properties">
        <ResponseField name="productName" type="string">
          Product name.
        </ResponseField>

        <ResponseField name="productShortName" type="string">
          Short product name.
        </ResponseField>

        <ResponseField name="companyName" type="string">
          Company name.
        </ResponseField>

        <ResponseField name="companyLegalName" type="string">
          Company legal name.
        </ResponseField>

        <ResponseField name="tagline" type="string">
          Tagline.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assets" type="object">
      Logos and images.

      <Expandable title="properties">
        <ResponseField name="logoLight" type="string">
          Logo for the light appearance.
        </ResponseField>

        <ResponseField name="logoDark" type="string">
          Logo for the dark appearance.
        </ResponseField>

        <ResponseField name="logoMark" type="string">
          Compact logo mark.
        </ResponseField>

        <ResponseField name="favicon" type="string">
          Browser tab icon.
        </ResponseField>

        <ResponseField name="ogImage" type="string">
          Social sharing image.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="theme" type="object">
      Colours, typography, corner radii and default appearance.

      <Expandable title="properties">
        <ResponseField name="colors" type="object">
          Colour palettes, one per appearance.

          <Expandable title="properties">
            <ResponseField name="light" type="object">
              Colour overrides for the light appearance. Each key takes a colour. Keys:
              `background`, `surface`, `surfaceRaised`, `surfaceSunken`, `border`, `borderStrong`,
              `textPrimary`, `textSecondary`, `textMuted`, `textInverted`, `brand`, `brandHover`,
              `brandContrast`, `brandSubtle`, `accent`, `accentContrast`, `focus`, `success`,
              `successSubtle`, `warning`, `warningSubtle`, `danger`, `dangerSubtle`, `info`,
              `infoSubtle`, `overlay`.
            </ResponseField>

            <ResponseField name="dark" type="object">
              Colour overrides for the dark appearance. Each key takes a colour. Keys: `background`,
              `surface`, `surfaceRaised`, `surfaceSunken`, `border`, `borderStrong`, `textPrimary`,
              `textSecondary`, `textMuted`, `textInverted`, `brand`, `brandHover`, `brandContrast`,
              `brandSubtle`, `accent`, `accentContrast`, `focus`, `success`, `successSubtle`,
              `warning`, `warningSubtle`, `danger`, `dangerSubtle`, `info`, `infoSubtle`, `overlay`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="typography" type="object">
          Fonts.

          <Expandable title="properties">
            <ResponseField name="fontFamilySans" type="string">
              CSS font stack for body text.
            </ResponseField>

            <ResponseField name="fontFamilyMono" type="string">
              CSS font stack for code.
            </ResponseField>

            <ResponseField name="baseSizePx" type="integer">
              Base font size in pixels.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="shape" type="object">
          Corner radii.

          <Expandable title="properties">
            <ResponseField name="radiusSm" type="string">
              Small radius.
            </ResponseField>

            <ResponseField name="radiusMd" type="string">
              Medium radius.
            </ResponseField>

            <ResponseField name="radiusLg" type="string">
              Large radius.
            </ResponseField>

            <ResponseField name="radiusXl" type="string">
              Extra-large radius.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="modeDefault" type="string">
          Appearance the interface starts in.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="domains" type="object">
      Your own help links.

      <Expandable title="properties">
        <ResponseField name="docsUrl" type="string">
          Documentation link.
        </ResponseField>

        <ResponseField name="supportUrl" type="string">
          Support link.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="legal" type="object">
      Your own legal links and notice. Third-party attribution notices are not part of the layer and
      cannot be set, changed or removed through this API.

      <Expandable title="properties">
        <ResponseField name="termsUrl" type="string">
          Terms of service link.
        </ResponseField>

        <ResponseField name="privacyUrl" type="string">
          Privacy policy link.
        </ResponseField>

        <ResponseField name="copyrightNotice" type="string">
          Your copyright line.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="surfaces" type="object">
      Display toggles.

      <Expandable title="properties">
        <ResponseField name="console" type="object">
          Console toggles.

          <Expandable title="properties">
            <ResponseField name="showLogo" type="boolean">
              Show the logo in the console.
            </ResponseField>

            <ResponseField name="showPoweredBy" type="boolean">
              Show the powered-by line in the console.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="widget" type="object">
          Website widget toggles.

          <Expandable title="properties">
            <ResponseField name="showBranding" type="boolean">
              Show branding in the widget.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="revision" type="integer" required>
  Concurrency revision. `0` until the first save; each save or reset adds one. Send it back on `PUT
      /branding` or `DELETE /branding`.
</ResponseField>

<ResponseField name="configured" type="boolean" required>
  `true` once branding has been saved or reset at least once. `false` means the organization has
  always used the platform default.
</ResponseField>

<ResponseField name="updatedAt" type="string | null" required>
  When branding was last saved or reset, ISO 8601 in UTC. `null` if never.
</ResponseField>

<ResponseField name="updatedBy" type="string | null" required>
  Identifier of the user or API key that last saved or reset branding. `null` if never.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request PUT "$MITHUNAI_URL/arukz/api/v1/branding" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "revision": 3,
      "layer": {
        "identity": { "productName": "Northwind Answers", "companyName": "Northwind Traders" },
        "assets": { "logoLight": "https://cdn.northwind.example/brand/logo-light.svg" },
        "theme": {
          "colors": { "light": { "brand": "#1F6FEB", "brandHover": "#1A5FCC" } },
          "modeDefault": "system"
        },
        "domains": { "supportUrl": "https://support.northwind.example" },
        "surfaces": { "widget": { "showBranding": false } }
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  layer = {
      "identity": {"productName": "Northwind Answers", "companyName": "Northwind Traders"},
      "assets": {"logoLight": "https://cdn.northwind.example/brand/logo-light.svg"},
      "theme": {
          "colors": {"light": {"brand": "#1F6FEB", "brandHover": "#1A5FCC"}},
          "modeDefault": "system",
      },
      "domains": {"supportUrl": "https://support.northwind.example"},
      "surfaces": {"widget": {"showBranding": False}},
  }

  response = requests.put(
      f"{os.environ['MITHUNAI_URL']}/arukz/api/v1/branding",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      json={"revision": 3, "layer": layer},
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const layer = {
    identity: { productName: 'Northwind Answers', companyName: 'Northwind Traders' },
    assets: { logoLight: 'https://cdn.northwind.example/brand/logo-light.svg' },
    theme: {
      colors: { light: { brand: '#1F6FEB', brandHover: '#1A5FCC' } },
      modeDefault: 'system',
    },
    domains: { supportUrl: 'https://support.northwind.example' },
    surfaces: { widget: { showBranding: false } },
  }

  const response = await fetch(`${process.env.MITHUNAI_URL}/arukz/api/v1/branding`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ revision: 3, layer }),
  })
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "layer": {
      "identity": {
        "productName": "Northwind Answers",
        "companyName": "Northwind Traders"
      },
      "assets": {
        "logoLight": "https://cdn.northwind.example/brand/logo-light.svg"
      },
      "theme": {
        "colors": {
          "light": {
            "brand": "#1F6FEB",
            "brandHover": "#1A5FCC"
          }
        },
        "modeDefault": "system"
      },
      "domains": {
        "supportUrl": "https://support.northwind.example"
      },
      "surfaces": {
        "widget": {
          "showBranding": false
        }
      }
    },
    "revision": 4,
    "configured": true,
    "updatedAt": "2026-09-24T10:48:13.209577+00:00",
    "updatedBy": "8d3f6a21-4c9e-4b07-a1d5-e62f0b9c7a48"
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "code": "validation_error",
    "message": "Colours must be a hex value such as #4636D9, or an rgb(), rgba(), hsl() or hsla() value."
  }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "You do not have permission to perform this action." }
  ```

  ```json 409 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "conflict", "message": "The branding was changed by someone else. Reload and try again." }
  ```
</ResponseExample>