Returning.AIDevelopers
v1

API reference / Community / Appearance

.md

Update community theme colors

Change your community's theme, logos, loading animation or call-to-action button, sending only the parts you want to change.

Last updated 26 Sep 2026API v1

Method
PUT
Path
https://api.returning.ai/v1/appearance
Permission
appearance
Retries
Safe to repeat; the same values give the same result

When to use this

  • You switch the community to one of the built-in themes, or to a custom theme your team made in the dashboard.
  • You update the community icon and logos after a rebrand.
  • You turn the call-to-action button on or off, or change its text and link, for a campaign.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
appearanceShown in the dashboard as “Appearance”

Use a Community API key with appearance, and keep it on your server. The key decides the community, so never send a community ID. The published path lacks /v1: call PUT /v1/appearance, because PUT /appearance returns 404.

Behaviour#

Only the fields you send change; everything else keeps its value, down to single colours and single call-to-action settings. The change shows for every member straight away. Members aren't notified.

A theme is picked by name. For a built-in theme, the colours come from that theme and any palette you send is ignored. For a custom theme made in your dashboard, its saved colours are used and the colours you send in palette replace those. A name that is neither returns 400. The built-in dark themes are black-beauty, dark-knight, botanical-forest, rustic-pottery and hearts-desire. The built-in light themes are aqua-lolly, lush-blush, white-smoke, prairie-dance, farsighted and violet-dream.

Images must be https or http URLs, or paths starting with /assets/files/, and must end in .png, .jpg, .jpeg, .gif, .webp or .svg. Send null to remove an image.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with appearance.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send a JSON object with one or more of theme, branding, loadingAnimation and callToAction. Any field not listed here is rejected with 400.

