API quickstart

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

Existing brand
Create a brand

List your brands and copy any id:

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.

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

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 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.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 for retries.

4. Request a Brief

Describe what you want to make:

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:

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

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.

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:

{
  "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:

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 defines the complete request and response contracts.

Getting started

Guides

Use cases

MCP

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