design_theme_get — read the current theme
Read a channel's tone, two primary color overrides, effective colors, and revision before preparing a theme change. Reading an uninitialized theme does not create it. Static guidance is available through screen_describe with screenId:design.theme.
Input and access
| Field | Type | Required | Constraint |
|---|---|---|---|
channelCode |
string | Yes | Nonempty; use a known channel code, not a numeric channel ID, title, or domain. |
{"channelCode":"selected-channel-code"}
Replace the placeholder with a code obtained through channel discovery, a creation result, or the authorized hosted resource. There is no default target; null and omission are invalid. Confirm the selected channel context when needed.
The HTTP adapter requires the stored account connection, the selected channel credential, and the configured PUBL_CHANNEL_ENV_API_ORIGIN. It reads channel detail with that channel token, checks the code matches, and requires an OWNER or DELEGATEE role decoded from the account token. This local role check does not verify signatures or replace the service's authorization. API origins and credentials are operator configuration, not tool inputs.
Hosted use belongs to the selected-channel resource and must use its exact bound code. Account resources do not expose this tool.
Inputs
This tool takes no input fields.
Result
A successful application result contains:
| Field | Meaning |
|---|---|
status, code |
success, DESIGN_THEME. |
environment, channel |
Adapter label and selected channel (id, channelCode, title, baseCurrency, optional currentPlan). |
initialized |
Whether stored theme settings exist. |
revision |
Lowercase 64-character hexadecimal fingerprint of the whole tone/palette state, including absence. |
tone |
Stored DARK or LIGHT; DARK when uninitialized. |
brandColor, onBrandColor |
Stored custom values; empty strings when unset or uninitialized. |
effectiveBrandColor |
Custom brand color, otherwise #586CFF for DARK or #455EEF for LIGHT. |
effectiveOnBrandColor |
Custom on-brand color, otherwise #FFFFFF. |
verification |
confirmed:true, method:theme_read; a stored-data read, not visitor rendering verification. |
consoleUrl |
Non-demo theme management link when supplied by the server. |
An uninitialized theme returns initialized:false, the absence revision, and calculated default display colors. It is a valid result. Do not infer a stored write from those calculated values. The result does not expose the entire palette, but revisions cover all its keys; a change to another palette entry can invalidate a planned update.
Revision calculation sorts palette keys, normalizes case, and expands three-digit hex colors. Equivalent hex notation need not change the revision. Copy the returned revision to design_theme_apply.expectedRevision; do not compute or invent it. The target code comes from channel.channelCode.
HTTP behavior and failures
After the general-origin channel detail read, the adapter uses the separate CHANNEL_ENV origin for GET /seller/api/v1/channel-management/custom, with the selected channel bearer and x-publ-channel-id. The returned custom.channel_id must match and custom.experimentals must satisfy the theme contract.
Only a 404 from that theme GET is interpreted as uninitialized. A failed channel-detail read, 401/403/500 response, malformed theme, or wrong channel ID must not be treated as missing settings or permission to initialize them.
| Code | Meaning and next action |
|---|---|
AUTH_REQUIRED, CHANNEL_CREDENTIAL_MISSING |
A person must restore the correct environment/target connection without sending secrets through conversation. |
CHANNEL_CONTEXT_MISMATCH, DESIGN_RESPONSE_UNVERIFIED |
Target identity or response shape is not verified; stop before preparing a write. |
DESIGN_ROLE_DENIED |
The account role does not meet the implemented OWNER/DELEGATEE condition. |
DESIGN_ORIGIN_REQUIRED |
The operator must configure the verified CHANNEL_ENV origin. |
CONNECTION_BUSY, CONNECTION_CHANGED |
Another operation holds the connection or its identity changed. Preserve original task bindings. |
PERMISSION_DENIED, UPSTREAM_* |
Resolve the reported service/transport failure before reading again. |
This read makes no initialization/update, credential refresh, or job. It can be repeated after the underlying problem is resolved. Failure payloads need not include task or channel metadata.