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, and typography. Both follow the same lifecycle: prepare a candidate, inspect or refine it, then Apply or Discard. Creating an edit does not change the active Brand. Apply 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 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, palette, or Heading and Body fonts.

An exact profile request preserves the requested structured values, but the Agent may also update related Markdown. For example, a palette change can update the visual guidance that describes how those colors are used. 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, create a Brand font asset and reference its font asset ID and family. Typography roles can be removed with null.

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.trybloom.ai/api/v1/brands/$BRAND_ID/edits" \
  -H "x-api-key: $BLOOM_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" }]
  }
}

Creation returns 202 Accepted with the edit resource in data. Keep its id and poll Get a Brand edit while its status is preparing.

Ask your connected client to make the change:

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

The client uses bloom_create_brand_edit with an instruction or profile change, then bloom_get_brand_edit to follow preparation. The connected server’s tools/list defines the exact fields.

Handle a request for input

Preparation may pause at input_required. The returned interaction describes a clarification or a choice, including the input it accepts. 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. Then resume polling the edit. 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 bloom_continue_brand_edit with the returned edit and interaction IDs.

Inspect and apply

When status reaches awaiting_approval, the candidate is ready. The response includes:

a summary and the proposed profile;
structured profile changes;
Markdown diff hunks, with a truncated flag for each file; and
asset changes.

These let a client review the candidate at the level appropriate for the task and the authority delegated to it. For complete Markdown, Get a changed Brand file or bloom_get_brand_edit_file returns the base and candidate snapshots in pages. Follow the returned cursor to read the remaining content. Call Apply a Brand Edit or bloom_apply_brand_edit to activate the candidate. Call Discard a Brand Edit or bloom_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 Skill and prepare a new edit from it.

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 Bloom discard the old candidate and make the new one available for Apply. A failed refinement does not lose the previous candidate.

Follow the result

Status	Meaning
`preparing`	Preparation is running; poll the edit.
`input_required`	Answer or decline the current interaction.
`awaiting_approval`	A candidate is available to inspect, refine, Apply, or Discard.
`applied`	The candidate was activated.
`discarded`	The edit ended without activation, either explicitly or through replacement.
`stale`	The Brand changed and this candidate can no longer be applied.
`no_changes`	Preparation finished without a change to propose.
`failed`	Preparation failed; inspect the returned error.

See the API reference for exact schemas and errors, or live MCP tools/list for tool contracts. After Apply, retrieve the active Brand Skill to use the updated context outside Bloom.

Getting started

Guides

Use cases

MCP

Edit a brand

Choose the change

Prepare a candidate

Handle a request for input

Inspect and apply

Refine a candidate

Follow the result

​Choose the change

​Prepare a candidate

​Handle a request for input

​Inspect and apply

​Refine a candidate

​Follow the result

Choose the change

Prepare a candidate

Handle a request for input

Inspect and apply

Refine a candidate

Follow the result