Create a Brand

Create a Brand once, wait for its source evidence to become an active Brand Skill, then use the stable Brand ID for later work. Use the API for application or server code. Use MCP when an interactive agent is operating Bloom.

Choose the source evidence

A source-based request accepts up to 30 entries, with at most one website and one Instagram account. Files can supply Brand guides, briefs, logos, covers, and other useful evidence.

Website sources use { "kind": "website", "url": "https://..." }.
Instagram sources use { "kind": "instagram", "username": "acme" }.
File sources use { "kind": "file", "url": "https://...", "filename": "..." }.

File URLs must use HTTPS and remain publicly reachable while the request runs. Bloom copies the bytes into private storage before the Brand Agent begins. filename labels a source; it does not tell Bloom what role the file should play. Bloom determines the Brand name from the evidence. Pass workspaceId in the API or workspace_id in MCP when the Brand should belong to a team workspace; otherwise creation defaults to the caller’s personal workspace.

Tell the Brand Agent what matters

instructions is optional, accepts up to 4,000 characters, and applies only to this Brand Agent run. Use it to:

identify the role or authority of a supplied file;
emphasize evidence important to the application; or
request additional guidance that the resulting Brand Skill should cover.

The Brand Agent applies the request using its existing judgment. instructions is not a strict output guarantee.

Start creation

Send the ordered source set to POST /brands:

curl -X POST https://www.trybloom.ai/api/v1/brands \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      { "kind": "website", "url": "https://acme.com" },
      {
        "kind": "file",
        "url": "https://uploads.acme.com/temporary-brand-guide.pdf",
        "filename": "brand-guide.pdf"
      }
    ],
    "instructions": "Create an imagery.md file that explains how image-heavy this brand is and what imagery it uses."
  }'

Bloom returns 202 Accepted after the work is queued:

{
  "data": {
    "id": "f7e319aa-2a7f-4f2a-853a-eb5a5798659e",
    "status": "analyzing"
  }
}

Once Bloom MCP is connected, ask the agent to create the Brand from the same evidence:

Create a Bloom Brand from acme.com and the Brand guide at
https://uploads.acme.com/temporary-brand-guide.pdf. Ask the Brand Agent to
create an imagery.md file explaining how image-heavy the Brand is and what
imagery it uses.

An integration calling bloom_onboard_brand directly can pass:

{
  "sources": [
    { "kind": "website", "url": "https://acme.com" },
    {
      "kind": "file",
      "url": "https://uploads.acme.com/temporary-brand-guide.pdf",
      "filename": "brand-guide.pdf"
    }
  ],
  "instructions": "Create an imagery.md file that explains how image-heavy this brand is and what imagery it uses."
}

Both interfaces return the stable Brand ID while processing continues. Keep that ID for status checks, Brand Skill retrieval, and image operations.

Wait until the Brand is ready

Call the Brand with wait=true:

curl "https://www.trybloom.ai/api/v1/brands/$BRAND_ID?wait=true" \
  -H "x-api-key: $BLOOM_API_KEY"

Call bloom_get_brand with the returned ID and wait: true.

Each call waits for a bounded period. If either interface returns status: "analyzing", repeat the same request with the same Brand ID. Generate only after the Brand becomes ready.

Supply a specific logo

Include the approved logo as a file source and name its role explicitly:

{
  "sources": [
    { "kind": "website", "url": "https://acme.com" },
    {
      "kind": "file",
      "url": "https://uploads.acme.com/brand-logo.png",
      "filename": "brand-logo.png"
    }
  ],
  "instructions": "The attached image is the approved primary logo."
}

When several logos are supplied, identify each one as primary, alternate, deprecated, tentative, or reference-only. Prefer PNG or WebP when a supplied file should become the profile’s primary logo. After the Brand is ready, GET /brands/{id} returns the selected logo in profile.primaryLogo. The complete active Skill provides its exact asset identity.

Handle failures

If Bloom rejects the creation request, correct the source or instructions before retrying. Common API validation codes include INVALID_URL, UNSUPPORTED_SOURCE, and INVALID_SOURCE; MCP returns the corresponding validation failure through the tool result. After creation is queued, a failed Brand includes a stable failure code and a human-readable message. Show the message, correct the input, and submit a new creation request.

Compatibility inputs

The API and MCP retain a single website or Instagram url input for existing integrations. A plain url creates a Brand Skill through the same source-first pipeline. New integrations should use sources so they can combine evidence and provide instructions. Adding logoUrl to an API request, or logo_url to an MCP request, switches the request to the older explicit-logo onboarding workflow. That compatibility path can return logo_required; supply a replacement logo and wait for the Brand again before generating.

Next steps

Retrieve and use the active Brand Skill
Generate images with the Brand
Inspect the exact POST /brands contract

Getting started

Guides

MCP

Create a Brand

Choose the source evidence

Tell the Brand Agent what matters

Start creation

Wait until the Brand is ready

Supply a specific logo

Handle failures

Compatibility inputs

Next steps

​Choose the source evidence

​Tell the Brand Agent what matters

​Start creation

​Wait until the Brand is ready

​Supply a specific logo

​Handle failures

​Compatibility inputs

​Next steps

Choose the source evidence

Tell the Brand Agent what matters

Start creation

Wait until the Brand is ready

Supply a specific logo

Handle failures

Compatibility inputs

Next steps