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.

patch/v1/projects/{project_id}/themes/{theme_id}

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

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

Guides and surveys theme identifier.

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
namestring
Constraints:min length: 1max length: 255
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
updated_atstring

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

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.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
detailsobject
Constraints:nullable
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable

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.