Getting Started

Bloom is the brand layer. Give it a brand and every image comes back on-brand: on-palette, on-tone, on-aesthetic. The API exposes the same engine for integrations, automations, and platforms. 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. Treat it as a secret — never commit it or expose it client-side.

export BLOOM_API_KEY=bloom_sk_...

App integrations can use Bloom OAuth instead and call the API with Authorization: Bearer <access_token>. See 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 a new one from a URL.

Brand already in Bloom
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.

Onboard a brand from a website or Instagram URL. Bloom pulls in the brand identity and starts visual DNA analysis in the background:

curl -X POST https://www.trybloom.ai/api/v1/brands \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://acme.com" }'

Bloom returns 202 Accepted after the initialization workflow is durably queued:

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

The website crawl and visual DNA analysis run in the background. Continue to step 3 before generating.Set collectImages to false if you don’t want Bloom to populate the brand’s background image library. This does not skip crawling, brand initialization, or visual DNA analysis.

3. Wait for the brand

Pass wait=true to hold the connection until the brand reaches ready, logo_required, or failed:

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

A timeout returns the current resource with status: "analyzing"; you can call the endpoint again. Only start generation after the status is ready.

logo_required means Bloom needs a replacement logo before visual DNA can finish.
failed includes a non-null failure object with a stable code and a message safe to show to the user.
While the brand is analyzing, fields such as logoUrl and summary may be null.

Failure codes are INVALID_URL, SCRAPE_FAILED, INSTAGRAM_FETCH_FAILED, INTERNAL_ERROR, and VISUAL_DNA_FAILED. Branch on the code and display the accompanying message; submit a new POST /brands to retry a failed initialization.

4. Start a generation

Generations are asynchronous. Bloom queues the job and returns 202 immediately with the image ID.

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

Hit GET /images/{id} to check status. Pass wait=true to hold the connection open until the generation reaches a terminal state — no polling loop needed:

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. 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://storage.trybloom.ai/..."
  }
}

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.

Bloom API

Guides

API Reference

Getting Started

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