> ## 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.

# API quickstart

> Make your first call to Bloom in five steps.

<img src="https://mintcdn.com/bloom-100885a1/18j4aak0YiRD3A4u/images/api-hero.png?fit=max&auto=format&n=18j4aak0YiRD3A4u&q=85&s=15652471e78223f7ef6609507bc187fd" alt="Bloom API" width="2400" height="1000" data-path="images/api-hero.png" />

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](/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](https://www.trybloom.ai/settings/api-keys) 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](/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.

<Tabs>
  <Tab title="Existing brand">
    List your brands and copy any `id`:

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

  <Tab title="Onboard your brand">
    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:

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

    ```json theme={null}
    {
      "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](/guides/create-brand) for supported sources, explicit-logo handling, failures, and compatibility inputs.
  </Tab>
</Tabs>

## 3. Wait for the brand

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

```bash theme={null}
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](/guides/create-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.

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

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

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

```json theme={null}
{
  "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](/guides/generate-images), or open the [API reference](/api/openapi) for the complete public contract.