Colours are hex (#6755ff, also 3, 4 or 8 digits), rgb() or rgba() values, or one of var(--accent-1), var(--text-1) and var(--divider-lines-1). Named colours such as red are rejected.

For a loading animation, send mode: "preset" with preset, or mode: "custom" with activeTheme and a custom entry for that theme. Each custom entry sets type and fills only the matching html or lottie field.

theme#objectOPTIONAL
Theme settings. Send only the parts you change.

Eg{"defaultMode": "dark", "dark": {"name": "dark-knight"}}

font#stringOPTIONAL
The font for the whole community.

RuleLato, Roboto, Noto, Open Sans, Source Sans Pro, Inter, Montserrat, Poppins, Nunito, Prata, Bebas Neue, Monospace, Courier, Monaco, Quicksand, Fira Code, Fira Sans, Rubik, Noto Sans, Lora, Playfair Display

defaultMode#stringOPTIONAL
Whether members see the dark or the light theme by default.

Rulelight, dark

Eg"dark"

dark#objectOPTIONAL
The dark theme.

Eg{"name": "dark-knight"}

name#stringOPTIONAL
A built-in theme name, such as dark-knight, or the name of a custom theme made in your dashboard. Required when you send palette.

RuleTheme name

Eg"dark-knight"

palette#objectOPTIONAL
Colours to change. Used only with a custom theme; a built-in theme always uses its own colours.
accent1#stringOPTIONAL
Main accent colour.

RuleHex or rgb() colour

accent2#stringOPTIONAL
Second accent shade.

RuleHex or rgb() colour

accent3#stringOPTIONAL
Third accent shade.

RuleHex or rgb() colour

accent4#stringOPTIONAL
Fourth accent shade.

RuleHex or rgb() colour

accentGradient#stringOPTIONAL
Accent gradient, any CSS gradient value such as linear-gradient(90deg, #596cff 0%, #8f5cff 100%).

RuleAny non-empty CSS value

text1#stringOPTIONAL
Main text colour.

RuleHex or rgb() colour

text2#stringOPTIONAL
Second text shade.

RuleHex or rgb() colour

text3#stringOPTIONAL
Third text shade.

RuleHex or rgb() colour

text4#stringOPTIONAL
Fourth text shade.

RuleHex or rgb() colour

text5#stringOPTIONAL
Fifth text shade.

RuleHex or rgb() colour

text6#stringOPTIONAL
Sixth text shade.

RuleHex or rgb() colour

text7#stringOPTIONAL
Inverted text colour, the opposite of text1. Worked out from text1 when you leave it out.

RuleHex or rgb() colour

background1#stringOPTIONAL
Main background colour.

RuleHex or rgb() colour

background2#stringOPTIONAL
Second background shade.

RuleHex or rgb() colour

background3#stringOPTIONAL
Third background shade.

RuleHex or rgb() colour

background4#stringOPTIONAL
Fourth background shade.

RuleHex or rgb() colour

background5#stringOPTIONAL
Fifth background shade.

RuleHex or rgb() colour

background6#stringOPTIONAL
Sixth background shade.

RuleHex or rgb() colour

background7#stringOPTIONAL
Seventh background shade.

RuleHex or rgb() colour

divider1#stringOPTIONAL
Main divider line colour.

RuleHex or rgb() colour

divider2#stringOPTIONAL
Second divider line colour.

RuleHex or rgb() colour

shadow#stringOPTIONAL
Shadow, any CSS shadow value such as 0 8px 24px rgba(0, 0, 0, 0.24).

RuleAny non-empty CSS value

label#stringOPTIONAL
Background colour of labels and mentions.

RuleHex or rgb() colour

mentionBackground#stringOPTIONAL
Older name for label. Send label instead.

RuleHex or rgb() colour; must equal label when both are sent

scrollThumb#stringOPTIONAL
Scroll bar thumb colour.

RuleHex or rgb() colour

scrollTrack#stringOPTIONAL
Scroll bar track colour.

RuleHex or rgb() colour

light#objectOPTIONAL
The light theme.
name#stringOPTIONAL
A built-in theme name, such as white-smoke, or the name of a custom theme made in your dashboard. Required when you send palette.

RuleTheme name

Eg"white-smoke"

palette#objectOPTIONAL
Colours to change. Used only with a custom theme; a built-in theme always uses its own colours.
accent1#stringOPTIONAL
Main accent colour.

RuleHex or rgb() colour

accent2#stringOPTIONAL
Second accent shade.

RuleHex or rgb() colour

accent3#stringOPTIONAL
Third accent shade.

RuleHex or rgb() colour

accent4#stringOPTIONAL
Fourth accent shade.

RuleHex or rgb() colour

accentGradient#stringOPTIONAL
Accent gradient, any CSS gradient value such as linear-gradient(90deg, #596cff 0%, #8f5cff 100%).

RuleAny non-empty CSS value

text1#stringOPTIONAL
Main text colour.

RuleHex or rgb() colour

text2#stringOPTIONAL
Second text shade.

RuleHex or rgb() colour

text3#stringOPTIONAL
Third text shade.

RuleHex or rgb() colour

text4#stringOPTIONAL
Fourth text shade.

RuleHex or rgb() colour

text5#stringOPTIONAL
Fifth text shade.

RuleHex or rgb() colour

text6#stringOPTIONAL
Sixth text shade.

RuleHex or rgb() colour

text7#stringOPTIONAL
Inverted text colour, the opposite of text1. Worked out from text1 when you leave it out.

RuleHex or rgb() colour

background1#stringOPTIONAL
Main background colour.

RuleHex or rgb() colour

background2#stringOPTIONAL
Second background shade.

RuleHex or rgb() colour

background3#stringOPTIONAL
Third background shade.

RuleHex or rgb() colour

background4#stringOPTIONAL
Fourth background shade.

RuleHex or rgb() colour

background5#stringOPTIONAL
Fifth background shade.

RuleHex or rgb() colour

background6#stringOPTIONAL
Sixth background shade.

RuleHex or rgb() colour

background7#stringOPTIONAL
Seventh background shade.

RuleHex or rgb() colour

divider1#stringOPTIONAL
Main divider line colour.

RuleHex or rgb() colour

divider2#stringOPTIONAL
Second divider line colour.

RuleHex or rgb() colour

shadow#stringOPTIONAL
Shadow, any CSS shadow value such as 0 8px 24px rgba(0, 0, 0, 0.24).

RuleAny non-empty CSS value

label#stringOPTIONAL
Background colour of labels and mentions.

RuleHex or rgb() colour

mentionBackground#stringOPTIONAL
Older name for label. Send label instead.

RuleHex or rgb() colour; must equal label when both are sent

scrollThumb#stringOPTIONAL
Scroll bar thumb colour.

RuleHex or rgb() colour

scrollTrack#stringOPTIONAL
Scroll bar track colour.

RuleHex or rgb() colour

branding#objectOPTIONAL
The community's images.

Eg{ ... }

icon#stringOPTIONAL
The community icon, or null to remove it.

RuleImage URL or path; nullable

dark#stringOPTIONAL
The logo shown with the dark theme, or null to remove it.

RuleImage URL or path; nullable

Eg"https://cdn.example.com/brand/logo-dark.svg"

light#stringOPTIONAL
The logo shown with the light theme, or null to remove it.

RuleImage URL or path; nullable

Eg"https://cdn.example.com/brand/logo-light.svg"

loadingAnimation#objectOPTIONAL
The animation members see while the community loads.
mode#stringOPTIONAL
preset for a built-in animation, or custom for your own.

Rulepreset, custom

preset#stringOPTIONAL
The built-in animation. Required when mode is preset.

Rulebar, default, circle, square

activeTheme#stringOPTIONAL
Which custom animation to show. Required when mode is custom.

Ruledark, light

custom#objectOPTIONAL
Your own animations, one for each theme.
dark#objectOPTIONAL
The custom animation for the dark theme.
type#stringOPTIONAL
html or lottie. Send the matching field and leave the other empty.

Rulehtml, lottie

html#stringOPTIONAL
HTML for the animation. Scripts, event handlers, iframe and embed tags, and javascript: or data: URLs are rejected.
lottie#stringOPTIONAL
Lottie animation JSON as a string, or a URL or path ending in .json.
light#objectOPTIONAL
The custom animation for the light theme.
type#stringOPTIONAL
html or lottie. Send the matching field and leave the other empty.

Rulehtml, lottie

html#stringOPTIONAL
HTML for the animation. Scripts, event handlers, iframe and embed tags, and javascript: or data: URLs are rejected.
lottie#stringOPTIONAL
Lottie animation JSON as a string, or a URL or path ending in .json.
callToAction#objectOPTIONAL
The call-to-action button.

Eg{ ... }

isEnabled#booleanOPTIONAL
Show the button.

Egtrue

isMobileEnabled#booleanOPTIONAL
Show the button on mobile.
content#objectOPTIONAL
What the button says and where it goes.

Eg{ ... }

text#stringOPTIONAL
The button text. Can't be empty when you also send isEnabled as true.

Eg"Open an account"

link#stringOPTIONAL
Where the button goes, an https or http URL. An empty string removes the link.

RuleURL or empty, max 2048 chars

Eg"https://www.example.com/open-account"

linkBehavior#stringOPTIONAL
Open the link in a new tab or the same one.

Rulenew, same

Eg"new"

iconImage#stringOPTIONAL
An icon shown on the button, or null to remove it.

RuleImage URL or path; nullable

style#objectOPTIONAL
How the button looks.
shape#stringOPTIONAL
The button shape.

Rulesquare, rounded, circle

backgroundColor#stringOPTIONAL
The button colour.

RuleHex or rgb() colour

borderSize#stringOPTIONAL
The border width in whole pixels.

Rule0px to 20px

borderColor#stringOPTIONAL
The border colour.

RuleHex or rgb() colour

typography#objectOPTIONAL
The button text style.
fontFamily#stringOPTIONAL
The button font.

RuleLato, Roboto, Noto, Open Sans, Source Sans Pro, Inter, Montserrat, Poppins, Nunito, Prata, Bebas Neue, Monospace, Courier, Monaco, Quicksand, Fira Code, Fira Sans, Rubik, Noto Sans, Lora, Playfair Display

fontSize#stringOPTIONAL
The text size in whole pixels.

Rule1px to 20px

fontColor#stringOPTIONAL
The text colour.

RuleHex or rgb() colour

fontStyle#stringOPTIONAL
The text style.

Rulenormal, italic, bold

textAlign#stringOPTIONAL
The text alignment.

Ruleleft, center, right

curl --request PUT \
  --url https://api.returning.ai/v1/appearance \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "theme": {
      "defaultMode": "dark",
      "dark": {
        "name": "dark-knight"
      }
    },
    "branding": {
      "logo": {
        "dark": "https://cdn.example.com/brand/logo-dark.svg",
        "light": "https://cdn.example.com/brand/logo-light.svg"
      }
    },
    "callToAction": {
      "isEnabled": true,
      "content": {
        "text": "Open an account",
        "link": "https://www.example.com/open-account",
        "linkBehavior": "new"
      }
    }
  }'

Response#

A 200 returns the community's whole appearance after the change in data, including the parts you didn't send. Palette colours come back under label, never mentionBackground.

meta#objectALWAYS

Eg{"status": "success", "statusCode": 200}

status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.

Rule200

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Update community appearance success."

data#objectALWAYS
The community's whole appearance after the change, not only the parts you sent.

Eg{ ... }

_id#stringALWAYS
Your community's ID, the same as communityID.

Eg"66f000000000000000000010"

communityID#stringALWAYS
Your community's ID.

Eg"66f000000000000000000010"

theme#object
The theme settings.

Eg{ ... }

font#stringALWAYS
The community font.

Eg"Inter"

defaultMode#stringALWAYS
The default theme, dark or light.

Eg"dark"

dark#objectALWAYS
The dark theme.

Eg{ ... }

name#stringALWAYS
The dark theme's name.

Eg"dark-knight"

palette#objectALWAYS
The dark theme's colours. A key is present only when it has a value.

Eg{ ... }

accent1#stringWHEN SET
Main accent colour.

Eg"rgb(224, 208, 162)"

accent2#stringWHEN SET
Second accent shade.

Eg"rgb(239, 225, 186)"

accent3#stringWHEN SET
Third accent shade.

Eg"rgb(250, 240, 212)"

accent4#stringWHEN SET
Fourth accent shade.

Eg"rgb(254, 249, 236)"

text1#stringWHEN SET
Main text colour.

Eg"rgb(252, 252, 252)"

text2#stringWHEN SET
Second text shade.

Eg"rgb(210, 217, 224)"

text3#stringWHEN SET
Third text shade.

Eg"rgb(200, 210, 220)"

text4#stringWHEN SET
Fourth text shade.

Eg"rgb(158, 171, 185)"

text5#stringWHEN SET
Fifth text shade.

Eg"rgb(151, 165, 181)"

text6#stringWHEN SET
Sixth text shade.

Eg"rgb(133, 147, 164)"

background1#stringWHEN SET
Main background colour.

Eg"rgb(6, 9, 33)"

background2#stringWHEN SET
Second background shade.

Eg"rgb(13, 17, 42)"

background3#stringWHEN SET
Third background shade.

Eg"rgb(23, 26, 54)"

background4#stringWHEN SET
Fourth background shade.

Eg"rgb(23, 27, 56)"

background5#stringWHEN SET
Fifth background shade.

Eg"rgb(31, 35, 65)"

background6#stringWHEN SET
Sixth background shade.

Eg"rgb(37, 41, 73)"

background7#stringWHEN SET
Seventh background shade.

Eg"rgb(53, 59, 92)"

divider1#stringWHEN SET
Main divider line colour.

Eg"rgb(79, 92, 108)"

divider2#stringWHEN SET
Second divider line colour.

Eg"rgb(158, 171, 185)"

shadow#stringWHEN SET
Shadow, any CSS shadow value such as 0 8px 24px rgba(0, 0, 0, 0.24).

Eg"rgba(6, 9, 33, 0.5)"

scrollThumb#stringWHEN SET
Scroll bar thumb colour.

Eg"rgb(34, 34, 34)"

scrollTrack#stringWHEN SET
Scroll bar track colour.

Eg"rgb(59, 59, 59)"

accentGradient#stringWHEN SET
Accent gradient, any CSS gradient value such as linear-gradient(90deg, #596cff 0%, #8f5cff 100%).
text7#stringWHEN SET
Inverted text colour, the opposite of text1. Worked out from text1 when you leave it out.
label#stringWHEN SET
Background colour of labels and mentions.
colorSettings#objectWHEN SET
One entry per colour, used by the dashboard's colour editor. You can ignore it.
light#objectALWAYS
The light theme.

Eg{ ... }

name#stringALWAYS
The light theme's name.

Eg"white-smoke"

palette#objectALWAYS
The light theme's colours. A key is present only when it has a value.

Eg{ ... }

accent1#stringWHEN SET
Main accent colour.

Eg"rgb(48, 65, 97)"

accent2#stringWHEN SET
Second accent shade.

Eg"rgb(64, 87, 130)"

accent3#stringWHEN SET
Third accent shade.

Eg"rgb(159, 171, 192)"

accent4#stringWHEN SET
Fourth accent shade.

Eg"rgb(193, 202, 218)"

text1#stringWHEN SET
Main text colour.

Eg"rgb(27, 28, 29)"

text2#stringWHEN SET
Second text shade.

Eg"rgb(71, 71, 71)"

text3#stringWHEN SET
Third text shade.

Eg"rgb(84, 84, 84)"

text4#stringWHEN SET
Fourth text shade.

Eg"rgb(103, 103, 103)"

text5#stringWHEN SET
Fifth text shade.

Eg"rgb(119, 119, 119)"

text6#stringWHEN SET
Sixth text shade.

Eg"rgb(146, 146, 146)"

background1#stringWHEN SET
Main background colour.

Eg"rgb(252, 252, 252)"

background2#stringWHEN SET
Second background shade.

Eg"rgb(240, 240, 240)"

background3#stringWHEN SET
Third background shade.

Eg"rgb(233, 233, 233)"

background4#stringWHEN SET
Fourth background shade.

Eg"rgb(228, 228, 228)"

background5#stringWHEN SET
Fifth background shade.

Eg"rgb(211, 211, 211)"

background6#stringWHEN SET
Sixth background shade.

Eg"rgb(199, 199, 199)"

background7#stringWHEN SET
Seventh background shade.

Eg"rgb(167, 167, 167)"

divider1#stringWHEN SET
Main divider line colour.

Eg"rgb(146, 146, 146)"

divider2#stringWHEN SET
Second divider line colour.

Eg"rgb(103, 103, 103)"

shadow#stringWHEN SET
Shadow, any CSS shadow value such as 0 8px 24px rgba(0, 0, 0, 0.24).

Eg"rgba(27, 28, 29, 0.35)"

scrollThumb#stringWHEN SET
Scroll bar thumb colour.

Eg"rgb(203, 203, 203)"

scrollTrack#stringWHEN SET
Scroll bar track colour.

Eg"rgb(234, 234, 234)"

accentGradient#stringWHEN SET
Accent gradient, any CSS gradient value such as linear-gradient(90deg, #596cff 0%, #8f5cff 100%).
text7#stringWHEN SET
Inverted text colour, the opposite of text1. Worked out from text1 when you leave it out.
label#stringWHEN SET
Background colour of labels and mentions.
colorSettings#objectWHEN SET
One entry per colour, used by the dashboard's colour editor. You can ignore it.
branding#object
The community's images.

Eg{ ... }

icon#string
The community icon, or null.

RuleNullable

Eg"https://cdn.example.com/brand/icon.png"

dark#string
The dark-theme logo, or null.

RuleNullable

Eg"https://cdn.example.com/brand/logo-dark.svg"

light#string
The light-theme logo, or null.

RuleNullable

Eg"https://cdn.example.com/brand/logo-light.svg"

loadingAnimation#object
The loading animation settings.

Eg{"mode": "preset", "preset": "default"}

mode#string
preset or custom.

Eg"preset"

preset#string
The built-in animation.

Eg"default"

activeTheme#string
Which custom animation is shown.
custom#objectWHEN SET
The custom animations.
dark#objectWHEN SET
The dark-theme animation.
type#stringALWAYS
html or lottie.
html#stringALWAYS
The HTML animation.
lottie#stringALWAYS
The Lottie animation.
light#objectWHEN SET
The light-theme animation.
type#stringALWAYS
html or lottie.
html#stringALWAYS
The HTML animation.
lottie#stringALWAYS
The Lottie animation.
callToAction#object
The call-to-action button.

Eg{ ... }

isEnabled#boolean
true when the button is shown.

Egtrue

isMobileEnabled#boolean
true when the button is shown on mobile.

Egtrue

content#object
The button text and link.

Eg{ ... }

text#stringWHEN SET
The button text.

Eg"Open an account"

link#stringWHEN SET
The button link.

Eg"https://www.example.com/open-account"

linkBehavior#stringWHEN SET
new or same.

Eg"new"

iconImage#string
The button icon, or null.

RuleNullable

Egnull

style#object
The button style.

Eg{ ... }

shape#stringWHEN SET
The button shape.

Eg"rounded"

backgroundColor#stringWHEN SET
The button colour.

Eg"var(--accent-1)"

borderSize#stringWHEN SET
The border width.

Eg"0px"

borderColor#stringWHEN SET
The border colour.

Eg"var(--accent-1)"

typography#object
The button text style.

Eg{ ... }

fontFamily#stringWHEN SET
The button font.

Eg"Inter"

fontSize#stringWHEN SET
The text size.

Eg"14px"

fontColor#stringWHEN SET
The text colour.

Eg"var(--text-1)"

fontStyle#stringWHEN SET
The text style.

Eg"bold"

textAlign#stringWHEN SET
The text alignment.

Eg"center"

createdAt#stringALWAYS
When the community was created.

Eg"2026-09-20T08:30:00.000Z"

updatedAt#stringALWAYS
When the community last changed.

Eg"2026-09-26T08:30:00.000Z"

{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Update community appearance success.",
  "data": {
    "_id": "66f000000000000000000010",
    "communityID": "66f000000000000000000010",
    "theme": {
      "font": "Inter",
      "defaultMode": "dark",
      "dark": {
        "name": "dark-knight",
        "palette": {
          "accent1": "rgb(224, 208, 162)",
          "accent2": "rgb(239, 225, 186)",
          "accent3": "rgb(250, 240, 212)",
          "accent4": "rgb(254, 249, 236)",
          "text1": "rgb(252, 252, 252)",
          "text2": "rgb(210, 217, 224)",
          "text3": "rgb(200, 210, 220)",
          "text4": "rgb(158, 171, 185)",
          "text5": "rgb(151, 165, 181)",
          "text6": "rgb(133, 147, 164)",
          "text7": "rgb(27, 28, 29)",
          "background1": "rgb(6, 9, 33)",
          "background2": "rgb(13, 17, 42)",
          "background3": "rgb(23, 26, 54)",
          "background4": "rgb(23, 27, 56)",
          "background5": "rgb(31, 35, 65)",
          "background6": "rgb(37, 41, 73)",
          "background7": "rgb(53, 59, 92)",
          "divider1": "rgb(79, 92, 108)",
          "divider2": "rgb(158, 171, 185)",
          "shadow": "rgba(6, 9, 33, 0.5)",
          "label": "rgb(23, 26, 54)",
          "scrollThumb": "rgb(34, 34, 34)",
          "scrollTrack": "rgb(59, 59, 59)"
        },
        "colorSettings": {
          "accent1": {
            "type": "solid",
            "solid": "rgb(224, 208, 162)"
          },
          "accent2": {
            "type": "solid",
            "solid": "rgb(239, 225, 186)"
          },
          "accent3": {
            "type": "solid",
            "solid": "rgb(250, 240, 212)"
          },
          "accent4": {
            "type": "solid",
            "solid": "rgb(254, 249, 236)"
          },
          "text1": {
            "type": "solid",
            "solid": "rgb(252, 252, 252)"
          },
          "text2": {
            "type": "solid",
            "solid": "rgb(210, 217, 224)"
          },
          "text3": {
            "type": "solid",
            "solid": "rgb(200, 210, 220)"
          },
          "text4": {
            "type": "solid",
            "solid": "rgb(158, 171, 185)"
          },
          "text5": {
            "type": "solid",
            "solid": "rgb(151, 165, 181)"
          },
          "text6": {
            "type": "solid",
            "solid": "rgb(133, 147, 164)"
          },
          "text7": {
            "type": "solid",
            "solid": "rgb(27, 28, 29)"
          },
          "background1": {
            "type": "solid",
            "solid": "rgb(6, 9, 33)"
          },
          "background2": {
            "type": "solid",
            "solid": "rgb(13, 17, 42)"
          },
          "background3": {
            "type": "solid",
            "solid": "rgb(23, 26, 54)"
          },
          "background4": {
            "type": "solid",
            "solid": "rgb(23, 27, 56)"
          },
          "background5": {
            "type": "solid",
            "solid": "rgb(31, 35, 65)"
          },
          "background6": {
            "type": "solid",
            "solid": "rgb(37, 41, 73)"
          },
          "background7": {
            "type": "solid",
            "solid": "rgb(53, 59, 92)"
          },
          "divider1": {
            "type": "solid",
            "solid": "rgb(79, 92, 108)"
          },
          "divider2": {
            "type": "solid",
            "solid": "rgb(158, 171, 185)"
          },
          "shadow": {
            "type": "solid",
            "solid": "rgba(6, 9, 33, 0.5)"
          },
          "label": {
            "type": "solid",
            "solid": "rgb(23, 26, 54)"
          },
          "scrollThumb": {
            "type": "solid",
            "solid": "rgb(34, 34, 34)"
          },
          "scrollTrack": {
            "type": "solid",
            "solid": "rgb(59, 59, 59)"
          }
        }
      },
      "light": {
        "name": "white-smoke",
        "palette": {
          "accent1": "rgb(48, 65, 97)",
          "accent2": "rgb(64, 87, 130)",
          "accent3": "rgb(159, 171, 192)",
          "accent4": "rgb(193, 202, 218)",
          "text1": "rgb(27, 28, 29)",
          "text2": "rgb(71, 71, 71)",
          "text3": "rgb(84, 84, 84)",
          "text4": "rgb(103, 103, 103)",
          "text5": "rgb(119, 119, 119)",
          "text6": "rgb(146, 146, 146)",
          "text7": "rgb(252, 252, 252)",
          "background1": "rgb(252, 252, 252)",
          "background2": "rgb(240, 240, 240)",
          "background3": "rgb(233, 233, 233)",
          "background4": "rgb(228, 228, 228)",
          "background5": "rgb(211, 211, 211)",
          "background6": "rgb(199, 199, 199)",
          "background7": "rgb(167, 167, 167)",
          "divider1": "rgb(146, 146, 146)",
          "divider2": "rgb(103, 103, 103)",
          "shadow": "rgba(27, 28, 29, 0.35)",
          "label": "rgb(233, 233, 233)",
          "scrollThumb": "rgb(203, 203, 203)",
          "scrollTrack": "rgb(234, 234, 234)"
        },
        "colorSettings": {
          "accent1": {
            "type": "solid",
            "solid": "rgb(48, 65, 97)"
          },
          "accent2": {
            "type": "solid",
            "solid": "rgb(64, 87, 130)"
          },
          "accent3": {
            "type": "solid",
            "solid": "rgb(159, 171, 192)"
          },
          "accent4": {
            "type": "solid",
            "solid": "rgb(193, 202, 218)"
          },
          "text1": {
            "type": "solid",
            "solid": "rgb(27, 28, 29)"
          },
          "text2": {
            "type": "solid",
            "solid": "rgb(71, 71, 71)"
          },
          "text3": {
            "type": "solid",
            "solid": "rgb(84, 84, 84)"
          },
          "text4": {
            "type": "solid",
            "solid": "rgb(103, 103, 103)"
          },
          "text5": {
            "type": "solid",
            "solid": "rgb(119, 119, 119)"
          },
          "text6": {
            "type": "solid",
            "solid": "rgb(146, 146, 146)"
          },
          "text7": {
            "type": "solid",
            "solid": "rgb(252, 252, 252)"
          },
          "background1": {
            "type": "solid",
            "solid": "rgb(252, 252, 252)"
          },
          "background2": {
            "type": "solid",
            "solid": "rgb(240, 240, 240)"
          },
          "background3": {
            "type": "solid",
            "solid": "rgb(233, 233, 233)"
          },
          "background4": {
            "type": "solid",
            "solid": "rgb(228, 228, 228)"
          },
          "background5": {
            "type": "solid",
            "solid": "rgb(211, 211, 211)"
          },
          "background6": {
            "type": "solid",
            "solid": "rgb(199, 199, 199)"
          },
          "background7": {
            "type": "solid",
            "solid": "rgb(167, 167, 167)"
          },
          "divider1": {
            "type": "solid",
            "solid": "rgb(146, 146, 146)"
          },
          "divider2": {
            "type": "solid",
            "solid": "rgb(103, 103, 103)"
          },
          "shadow": {
            "type": "solid",
            "solid": "rgba(27, 28, 29, 0.35)"
          },
          "label": {
            "type": "solid",
            "solid": "rgb(233, 233, 233)"
          },
          "scrollThumb": {
            "type": "solid",
            "solid": "rgb(203, 203, 203)"
          },
          "scrollTrack": {
            "type": "solid",
            "solid": "rgb(234, 234, 234)"
          }
        }
      }
    },
    "branding": {
      "icon": "https://cdn.example.com/brand/icon.png",
      "logo": {
        "dark": "https://cdn.example.com/brand/logo-dark.svg",
        "light": "https://cdn.example.com/brand/logo-light.svg"
      }
    },
    "loadingAnimation": {
      "mode": "preset",
      "preset": "default"
    },
    "callToAction": {
      "isEnabled": true,
      "isMobileEnabled": true,
      "content": {
        "text": "Open an account",
        "link": "https://www.example.com/open-account",
        "linkBehavior": "new",
        "iconImage": null
      },
      "style": {
        "shape": "rounded",
        "backgroundColor": "var(--accent-1)",
        "borderSize": "0px",
        "borderColor": "var(--accent-1)"
      },
      "typography": {
        "fontFamily": "Inter",
        "fontSize": "14px",
        "fontColor": "var(--text-1)",
        "fontStyle": "bold",
        "textAlign": "center"
      }
    },
    "createdAt": "2026-09-20T08:30:00.000Z",
    "updatedAt": "2026-09-26T08:30:00.000Z"
  }
}

Errors#

Every error carries meta.status and meta.statusCode, with the reason in detail. Key errors and field validation errors also carry meta.code; other 400 errors and the 500 and 502 errors don't.

Fix the request05

400Fix the request
detail says which: Request body must be a non-empty object (send at least one of theme, branding, loadingAnimation or callToAction), Theme 'name' not found for mode 'dark' (use a built-in theme name or a custom theme from your dashboard), or the unsafe loading-animation HTML message (remove scripts, event handlers and embedded frames). These 400 errors have no meta.code. Nothing changed.
400VALIDATION_FAILEDFix the request
A field breaks its rule, such as a colour that isn't hex or rgb(), a palette without name, a loading animation whose mode doesn't match its other fields, or a field this endpoint doesn't accept. detail names each field. Nothing changed.
401AUTH_API_KEY_REQUIREDFix the request
No key was sent. Send Authorization: Bearer <API_KEY>.
401AUTH_API_KEY_INVALIDFix the request
The key is unknown, expired or malformed. Use a current Community API key.
403AUTH_PERMISSION_REQUIREDFix the request
The key lacks appearance. Add the permission in Settings > Integration > API Keys.

Fix the data01

404Fix the data
The community that owns this key no longer exists. Contact Returning.AI support.

Retry with backoff03

500Retry with backoff
The change failed unexpectedly. Retry with backoff; sending the same values again is safe.
502Retry with backoff
The change couldn't be completed just now (Upstream service is temporarily unavailable.). Retry with backoff.
401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff
The key could not be checked just now. Retry with backoff; the key itself may be fine.
{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Validation failed",
  "detail": {
    "theme": "theme has invalid name, palette, or label alias relationships"
  },
  "solution": "Please check the request and try again"
}

Next step#

Update community bot profilePUT/v1/community-botGive the community bot a name and avatar that match the new look.