---
title: amp themes
description: "Reference for amp themes list, get, create, and update, which manage the draft themes that guides and surveys share."
product: general
lang: en
last_updated: 2026-11-18
token_estimate: 1557
---
# amp themes

`amp themes` manages the themes that guides and surveys share. Changes apply to a theme's draft; publish the draft in Amplitude. Read commands require `guides:read` and `surveys:read`; create and update require `guides:write` and `surveys:write`.

## `amp themes list`

Returns the guides and surveys themes in the project, newest first. Results use the standard Developer API list envelope with cursor pagination (`cursor`, `limit`). List items omit `config`; get a theme by id to read it.

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

Internal themes (per-guide or per-survey overrides) are not listed. Read them by id through a guide or survey's `theme_id`. Assistant themes are not part of this API.

```bash
amp themes list --project <project_id> --platform web
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--cursor` | string | No | Opaque cursor from `pagination.next_cursor` on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 `pagination_not_supported`. Alias: `--next-cursor`. |
| `--limit` | integer | No | Number of items to return. Defaults to 50, max 200. |
| `--platform` | string | No |  |
| `--include-archived` | boolean | No |  |

Requires the `guides:read` and `surveys:read` scopes.

## `amp themes get`

Returns a guides and surveys theme. `config` is the live theme by default. Archived themes return `404`.

```bash
amp themes get --project <project_id> --theme <theme_id> --include-unpublished-changes
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--theme` | string | Yes | Guides and surveys theme identifier. Alias: `--theme-id`. |
| `--include-unpublished-changes` | boolean | No | When true, `config` is the unpublished draft instead of the live theme. Use `has_unpublished_changes` to check whether a draft differs. |

Requires the `guides:read` and `surveys:read` scopes.

## `amp themes create`

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.

```bash
amp themes create --project <project_id> --name "Brand"
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--name` | string | Yes |  |
| `--platform` | string: `web`, `ios`, `android`, `react-native`, `desktop`, `flutter` | No | Target platform. Guides and surveys without an explicit platform are returned as `web`. |
| `--config` | object | No | 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. |

Requires the `guides:write` and `surveys:write` scopes.

## `amp themes update`

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.

```bash
amp themes update --project <project_id> --theme <theme_id> --config '{"lightMode":{"varDefaults":{"--base-accent":"rgb(37, 99, 235)"}}}'
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--theme` | string | Yes | Guides and surveys theme identifier. Alias: `--theme-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--name` | string | No |  |
| `--config` | object | No | 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. |
| `--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. |

Requires the `guides:write` and `surveys:write` scopes.

