API quickstart

Make your first generation through Bloom’s REST API. Select a ready brand, request a Brief and then start a generation using its guidance. This example creates an image.

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

Pick an existing brand or create one from your sources. Its Brand ID is the brandSessionId used in the requests below.

Existing brand
Create a 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.

This example combines a website and brand guide, then requests imagery guidance:

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 publicly reachable while the request runs.Save data.id from the response as the Brand ID. Creation continues while you check progress in step 3.See Create a brand to choose sources and recover from a failed attempt.

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 and follow Handle failures for retries.

4. Request a Brief

Describe what you want to make:

curl -X POST https://www.trybloom.ai/api/v1/briefs \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandSessionId": "<id from step 2>",
    "task": "A hero image for our spring product launch, with room for a headline."
  }'

Use the returned data.id to retrieve the Brief:

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

Repeat the read while pending or processing. Once completed, use data.guidance and relevant data.assets to prepare the model input. The Brand ID scopes a generation; it does not add context automatically. See Request a Brief for details and failure handling.

5. Make your first generation

Find an image model, then read its input schema. This example uses openai/gpt-image-1.5:

curl "https://www.trybloom.ai/api/v1/models?type=image" \
  -H "x-api-key: $BLOOM_API_KEY"

curl https://www.trybloom.ai/api/v1/models/openai/gpt-image-1.5 \
  -H "x-api-key: $BLOOM_API_KEY"

Build input according to the returned inputSchema. Replace the example prompt below with your task and the Brief’s guidance; include relevant assets where the model supports them. Generations run asynchronously and can return multiple outputs. The initial response contains a generation ID.

curl -X POST https://www.trybloom.ai/api/v1/generations \
  -H "x-api-key: $BLOOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandSessionId": "<id from step 2>",
    "model": "openai/gpt-image-1.5",
    "input": {
      "prompt": "Hero image for a spring product launch. Use the brand palette of forest green and warm cream, soft natural light, and generous empty space."
    }
  }'

Save data.id to retrieve the result:

{
  "data": {
    "id": "a1b2c3d4-140f-4491-8a24-b215616ed34a",
    "status": "pending"
  }
}

6. Retrieve the result

Call GET /generations/{id} with wait=true to wait for the result:

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

When data.status is completed, each entry in data.outputs contains a file’s url and mimeType. If the status is still pending or generating, repeat the same read. If it is failed, read data.failure before retrying. The API reference defines the complete request and response contracts.

Getting started

Guides

Use cases

MCP

API quickstart

1. Authenticate

2. Get a Brand ID

3. Wait for the brand

4. Request a Brief

5. Make your first generation

6. Retrieve the result

​1. Authenticate

​2. Get a Brand ID

​3. Wait for the brand

​4. Request a Brief

​5. Make your first generation

​6. Retrieve the result

1. Authenticate

2. Get a Brand ID

3. Wait for the brand

4. Request a Brief

5. Make your first generation

6. Retrieve the result