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 theupdated_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 witherror_code: theme_is_internal; edit them on their guide or survey in
Amplitude.
/v1/projects/{project_id}/themes/{theme_id}Authorizations
Authorizationstringrequiredhttp
Path parameters
project_idstringrequiredAmplitude project identifier, backed by the canonical app ID.
12345pattern: ^[0-9]+$theme_idstringrequiredGuides and surveys theme identifier.
pattern: ^[0-9]+$Header parameters
Idempotency-KeystringrequiredRequired 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.
min length: 8max length: 255Body
application/jsonnamestringmin length: 1max length: 255configobjectPartial 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.
{"lightMode":{"varDefaults":{"--base-accent":"rgb(120, 86, 255)"}},"darkMode":{"varDefaults":{"--base-accent":null}}}Show child attributes
lightModeobjectnullablevarDefaultsobjectVariables 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.
nullablevarOverridesobjectVariables 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.
nullablecomponentOverridesobjectnullablemobileOverridesobjectnullablecustomCssstringnullabledarkModeobjectnullablevarDefaultsobjectVariables 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.
nullablevarOverridesobjectVariables 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.
nullablecomponentOverridesobjectnullablemobileOverridesobjectnullablecustomCssstringnullableupdated_atstringOptional. The updated_at from your last read of this theme;
the update returns 409 if the theme has changed since.
Response
application/jsondataobjectrequiredShow child attributes
idstringrequiredNumeric theme identifier.
pattern: ^[0-9]+$objectstringrequiredproject_idstringrequiredpattern: ^[0-9]+$namestringrequiredplatformstringrequiredTarget platform. Guides and surveys without an explicit platform are
returned as web.
webiosandroidreact-nativedesktopflutteris_defaultbooleanrequiredWhether this is the project's default theme for its platform. Guides
and surveys with no theme_id use it.
is_internalbooleanrequiredInternal 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_archivedbooleanrequiredhas_unpublished_changesbooleanrequiredWhether the unpublished draft differs from the live theme.
urlstringrequiredAdmin URL for the theme. null for internal themes.
format: urinullablecreated_bystringrequirednullablelast_modified_bystringrequirednullablecreated_atstringrequiredformat: date-timenullableupdated_atstringrequiredformat: date-timenullableconfigoneOfrequiredTheme configuration. Live by default; the unpublished draft with
include_unpublished_changes=true. null when the theme has no
saved configuration.
objectnulllightModeobjectvarDefaultsobjectrequiredCSS 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).
{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}varOverridesobjectrequiredCSS 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).
{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}componentOverridesobjectrequiredPer-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.
{"tooltip":{"--background-color":"#ffffff"}}mobileOverridesobjectrequiredOverrides applied by the mobile SDKs.
customCssstringCustom CSS appended to the theme.
darkModeobjectvarDefaultsobjectrequiredCSS 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).
{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}varOverridesobjectrequiredCSS 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).
{"--base-accent":"rgb(120, 86, 255)","--font-size-base":"14px","--font-weight-bold":700}componentOverridesobjectrequiredPer-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.
{"tooltip":{"--background-color":"#ffffff"}}mobileOverridesobjectrequiredOverrides applied by the mobile SDKs.
customCssstringCustom CSS appended to the theme.
error_code is
conflict when updated_at is stale and theme_is_internal for
internal themes.
typestringrequiredformat: urititlestringrequiredstatusintegerrequiredmin: 400max: 599detailstringnullabledetailsobjectnullableinstancestringformat: urinullableerror_codestringrequiredretryablebooleanrequiredretry_after_secondsintegernullablemin: 0validation_errorsobject[]nullableWas 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.