---
title: Create theme
description: "Creates a guides and surveys theme. Both the live theme and the draft start as Amplitude's built-in default theme, and config is merged into the draft (see T…"
product: general
lang: en
last_updated: 2026-10-30
token_estimate: 3338
---
# Create theme

## Create theme

**POST** `/v1/projects/{project_id}/themes`

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

> 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`
- Production (EU): `https://developer-api.eu.amplitude.com/v1/projects/{project_id}/themes`

Create theme

Creates a guides and surveys theme. Both the live theme and the draft
start as Amplitude's built-in default theme, and `config` is merged into
the draft (see `ThemeConfigPatch`), so you only send the values you want
to change. Nothing changes for users until the draft is published in
Amplitude. The response carries the draft `config`.

The new theme isn't the default unless the platform has no default theme
and you can publish theme changes, in which case Amplitude makes it the
default, as it does in the theme editor. A `platform` that isn't enabled
for the project returns `400`. Publishing, archiving, and changing the
default theme are not available via API.

## 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]+$ |

## 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 | Yes | — | Constraints: min length: 1, max length: 255 |
| platform | string | No | — | Target platform. Guides and surveys without an explicit platform are returned as `web`. Allowed values: web, ios, android, react-native, desktop, flutter |
| 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 |

## Response (application/json)

**201** — Theme created.

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

**429**

**500**

## Code samples

### cURL

```bash
curl -X POST "https://developer-api.amplitude.com/v1/projects/12345/themes" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
  "name": "Holiday"
}'
```

### Python

```python
import requests

response = requests.post(
    "https://developer-api.amplitude.com/v1/projects/12345/themes",
    headers={
        "Content-Type": "application/json",
        "Authorization": "YOUR_API_KEY"
    },
    json={
  "name": "Holiday"
}
)
data = response.json()
```

### JavaScript

```javascript
const response = await fetch("https://developer-api.amplitude.com/v1/projects/12345/themes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_KEY"
  },
  body: JSON.stringify({
  "name": "Holiday"
})
});
const data = await response.json();
```

### PHP

```php
<?php
$ch = curl_init("https://developer-api.amplitude.com/v1/projects/12345/themes");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = json_encode({
  "name": "Holiday"
});
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("{\"name\":\"Holiday\"}")
req, _ := http.NewRequest("POST", "https://developer-api.amplitude.com/v1/projects/12345/themes", 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"))
      .method("POST", HttpRequest.BodyPublishers.ofString("{\"name\":\"Holiday\"}"))
.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")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "YOUR_API_KEY"
request.body = "{\"name\":\"Holiday\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
```

