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

# API quickstart

> Make your first generation through the API in six steps.

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

Make your first generation through Rainbrand'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](https://www.rainbrand.com/account?tab=api-keys) and generate an API key. Store it as `RAINBRAND_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 Rainbrand 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

Pick an existing brand with an active Brand Skill, or create one from your sources. The Brief in step 4 needs that Skill. Its Brand ID is the `brandSessionId` used in the requests below.

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

    ```bash theme={"dark"}
    curl https://www.rainbrand.com/api/v1/brands \
      -H "x-api-key: $RAINBRAND_API_KEY"
    ```

    Pick a brand whose `status` is `ready` and whose `activeSkill` is not `null`. The list doesn't include `activeSkill`, so read it with `GET /brands/{id}`. If none of your brands has one, create a brand instead. Its `id` is the `brandSessionId` you'll use next. If the brand is still `analyzing`, continue to step 3.
  </Tab>

  <Tab title="Create a brand">
    This example combines a website and brand guide, then requests imagery guidance:

    ```bash theme={"dark"}
    curl -X POST https://www.rainbrand.com/api/v1/brands \
      -H "x-api-key: $RAINBRAND_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](/guides/create-brand) to choose sources and recover from a failed attempt.
  </Tab>
</Tabs>

## 3. Wait for the brand

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

```bash theme={"dark"}
curl "https://www.rainbrand.com/api/v1/brands/<brand_id>?wait=true" \
  -H "x-api-key: $RAINBRAND_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](/guides/create-brand#handle-failures) for retries.

## 4. Request a Brief

Describe what you want to make:

```bash theme={"dark"}
curl -X POST https://www.rainbrand.com/api/v1/briefs \
  -H "x-api-key: $RAINBRAND_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:

```bash theme={"dark"}
curl "https://www.rainbrand.com/api/v1/briefs/<brief_id>?wait=true" \
  -H "x-api-key: $RAINBRAND_API_KEY"
```

Wait for the Brief to complete and inspect its guidance and assets. For a
supported image model, pass the completed Brief’s ID as `briefId` in the
generation request. The Brief must belong to you and the same Brand as
`brandSessionId`.

See [Request a Brief](/guides/request-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-2.5-flare`:

```bash theme={"dark"}
curl "https://www.rainbrand.com/api/v1/models?type=image" \
  -H "x-api-key: $RAINBRAND_API_KEY"

curl https://www.rainbrand.com/api/v1/models/openai/gpt-image-2.5-flare \
  -H "x-api-key: $RAINBRAND_API_KEY"
```

Build `input` according to the returned `inputSchema`. Write your concrete task
in `input.prompt` and set the model’s controls. Rainbrand places the complete Brief
guidance before your prompt and attaches compatible visual assets after your
references; your prompt and controls remain authoritative. Without `briefId`,
include the relevant brand guidance and references in the model input yourself.

Generations run asynchronously and can return multiple outputs. The initial response contains a generation ID.

```bash theme={"dark"}
curl -X POST https://www.rainbrand.com/api/v1/generations \
  -H "x-api-key: $RAINBRAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandSessionId": "<id from step 2>",
    "briefId": "<id from step 4>",
    "model": "openai/gpt-image-2.5-flare",
    "input": {
      "prompt": "Create a launch image with the product centered and the exact headline \"Introducing Atlas\"."
    }
  }'
```

Save `data.id` to retrieve the result:

```json theme={"dark"}
{
  "data": {
    "id": "a1b2c3d4-140f-4491-8a24-b215616ed34a",
    "status": "pending"
  }
}
```

To retry safely when a response is lost, send an optional `Idempotency-Key` header. Resending the same body with the same key returns the original generation instead of starting another; use a new key for a new generation.

## 6. Retrieve the result

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

```bash theme={"dark"}
curl "https://www.rainbrand.com/api/v1/generations/<generation_id>?wait=true" \
  -H "x-api-key: $RAINBRAND_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`: `message` summarizes the failure, and `providerMessage`, when present, gives the provider's own reason, such as an input value it rejected. Start a new attempt with the same request only when `retryable` is `true`, using a new `Idempotency-Key` if you sent one.

The [API reference](/api/openapi) defines the complete request and response contracts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.