Update community theme colors

What this endpoint does

Updates theme, branding, loading animation, or CTA for the community resolved from the Bearer API key.

Apidog documents PUT /appearance. On https://api.returning.ai that unprefixed path 404s. The mounted path is PUT /v1/appearance.

This write changes a live community. Do not send documentation examples against a production community.

INFO

Safer path

Prove PUT /v1/appearance with an empty object first (400). Only PUT real theme payloads against a disposable community after approval.

Quick start

Do not run that body against a live community from docs. Empty {} is the safe probe: it does not apply a theme.

Authentication and permission

Bearer community API key. Required permission: appearance. Community comes from the token; do not send communityID. Keep the key server-side.

Complete examples

Unprefixed path (404). PUT /appearance is not mounted.

Empty object (400). PUT /v1/appearance with {} returns Validation failed detail.body: Request body must be a non-empty object.

Partial theme write (200). PUT /v1/appearance with {"theme":{"defaultMode":"dark"}} returned message Update community appearance success. data includes _id, communityID, theme, branding, loadingAnimation, callToAction, createdAt, and updatedAt. theme.defaultMode was dark. Palette fields under theme.dark / theme.light are community-specific; copy them from an approved readback, not from this page.

{
  "meta": { "status": "success", "statusCode": 200 },
  "message": "Update community appearance success.",
  "data": {
    "_id": "<appearanceId>",
    "theme": { "defaultMode": "dark", "font": "Roboto" }
  }
}

Partial updates are the contract: send only theme, branding, loadingAnimation, and/or callToAction.

Success and readback

HTTP 200 Update community appearance success. There is no separate GET appearance route on the pages in this folder. Confirm the UI if you need the live palette.

Errors and recovery

Status	When	Recovery
`404`	`PUT /appearance` without `/v1`	Call `/v1/appearance`.
`400` `Request body must be a non-empty object`	`{}`	Send a non-empty object. Do not discover fields against a live community.
`401`	Missing or invalid token	Add a valid community key with `appearance`.

Retry safety

WARNING

Exact retry

A timeout can hide a successful branding write. Do not retry live theme PUTs without checking the community UI. There is no idempotency key.

Gotchas

Prefix /v1. The OpenAPI path /appearance 404s on this gateway.

PUT /v1/communities (name/URL) is not mounted. That is a different page.

Widget theme color is not this API.

Next steps

Update community bot profile

