> ## Documentation Index
> Fetch the complete documentation index at: https://www.trybloom.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Make your first call to Bloom in four 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 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 in four short steps: authenticate, list your brands, start a generation, 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. Treat it as a secret — never commit it or expose it client-side.

```bash theme={null}
export BLOOM_API_KEY=bloom_sk_...
```

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

<Tabs>
  <Tab title="Brand already in Bloom">
    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 one. Its `id` is the `brandSessionId` you'll use next.
  </Tab>

  <Tab title="Onboard your brand">
    Onboard a brand from a website or Instagram URL. Bloom pulls in the brand identity and starts visual DNA analysis in the background:

    ```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 '{ "url": "https://acme.com" }'
    ```

    The response returns the new brand's `id` immediately. Use it as `brandSessionId` in the next step — you can start generating right away; visual DNA analysis runs in parallel.
  </Tab>
</Tabs>

## 3. Start a generation

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

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

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

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

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.