API quickstart

Bloom’s REST API lets products, backends, and automated workflows add brands and create on-brand images. A brand keeps one stable identity while Bloom turns its source evidence into structured guidance. See How Bloom works for the relationship between brands, Brand Skills, the API, and MCP. This page walks through the first end-to-end call: authenticate, select or create a brand, wait for it to be ready, start a generation, and pick up the result.

1. Authenticate

For server-side automations, open your account settings and generate an API key. Store it as BLOOM_API_KEY in your environment or secret manager before running the examples below. Treat it as a secret — never commit it or expose it client-side. App integrations can use Bloom OAuth instead and call the API with Authorization: Bearer <access_token>. See API authentication for the OAuth endpoints and PKCE requirements.

2. Get a Brand ID

Image generations are scoped to a brand. You need a brandSessionId — either pick an existing brand or create one from source evidence.

Existing brand
Onboard your brand

List your brands and copy any id:

curl https://www.trybloom.ai/api/v1/brands \
  -H "x-api-key: $BLOOM_API_KEY"

Pick a brand whose status is ready. Its id is the brandSessionId you’ll use next. If the brand is still analyzing, continue to step 3.

Send an ordered sources array. This example combines a website and brand guide, then asks the Brand Agent for imagery guidance needed by the integration:

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."
  }'

File URLs must use HTTPS and remain reachable while the request runs. instructions is optional, accepts up to 4,000 characters, and is not a strict output guarantee.Bloom returns 202 Accepted after the workflow is durably queued:

{
  "data": {
    "id": "f7e319aa-...",
    "status": "analyzing"
  }
}

id is the stable Brand ID used by the rest of the API. Brand analysis runs in the background; poll this same id in step 3 before generating.See Create a brand for supported sources, explicit-logo handling, failures, and compatibility inputs.

3. Wait for the brand

Pass wait=true to wait for the current brand analysis:

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

Each call waits for a bounded period. If the response still has status: "analyzing", call the same endpoint again with the same Brand ID. Continue only when the brand is ready. If the brand is failed, show failure.message, correct the input, and submit a new creation request. logo_required applies only to older brands and the explicit-logo compatibility workflow. See Create a brand for the complete lifecycle and recovery guidance.

4. Start a generation

Generations are asynchronous. Bloom queues the job and returns 202 immediately with one or more image IDs.

curl -X POST https://www.trybloom.ai/api/v1/images/generations \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandSessionId": "<id from step 2>",
    "prompt": "Hero image for a spring product launch."
  }'

The response includes the image ID(s) you’ll poll next. If the brand is not ready, generation returns BRAND_NOT_READY with HTTP 409. Inspect or wait on GET /brands/{id} before retrying.

5. Retrieve the image

Call GET /images/{id} to check the status. Pass wait=true to hold the connection open while the generation runs:

curl "https://www.trybloom.ai/api/v1/images/<image_id>?wait=true" \
  -H "x-api-key: $BLOOM_API_KEY"

A successful response includes the URL of the finished image. If a bounded wait returns pending or generating, call the same endpoint again. For batch flows, the list endpoint accepts ids=...&wait=true to collect many images in one call.

Response format

Successful responses are wrapped in a data envelope:

{
  "data": {
    "id": "a1b2c3d4-...",
    "status": "completed",
    "imageUrl": "https://www.trybloom.ai/img/a1b2c3d4-..."
  }
}

Each endpoint’s exact data shape is documented in the API reference.

Error format

Failed responses use a consistent envelope:

{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "status": 404,
    "message": "Brand not found"
  }
}

Branch retries on code; treat message as human-readable only. Continue with Generate images, or open the API reference for the complete public contract.

Getting started

Guides

MCP

API quickstart

1. Authenticate

2. Get a Brand ID

3. Wait for the brand

4. Start a generation

5. Retrieve the image

Response format

Error format

​1. Authenticate

​2. Get a Brand ID

​3. Wait for the brand

​4. Start a generation

​5. Retrieve the image

​Response format

​Error format

1. Authenticate

2. Get a Brand ID

3. Wait for the brand

4. Start a generation

5. Retrieve the image

Response format

Error format