Change a channel's theme

Use one read and one apply workflow to change tone and primary colors. Examples are illustrative inputs and must use current read results.

Read the intended channel

Select a known channel code through the directory guide or the bound hosted resource, then call design_theme_get:

{"channelCode":"selected-channel-code"}

The HTTP implementation needs the selected channel's credential, an OWNER/DELEGATEE account role, and the operator-configured CHANNEL_ENV origin. Hosted theme tools belong to the selected-channel resource. Do not supply credentials or guessed API origins as business inputs.

Inspect initialized, tone, custom/effective colors, and revision. Missing settings return calculated DARK defaults without creating anything. The revision covers the complete palette, including keys not shown by the get result.

Prepare the requested change

Pass get's channel.channelCode and revision into design_theme_apply. Include only intended changes. Omitted values are preserved; empty color strings reset overrides. Changing tone alone keeps custom colors.

{
  "requestId":"example-theme-reset-001",
  "channelCode":"selected-channel-code",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "tone":"LIGHT",
  "brandColor":"",
  "onBrandColor":"",
  "dryRun":true
}

This example requests LIGHT tone and both default colors. Replace the placeholder code/revision with the actual read values. For a custom color use #RGB or #RRGGBB. A connected server may still predate this correction: inspect its discovery schema and use lowercase hex digits for a new request if it advertises the older lowercase-only pattern. Preserve the exact inputs when resuming an existing request ID. At least one tone/color field is required.

A new dry run returns the requested change and whether initialization is required. When settings exist it includes planned patches; missing settings have no patch list until real initialization supplies defaults. No new job or task ID is saved by this dry run.

Apply and verify

Execute the same request ID and business inputs with dryRun:false when the plan matches the requested operation. The workflow initializes missing settings, writes tone if needed, then writes the full palette while preserving other keys. It reads after changes and checks the final full theme.

DESIGN_THEME_APPLIED with verification.confirmed:true means expected stored values were observed. Equivalent hex spellings can avoid a color step. changed:false can still follow initial settings creation; do not interpret that flag alone as zero writes.

The steps are not atomic. An earlier tone change can remain when a palette update fails. Revisions cannot prevent every competing write after the last check, and there is no automatic rollback.

Inspect and resume

Preserve the returned task identity. Call task_status with the actual original ID:

{"taskId":"example-theme-reset-001","taskType":"design-theme"}

If continuing the original operation is intended, pass the same pair to task_resume. A definite rejection/not-sent step can resume after its cause is resolved. An uncertain initialization or update is observed first and is not resent if the result remains unknown. Inspect the original task before considering any new plan; never change the ID to force a retry.

Completed results are historical. Apply/resume can check channel context while returning an old theme result, so use get for current theme values. An observed matching state does not prove which actor created or changed it.

Reference index · Theme get · Theme apply · Common results

Saved plan replay

An existing matching task's dryRun returns historical saved plan/progress, historical:true, replayed:true and false current verification. It has no current console/action link and does not read present business state, repeat effects or change the journal. Saved phase/progress and existingPhase aliases remain where applicable. Follow nextStep for a current observation; retain the original task ID for uncertain-outcome recovery. A new task keeps normal fresh-plan validation.

nextStep: design_theme_get retains the original channel; saved tone/palette steps are not a fresh theme read.

Saved record identity

For this workflow, existing apply/dry-run calls and task status/resume require both the saved task ID and saved input requestId to match the requested ID. A mismatching or malformed saved identity returns TASK_STATE_UNVERIFIED before workflow context or business-state reads. Preserve the original record for inspection; do not rename/edit it, try its embedded ID or create a replacement request to bypass the error. No stored record is repaired or resent. Valid matching records retain the recovery behavior described above.

Saved step consistency

Existing theme tasks must retain the original input fingerprint, derived ordered patches, preserved palette values, progress and expected final state. Inconsistent records return TASK_STATE_UNVERIFIED before context/business calls and remain unchanged. Generic missing/invalid completion still uses TASK_COMPLETION_UNVERIFIED. Historical success is not a fresh theme observation.