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

> Add a brand and retrieve guidance for a task through the REST API.

![Rainbrand API](https://mintcdn.com/bloom-100885a1/lUdiOQm7tmmPkns8/images/api-hero.png?fit=max\&auto=format\&n=lUdiOQm7tmmPkns8\&q=85\&s=d8061a75f8b975d2a0f52ec24945e1d8)

This example adds Acme Inc. from its website, then requests brand guidance and assets for an Atlas Pro launch image.

Use an [API key](https://docs.rainbrand.com/api/authentication.md#api-keys) stored as `RAINBRAND_API_KEY` in your environment. All requests use `https://www.rainbrand.com/api/v1`.

## 1. Add a brand

```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" }]
  }'
```

Replace the website with your own. [Create a brand](https://docs.rainbrand.com/api-reference/brands/create-a-brand.md) lists the supported source formats.

The response identifies the new brand:

```json theme={"dark"}
{
  "data": {
    "id": "e6220a5e-4a68-4d39-8bb9-5105e9a3a164",
    "status": "analyzing"
  }
}
```

Use your returned `data.id` in place of the example Brand ID below. If you already have a brand, find its ID with [List brands](https://docs.rainbrand.com/api-reference/brands/list-brands.md) and continue here.

## 2. Wait until the brand is ready

```bash theme={"dark"}
curl "https://www.rainbrand.com/api/v1/brands/e6220a5e-4a68-4d39-8bb9-5105e9a3a164?wait=true" \
  -H "x-api-key: $RAINBRAND_API_KEY"
```

If `data.status` is still `analyzing`, repeat the read. Continue when it is `ready` and `data.activeSkill` is present.

If the status is `failed`, read `data.failure` for the cause before trying again. If an existing brand returns `logo_required`, complete its logo selection in Rainbrand before continuing.

## 3. Request a Brief

```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": "e6220a5e-4a68-4d39-8bb9-5105e9a3a164",
    "task": "A landscape launch image for Acme Inc. Atlas Pro. Center the product and include the headline \"Meet Atlas Pro\" and the call to action \"Explore Atlas Pro\"."
  }'
```

The response contains the Brief's ID. Use your returned `data.id` in the next request.

## 4. Retrieve the guidance and assets

```bash theme={"dark"}
curl "https://www.rainbrand.com/api/v1/briefs/657bcf79-1f2f-47fa-90f8-9245142980ed?wait=true" \
  -H "x-api-key: $RAINBRAND_API_KEY"
```

Repeat the read while `data.status` is `pending` or `processing`. When it is `completed`, `data.guidance` contains the task's brand guidance and `data.assets` contains the selected files. A failed Brief includes `data.error` with the reason and whether a new attempt may succeed.

## Use the Brief

Use the completed Brief with your own agents, models, or renderer. To generate through the AI Gateway, [get a model](https://docs.rainbrand.com/api-reference/models/get-a-model.md) to check its input schema, then pass the Brief's ID as `briefId`:

> [card] [Start a generation](https://docs.rainbrand.com/api-reference/generations/start-a-generation.md)
>
> Send the model input with the completed Brief.


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