Edit a brand

A Brand Edit prepares a candidate version of your Brand Skill. Use natural-language instructions to change brand guidance, or provide exact profile values for the name, logo, colors, gradients, and typography. Both follow the same lifecycle: prepare a candidate, inspect or refine it, then apply or discard it. Creating an edit does not change the active brand. Applying it activates the candidate; subsequent Brand Skill reads and image generations use that version. The Brand ID stays the same. Start with a ready brand that has an active Brand Skill. See Create a brand if you need one, and API authentication or the MCP quickstart to connect.

Choose the change

Change type	Use it for
`instruction`	Natural-language changes, such as making the voice more direct or updating guidance from new evidence.
`profile`	Exact values for the name, primary logo, colors, gradients, or typography roles.

An exact profile request preserves the requested structured values, but Rainbrand may also update related Markdown. For example, a palette change can update the visual guidance that describes how those colors are used. When changing the palette, send the complete color list in the desired order. For a matching HEX value, omitted names, groups, and usage keep their current values; send null to remove one of those fields. A gradient change replaces the complete gradient list. Omit gradients to keep them, or send an empty list to remove them all. Either type can include supporting evidence: a website, Instagram account, files, or images already in the Brand Library. Stage local files before submitting them. For a primary logo, first save the image to the Brand Library and reference its image ID. For a custom font, follow the font upload flow and reference the returned font asset ID and family. For exact profile fields and evidence limits, read the Create a Brand Edit reference or the connected server’s live MCP schema.

Prepare a candidate

Read the active Brand Skill and use its skillId as baseSkillId. Then call Create a Brand Edit:

curl -X POST "https://www.rainbrand.com/api/v1/brands/$BRAND_ID/edits" \
  -H "x-api-key: $RAINBRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $EDIT_REQUEST_KEY" \
  -d '{
    "baseSkillId": "<active_skill_id>",
    "change": {
      "kind": "instruction",
      "instruction": "Make our voice more direct. Keep the existing positioning and visual identity."
    }
  }'

Set EDIT_REQUEST_KEY to a unique value for this operation. Reuse it with the same body when retrying the request; use a new key for a different operation.For an exact profile edit, replace change with a profile request, such as:

{
  "kind": "profile",
  "changes": {
    "colors": [{ "hex": "#245C45" }, { "hex": "#F8F5EE" }]
  }
}

Keep the returned edit id. While its status is preparing, call Get a Brand Edit with wait=true. If it is still preparing, follow the response’s retry guidance and repeat the read with the same ID.

Ask your connected client to make the change:

Prepare an edit to our brand in Rainbrand that makes our voice more
direct, while keeping the existing positioning and visual identity.

The client uses create_brand_edit with an instruction or profile change. If the result is still preparing, call get_brand_edit with the same edit_id and wait: true. Repeat that read as needed; do not create another edit to check progress. The connected server’s tools/list defines the exact fields.

Preparation can produce a candidate or pause for input. A wait may end while preparation continues; keep using the same edit ID to follow its progress.

Handle a request for input

At input_required, read the clarification or choice and answer in the format it requests. Answering continues preparation; it does not apply the edit. API clients submit a typed response to Continue a Brand Edit, using the current interaction ID and an Idempotency-Key. If the result is preparing, read the edit again with wait=true. Use the returned option IDs for a selection, or provide an answer in the accepted format. A client can also decline the interaction. MCP clients that support native input can handle the exchange within the request. Other clients use continue_brand_edit with the returned edit and interaction IDs. If preparation continues, follow with get_brand_edit and wait: true.

Inspect the candidate

When status reaches awaiting_approval, inspect the proposed profile, guidance, and asset changes. For complete Markdown, read a changed file with the API or get_brand_edit_file in MCP. Follow the returned cursor to read the remaining content.

Refine a candidate

To revise a candidate awaiting approval, create another edit with replacesEditId in the API or replaces_edit_id in MCP. Describe the refinement in the new request. The existing candidate stays available while its replacement is being prepared or waiting for input. Only when the replacement reaches awaiting_approval does Rainbrand discard the old candidate and make the new one available to apply. A failed refinement does not lose the previous candidate.

Apply or discard

Call Apply a Brand Edit or apply_brand_edit to make the candidate the active Brand Skill. Call Discard a Brand Edit or discard_brand_edit to end the edit without changing the active brand. If the active brand changes after the edit was based on it, the candidate cannot overwrite that newer version. Read the current Brand Skill and prepare a new edit from it. After applying an edit, retrieve the active Brand Skill to use the updated context outside Rainbrand. If preparation fails, read the returned error before trying again. The Brand Edit reference and live MCP tools/list define the exact fields, statuses, and errors.

Getting started

Guides

Use cases

MCP

Choose the change

Prepare a candidate

Handle a request for input

Inspect the candidate

Refine a candidate

Apply or discard

​Choose the change

​Prepare a candidate

​Handle a request for input

​Inspect the candidate

​Refine a candidate

​Apply or discard

Choose the change

Prepare a candidate

Handle a request for input

Inspect the candidate

Refine a candidate

Apply or discard