> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybloom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit a brand

> Prepare, inspect, refine, and apply changes to a Brand through the API or MCP.

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](/guides/create-brand) if you need one, and [API authentication](/api/authentication) or the [MCP quickstart](/mcp/getting-started) 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](/guides/upload-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

<Tabs>
  <Tab title="API">
    Read the [active Brand Skill](/guides/use-brand-skill) and use its `skillId` as `baseSkillId`. Then call [Create a Brand Edit](/api-reference/brands/create-a-brand-edit):

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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](/api-reference/brands/get-a-brand-edit) while its status is `preparing`.
  </Tab>

  <Tab title="MCP">
    Ask your connected client to make the change:

    ```text theme={null}
    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.
  </Tab>
</Tabs>

## 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](/api-reference/brands/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](/api-reference/brands/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](/api-reference/brands/apply-a-brand-edit) or `bloom_apply_brand_edit` to activate the candidate. Call [Discard a Brand Edit](/api-reference/brands/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](/api/openapi) for exact schemas and errors, or live MCP `tools/list` for tool contracts. After Apply, [retrieve the active Brand Skill](/guides/use-brand-skill) to use the updated context outside Bloom.