---
title: Update theme
description: "Renames a theme or changes its draft. config is merged into the current draft (see ThemeConfigPatch ): send only the values you want to change, and null to r…"
product: general
lang: en
last_updated: 2026-10-30
token_estimate: 4229
---
# Update theme

## Update theme

**PATCH** `/v1/projects/{project_id}/themes/{theme_id}`

Full URL: `https://developer-api.amplitude.com/v1/projects/{project_id}/themes/{theme_id}`

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

**Servers:**
- Production (US): `https://developer-api.amplitude.com/v1/projects/{project_id}/themes/{theme_id}`
- Production (EU): `https://developer-api.eu.amplitude.com/v1/projects/{project_id}/themes/{theme_id}`

Update theme

Renames a theme or changes its draft. `config` is merged into the current
draft (see `ThemeConfigPatch`): send only the values you want to change,
and `null` to reset a value to Amplitude's built-in default. The live theme
is not changed; publish the draft in Amplitude. The response carries the
full draft `config`.

To make sure nobody changed the theme since you read it, send the
`updated_at` from your last read; if the theme has changed since, the
update returns `409` and nothing is written. Omit `updated_at` to skip the
check: concurrent patches then both apply, and a later one wins for any
value both set. The check runs before the write rather than atomically
with it, so it narrows but does not close that window. Internal themes
return `409` with
`error_code: theme_is_internal`; edit them on their guide or survey in
Amplitude.

## Authorizations

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Authorization | string | Yes | — | http |

## Path parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| project_id (path) | string | Yes | 12345 | Amplitude project identifier, backed by the canonical app ID. Constraints: pattern: ^[0-9]+$ |
| theme_id (path) | string | Yes | — | Guides and surveys theme identifier. Constraints: pattern: ^[0-9]+$ |

## Header parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Idempotency-Key (header) | string | Yes | — | Required on write operations. Keys aren't stored yet, so retrying a write with the same key performs it again; a retried create makes another resource. Check whether the first attempt succeeded before you retry. Constraints: min length: 8, max length: 255 |

## Body (application/json)

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| name | string | No | — | Constraints: min length: 1, max length: 255 |
| config | object | No | {"lightMode":{"varDefaults":{"--base-accent":"rgb(120, 86, 255)"}},"darkMode":{"varDefaults":{"--base-accent":null}}} | Partial `ThemeConfig`, merged like a JSON merge patch (RFC 7396): objects merge key by key, and any other value replaces what's there. Unlike RFC 7396, `null` resets a value to Amplitude's built-in default theme, or removes it where the default has none (for example a component override or `customCss`). That works at any level, from one variable up to a whole mode. |
| config.lightMode | object | No | — | Constraints: nullable |
| config.lightMode.varDefaults | object | No | — | Variables to set, or `null` to reset a variable to its default. Setting a name that isn't a known theme variable returns `400`. `null` is accepted for any name, so you can remove one stored earlier. Constraints: nullable |
| config.lightMode.varOverrides | object | No | — | Variables to set, or `null` to reset a variable to its default. Setting a name that isn't a known theme variable returns `400`. `null` is accepted for any name, so you can remove one stored earlier. Constraints: nullable |
| config.lightMode.componentOverrides | object | No | — | Constraints: nullable |
| config.lightMode.mobileOverrides | object | No | — | Constraints: nullable |
| config.lightMode.customCss | string | No | — | Constraints: nullable |
| config.darkMode | object | No | — | Constraints: nullable |
| config.darkMode.varDefaults | object | No | — | Variables to set, or `null` to reset a variable to its default. Setting a name that isn't a known theme variable returns `400`. `null` is accepted for any name, so you can remove one stored earlier. Constraints: nullable |
| config.darkMode.varOverrides | object | No | — | Variables to set, or `null` to reset a variable to its default. Setting a name that isn't a known theme variable returns `400`. `null` is accepted for any name, so you can remove one stored earlier. Constraints: nullable |
| config.darkMode.componentOverrides | object | No | — | Constraints: nullable |
| config.darkMode.mobileOverrides | object | No | — | Constraints: nullable |
| config.darkMode.customCss | string | No | — | Constraints: nullable |
| updated_at | string | No | — | Optional. The `updated_at` from your last read of this theme; the update returns `409` if the theme has changed since. |

## Response (application/json)