Bot name/avatar is a separate /v1/community-bot PUT.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request PUT 'https://adss-production.returning.ai/apis/partner/appearance' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "theme": { "font": "Playfair Display", "defaultMode": "light", "dark": { "name": "botanical-forest" }, "light": { "name": "prairie-dance" } }, "branding": { "icon": "https://d1qp7obm8na1ru.cloudfront.net/57ef33a0-3896-11f1-95a3-399026424a57_appearance.webp", "logo": { "dark": "https://d1qp7obm8na1ru.cloudfront.net/57ef33a0-3896-11f1-95a3-399026424a57_appearance.webp", "light": "https://d1qp7obm8na1ru.cloudfront.net/57ef33a0-3896-11f1-95a3-399026424a57_appearance.webp" } }, "callToAction": { "content": { "text": "Thingyan mode", "link": "https://www.google.com/", "linkBehavior": "same" } }, "loadingAnimation": { "mode": "custom", "preset": "default", "activeTheme": "light" } }'

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Update community appearance success.", "data": { "_id": "697df8837aae7afa852c03ce", "communityID": "6502c9e514a3e564c5c09c0a", "theme": { "font": "Playfair Display", "defaultMode": "light", "dark": { "name": "botanical-forest", "palette": { "accent1": "rgb(233, 115, 123)", "accent2": "rgb(238, 153, 159)", "accent3": "rgb(241, 179, 184)", "accent4": "rgb(252, 210, 213)", "background1": "rgb(0, 44, 38)", "background2": "rgb(5, 52, 47)", "background3": "rgb(15, 61, 59)", "background4": "rgb(15, 62, 61)", "background5": "rgb(23, 70, 70)", "background6": "rgb(29, 76, 78)", "background7": "rgb(45, 95, 97)", "text1": "rgb(228, 241, 238)", "text2": "rgb(172, 213, 203)", "text3": "rgb(159, 201, 191)", "text4": "rgb(132, 178, 167)", "text5": "rgb(110, 164, 151)", "text6": "rgb(102, 149, 138)", "divider1": "rgb(69, 128, 114)", "divider2": "rgb(132, 178, 167)", "shadow": "rgba(0, 44, 38, 0.5)", "mentionBackground": "rgb(15, 61, 59)", "scrollThumb": "rgb(34, 34, 34)", "scrollTrack": "rgb(59, 59, 59)" } }, "light": { "name": "prairie-dance", "palette": { "accent1": "rgb(174, 76, 76)", "accent2": "rgb(191, 100, 100)", "accent3": "rgb(208, 122, 122)", "accent4": "rgb(224, 162, 162)", "background1": "rgb(252, 252, 252)", "background2": "rgb(252, 248, 241)", "background3": "rgb(250, 244, 231)", "background4": "rgb(243, 236, 218)", "background5": "rgb(233, 224, 202)", "background6": "rgb(221, 212, 190)", "background7": "rgb(200, 188, 161)", "text1": "rgb(62, 79, 60)", "text2": "rgb(73, 91, 70)", "text3": "rgb(86, 104, 83)", "text4": "rgb(117, 126, 95)", "text5": "rgb(127, 136, 107)", "text6": "rgb(143, 151, 124)", "divider1": "rgb(161, 169, 142)", "divider2": "rgb(117, 126, 95)", "shadow": "rgba(62, 79, 60, 0.35)", "mentionBackground": "rgb(250, 244, 231)", "scrollThumb": "rgb(203, 203, 203)", "scrollTrack": "rgb(234, 234, 234)" } } }, "branding": { "icon": "https://d1qp7obm8na1ru.cloudfront.net/57ef33a0-3896-11f1-95a3-399026424a57_appearance.webp", "logo": { "dark": "https://d1qp7obm8na1ru.cloudfront.net/57ef33a0-3896-11f1-95a3-399026424a57_appearance.webp", "light": "https://d1qp7obm8na1ru.cloudfront.net/57ef33a0-3896-11f1-95a3-399026424a57_appearance.webp" }, "splash": { "desktop": "https://chartsnapshot-genesiv.s3.amazonaws.com/9f522570-fc66-11f0-8cde-a383b71d30de_image.webp", "mobile": "https://s3.us-east-1.amazonaws.com/genesiv-forexchatroom/94ba2010a0ed7518691b1f3e37335e1.jpg" } }, "loadingAnimation": { "mode": "custom", "preset": "default", "activeTheme": "light", "custom": { "dark": { "type": "lottie", "html": "<h1>hello Min Ga Lar Par <h1>", "lottie": "https://pre-staging-application.returning.ai/assets/files/communities/6502c9e514a3e564c5c09c0a/loading-animations/dark-lottie-1777391140614.json" }, "light": { "type": "html", "html": "<div class=\"loader\">\n <div class=\"loader-inner\">\n <div class=\"loader-line-wrap\">\n <div class=\"loader-line\"></div>\n </div>\n <div class=\"loader-line-wrap\">\n <div class=\"loader-line\"></div>\n </div>\n <div class=\"loader-line-wrap\">\n <div class=\"loader-line\"></div>\n </div>\n <div class=\"loader-line-wrap\">\n <div class=\"loader-line\"></div>\n </div>\n <div class=\"loader-line-wrap\">\n <div class=\"loader-line\"></div>\n </div>\n </div>\n </div>\n<style>\n.loader {\n width: 130px;\n height: 130px;\n background: transparent;\n bottom: 0;\n left: 0;\n overflow: hidden;\n position: relative;\n right: 0;\n top: 0;\n z-index: 99999;\n}\n\n.loader-inner {\n bottom: 0;\n height: 60px;\n left: 0;\n margin: auto;\n position: absolute;\n right: 0;\n top: 0;\n width: 100px;\n}\n\n.loader-line-wrap {\n animation: \n spin 2000ms cubic-bezier(.175, .885, .32, 1.275) infinite\n ;\n box-sizing: border-box;\n height: 50px;\n left: 0;\n overflow: hidden;\n position: absolute;\n top: 0;\n transform-origin: 50% 100%;\n width: 100px;\n}\n.loader-line {\n border: 4px solid transparent;\n border-radius: 100%;\n box-sizing: border-box;\n height: 100px;\n left: 0;\n margin: 0 auto;\n position: absolute;\n right: 0;\n top: 0;\n width: 100px;\n}\n.loader-line-wrap:nth-child(1) { animation-delay: -50ms; }\n.loader-line-wrap:nth-child(2) { animation-delay: -100ms; }\n.loader-line-wrap:nth-child(3) { animation-delay: -150ms; }\n.loader-line-wrap:nth-child(4) { animation-delay: -200ms; }\n.loader-line-wrap:nth-child(5) { animation-delay: -250ms; }\n\n.loader-line-wrap:nth-child(1) .loader-line {\n border-color: hsl(0, 80%, 60%);\n height: 90px;\n width: 90px;\n top: 7px;\n}\n.loader-line-wrap:nth-child(2) .loader-line {\n border-color: hsl(60, 80%, 60%);\n height: 76px;\n width: 76px;\n top: 14px;\n}\n.loader-line-wrap:nth-child(3) .loader-line {\n border-color: hsl(120, 80%, 60%);\n height: 62px;\n width: 62px;\n top: 21px;\n}\n.loader-line-wrap:nth-child(4) .loader-line {\n border-color: hsl(180, 80%, 60%);\n height: 48px;\n width: 48px;\n top: 28px;\n}\n.loader-line-wrap:nth-child(5) .loader-line {\n border-color: hsl(240, 80%, 60%);\n height: 34px;\n width: 34px;\n top: 35px;\n}\n\n@keyframes spin {\n 0%, 15% {\n transform: rotate(0);\n }\n 100% {\n transform: rotate(360deg);\n }\n}\n</style>", "lottie": "https://pre-staging-application.returning.ai/assets/files/communities/6502c9e514a3e564c5c09c0a/loading-animations/light-lottie-1777391141715.json" } } }, "callToAction": { "isEnabled": true, "isMobileEnabled": true, "content": { "text": "Thingyan mode", "link": "https://www.google.com/", "linkBehavior": "same", "iconImage": "https://chartsnapshot-genesiv.s3.amazonaws.com/a911d540-e002-11f0-9ded-bd382b6c5e6d_A_digital_illustration_depicts_a_young_male_AI_dev_compressed.webp" }, "style": { "shape": "square", "backgroundColor": "var(--accent-1)", "borderSize": "1", "borderColor": "var(--divider-lines-1)" }, "typography": { "fontFamily": "Poppins", "fontSize": "16px", "fontColor": "var(--text-1)", "fontStyle": "normal", "textAlign": "center" } }, "createdAt": "2026-04-26T04:54:10.575Z", "updatedAt": "2026-04-28T16:44:51.234Z" } }

Update community theme colors

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps