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.

post/v1/projects/{project_id}/themes

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

Example:12345
Constraints:pattern: ^[0-9]+$

Header parameters

Idempotency-Keystringrequired

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: 8max length: 255

Body

application/json
namestringrequired
Constraints:min length: 1max length: 255
platformstring

Target platform. Guides and surveys without an explicit platform are returned as web.

Allowed values:webiosandroidreact-nativedesktopflutter
configobject

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.

Example:{"lightMode":{"varDefaults":{"--base-accent":"rgb(120, 86, 255)"}},"darkMode":{"varDefaults":{"--base-accent":null}}}
Show child attributes
lightModeobject
Constraints:nullable
varDefaultsobject

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
varOverridesobject

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
componentOverridesobject
Constraints:nullable
mobileOverridesobject
Constraints:nullable
customCssstring
Constraints:nullable
darkModeobject
Constraints:nullable
varDefaultsobject

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
varOverridesobject

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
componentOverridesobject
Constraints:nullable
mobileOverridesobject
Constraints:nullable
customCssstring
Constraints:nullable

Response

application/json
201· Theme created.
dataobjectrequired
Show child attributes
idstringrequired

Numeric theme identifier.

Constraints:pattern: ^[0-9]+$
objectstringrequired
project_idstringrequired
Constraints:pattern: ^[0-9]+$
namestringrequired
platformstringrequired

Target platform. Guides and surveys without an explicit platform are returned as web.

Allowed values:webiosandroidreact-nativedesktopflutter
is_defaultbooleanrequired

Whether this is the project's default theme for its platform. Guides and surveys with no theme_id use it.

is_internalbooleanrequired

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.

is_archivedbooleanrequired
has_unpublished_changesbooleanrequired

Whether the unpublished draft differs from the live theme.

urlstringrequired

Admin URL for the theme. null for internal themes.

Constraints:format: urinullable
created_bystringrequired
Constraints:nullable
last_modified_bystringrequired
Constraints:nullable
created_atstringrequired
Constraints:format: date-timenullable
updated_atstringrequired
Constraints:format: date-timenullable
configoneOfrequired

Theme configuration. Live by default; the unpublished draft with include_unpublished_changes=true. null when the theme has no saved configuration.

Constraints:objectnull
lightModeobject
varDefaultsobjectrequired

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

Example:{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}
varOverridesobjectrequired

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

Example:{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}
componentOverridesobjectrequired

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.

Example:{"tooltip":{"--background-color":"#ffffff"}}
mobileOverridesobjectrequired

Overrides applied by the mobile SDKs.

customCssstring

Custom CSS appended to the theme.

darkModeobject
varDefaultsobjectrequired

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

Example:{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}
varOverridesobjectrequired

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

Example:{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}
componentOverridesobjectrequired

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.

Example:{"tooltip":{"--background-color":"#ffffff"}}
mobileOverridesobjectrequired

Overrides applied by the mobile SDKs.

customCssstring

Custom CSS appended to the theme.

Was this helpful?

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