**200** — Theme updated.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| data | object | Yes | — | — |
| data.id | string | Yes | — | Numeric theme identifier. Constraints: pattern: ^[0-9]+$ |
| data.object | string | Yes | — | — |
| data.project_id | string | Yes | — | Constraints: pattern: ^[0-9]+$ |
| data.name | string | Yes | — | — |
| data.platform | string | Yes | — | Target platform. Guides and surveys without an explicit platform are returned as `web`. Allowed values: web, ios, android, react-native, desktop, flutter |
| data.is_default | boolean | Yes | — | Whether this is the project's default theme for its platform. Guides and surveys with no `theme_id` use it. |
| data.is_internal | boolean | Yes | — | Internal themes are per-guide or per-survey overrides created in the guide or survey editor. Lists omit them; get them by id through a guide or survey's `theme_id`. |
| data.is_archived | boolean | Yes | — | — |
| data.has_unpublished_changes | boolean | Yes | — | Whether the unpublished draft differs from the live theme. |
| data.url | string | Yes | — | Admin URL for the theme. `null` for internal themes. Constraints: format: uri, nullable |
| data.created_by | string | Yes | — | Constraints: nullable |
| data.last_modified_by | string | Yes | — | Constraints: nullable |
| data.created_at | string | Yes | — | Constraints: format: date-time, nullable |
| data.updated_at | string | Yes | — | Constraints: format: date-time, nullable |
| data.config | oneOf | Yes | — | Theme configuration. Live by default; the unpublished draft with `include_unpublished_changes=true`. `null` when the theme has no saved configuration. Constraints: object, null |
| data.config.lightMode | object | No | — | — |
| data.config.lightMode.varDefaults | object | Yes | {"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700} | CSS variable values keyed by variable name. Colors accept any CSS color (`#ff0000`, `rgb()`, `color-mix()`, `var(--token)`). Sizes need a unit (`12px`, `1.5rem`, `100%`). Numbers such as font weights may be JSON numbers or numeric strings. Any value may reference another variable with `var(--name)`. |
| data.config.lightMode.varOverrides | object | Yes | {"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700} | CSS variable values keyed by variable name. Colors accept any CSS color (`#ff0000`, `rgb()`, `color-mix()`, `var(--token)`). Sizes need a unit (`12px`, `1.5rem`, `100%`). Numbers such as font weights may be JSON numbers or numeric strings. Any value may reference another variable with `var(--name)`. |
| data.config.lightMode.componentOverrides | object | Yes | {"tooltip":{"--background-color":"#ffffff"}} | Per-component overrides keyed by component slug (for example `tooltip` or `modal`). Each entry maps a key to a CSS variable value or to a map of CSS variables. |
| data.config.lightMode.mobileOverrides | object | Yes | — | Overrides applied by the mobile SDKs. |
| data.config.lightMode.customCss | string | No | — | Custom CSS appended to the theme. |
| data.config.darkMode | object | No | — | — |
| data.config.darkMode.varDefaults | object | Yes | {"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700} | CSS variable values keyed by variable name. Colors accept any CSS color (`#ff0000`, `rgb()`, `color-mix()`, `var(--token)`). Sizes need a unit (`12px`, `1.5rem`, `100%`). Numbers such as font weights may be JSON numbers or numeric strings. Any value may reference another variable with `var(--name)`. |
| data.config.darkMode.varOverrides | object | Yes | {"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700} | CSS variable values keyed by variable name. Colors accept any CSS color (`#ff0000`, `rgb()`, `color-mix()`, `var(--token)`). Sizes need a unit (`12px`, `1.5rem`, `100%`). Numbers such as font weights may be JSON numbers or numeric strings. Any value may reference another variable with `var(--name)`. |
| data.config.darkMode.componentOverrides | object | Yes | {"tooltip":{"--background-color":"#ffffff"}} | Per-component overrides keyed by component slug (for example `tooltip` or `modal`). Each entry maps a key to a CSS variable value or to a map of CSS variables. |
| data.config.darkMode.mobileOverrides | object | Yes | — | Overrides applied by the mobile SDKs. |
| data.config.darkMode.customCss | string | No | — | Custom CSS appended to the theme. |

```json
{
  "data": {
    "id": "string",
    "object": "theme",
    "project_id": "string",
    "name": "string",
    "platform": "web",
    "is_default": true,
    "is_internal": true,
    "is_archived": true,
    "has_unpublished_changes": true,
    "url": "https://example.com",
    "created_by": "string",
    "last_modified_by": "string",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "config": {
      "lightMode": {
        "varDefaults": {
          "--base-accent": "rgb(120, 86, 255)",
          "--font-size-base": "14px",
          "--font-weight-bold": 700
        },
        "varOverrides": {
          "--base-accent": "rgb(120, 86, 255)",
          "--font-size-base": "14px",
          "--font-weight-bold": 700
        },
        "componentOverrides": {
          "tooltip": {
            "--background-color": "#ffffff"
          }
        },
        "mobileOverrides": {},
        "customCss": "string"
      },
      "darkMode": {
        "varDefaults": {
          "--base-accent": "rgb(120, 86, 255)",
          "--font-size-base": "14px",
          "--font-weight-bold": 700
        },
        "varOverrides": {
          "--base-accent": "rgb(120, 86, 255)",
          "--font-size-base": "14px",
          "--font-weight-bold": 700
        },
        "componentOverrides": {
          "tooltip": {
            "--background-color": "#ffffff"
          }
        },
        "mobileOverrides": {},
        "customCss": "string"
      }
    }
  }
}
```

**400**

**401**

**403**

**404**

**409** — The write conflicts with the theme's current state. `error_code` is
`conflict` when `updated_at` is stale and `theme_is_internal` for
internal themes.


| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| type | string | Yes | — | Constraints: format: uri |
| title | string | Yes | — | — |
| status | integer | Yes | — | Constraints: min: 400, max: 599 |
| detail | string | No | — | Constraints: nullable |
| details | object | No | — | Constraints: nullable |
| instance | string | No | — | Constraints: format: uri, nullable |
| error_code | string | Yes | — | — |
| retryable | boolean | Yes | — | — |
| retry_after_seconds | integer | No | — | Constraints: nullable, min: 0 |
| validation_errors | object[] | No | — | Constraints: nullable |

```json
{
  "type": "https://developer-api.amplitude.com/problems/conflict",
  "title": "The write conflicts with the theme's current state. `error_code` is\n`conflict` when `updated_at` is stale and `theme_is_internal` for\ninternal themes.\n",
  "status": 409,
  "detail": "updated_at 2026-10-27T10:00:00.123456Z is stale; the theme was last updated at 2026-10-27T11:42:08.004211Z. Fetch the theme again and retry, or omit updated_at to skip this check.",
  "error_code": "conflict",
  "retryable": false
}
```

**429**

**500**

## Code samples

### cURL

```bash
curl -X PATCH "https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "config": {
    "lightMode": {
      "varDefaults": {
        "--base-accent": "rgb(37, 99, 235)"
      },
      "componentOverrides": {
        "tooltip": {
          "--background-color": "#ffffff"
        }
      }
    },
    "darkMode": {
      "varDefaults": {
        "--base-accent": "rgb(96, 165, 250)"
      }
    }
  }
}'
```

### Python

```python
import requests

response = requests.patch(
    "https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}",
    headers={
        "Content-Type": "application/json",
        "Authorization": "YOUR_API_KEY"
    },
    json={
  "config": {
    "lightMode": {
      "varDefaults": {
        "--base-accent": "rgb(37, 99, 235)"
      },
      "componentOverrides": {
        "tooltip": {
          "--background-color": "#ffffff"
        }
      }
    },
    "darkMode": {
      "varDefaults": {
        "--base-accent": "rgb(96, 165, 250)"
      }
    }
  }
}
)
data = response.json()
```

### JavaScript

```javascript
const response = await fetch("https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_KEY"
  },
  body: JSON.stringify({
  "config": {
    "lightMode": {
      "varDefaults": {
        "--base-accent": "rgb(37, 99, 235)"
      },
      "componentOverrides": {
        "tooltip": {
          "--background-color": "#ffffff"
        }
      }
    },
    "darkMode": {
      "varDefaults": {
        "--base-accent": "rgb(96, 165, 250)"
      }
    }
  }
})
});
const data = await response.json();
```

### PHP

```php
<?php
$ch = curl_init("https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = json_encode({
  "config": {
    "lightMode": {
      "varDefaults": {
        "--base-accent": "rgb(37, 99, 235)"
      },
      "componentOverrides": {
        "tooltip": {
          "--background-color": "#ffffff"
        }
      }
    },
    "darkMode": {
      "varDefaults": {
        "--base-accent": "rgb(96, 165, 250)"
      }
    }
  }
});
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
$response = curl_exec($ch);
curl_close($ch);
```

### Go

```go
package main

import (
  "bytes"
  "net/http"
)

func main() {
body := []byte("{\"config\":{\"lightMode\":{\"varDefaults\":{\"--base-accent\":\"rgb(37, 99, 235)\"},\"componentOverrides\":{\"tooltip\":{\"--background-color\":\"#ffffff\"}}},\"darkMode\":{\"varDefaults\":{\"--base-accent\":\"rgb(96, 165, 250)\"}}}}")
req, _ := http.NewRequest("PATCH", "https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}", bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "YOUR_API_KEY")
  client := &http.Client{}
  resp, _ := client.Do(req)
  defer resp.Body.Close()
}
```

### Java

```java
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}"))
      .method("PATCH", HttpRequest.BodyPublishers.ofString("{\"config\":{\"lightMode\":{\"varDefaults\":{\"--base-accent\":\"rgb(37, 99, 235)\"},\"componentOverrides\":{\"tooltip\":{\"--background-color\":\"#ffffff\"}}},\"darkMode\":{\"varDefaults\":{\"--base-accent\":\"rgb(96, 165, 250)\"}}}}"))
.header("Content-Type", "application/json")
      .header("Authorization", "YOUR_API_KEY")
      .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

### Ruby

```ruby
require "net/http"
require "json"

uri = URI("https://developer-api.amplitude.com/v1/projects/12345/themes/{theme_id}")
request = Net::HTTP::Patch.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "YOUR_API_KEY"
request.body = "{\"config\":{\"lightMode\":{\"varDefaults\":{\"--base-accent\":\"rgb(37, 99, 235)\"},\"componentOverrides\":{\"tooltip\":{\"--background-color\":\"#ffffff\"}}},\"darkMode\":{\"varDefaults\":{\"--base-accent\":\"rgb(96, 165, 250)\"}}}}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
```

