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

# Quickstart

> Create, download, and use a Brand Skill.

This walkthrough creates one Brand Skill from a website, then downloads the
completed folder. Rainbrand schedules its retained copy for deletion automatically.

## Before you start

You need:

* a dedicated Rainbrand API key created from the approved account that will own
  the integration ([create one in Account](https://www.rainbrand.com/account?tab=api-keys));
* one or more public website or non-PDF file sources; and
* a server-side environment where the API key remains secret, with `curl` and
  `jq` installed.

```bash theme={null}
export RAINBRAND_API_KEY=bloom_sk_...
export IDEMPOTENCY_KEY=replace-with-a-unique-value
```

The idempotency key is optional but recommended. Use a new value for each Brand
Skill you intend to create, and reuse it only when retrying the same request
body.

## 1. Create the Brand Skill

This example creates a Brand Skill from a website:

```bash theme={null}
CREATE_RESPONSE="$(
  curl --silent --show-error --fail-with-body \
    --request POST "https://www.rainbrand.com/api/v1/brand-skills" \
    --header "x-api-key: $RAINBRAND_API_KEY" \
    --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "brandName": "Acme",
      "instructions": "Create an imagery.md file that explains how image-heavy this brand is and what imagery it uses.",
      "sources": [
        {
          "kind": "website",
          "url": "https://acme.com"
        }
      ]
    }'
)"

printf '%s\n' "$CREATE_RESPONSE" | jq
if BRAND_SKILL_ID="$(
  printf '%s' "$CREATE_RESPONSE" | jq --raw-output --exit-status '.data.id'
)"; then
  export BRAND_SKILL_ID
else
  unset BRAND_SKILL_ID
  printf '%s\n' "Create response did not contain data.id." >&2
fi
```

Rainbrand validates the website, queues the build, and returns `202 Accepted`:

```json theme={null}
{
  "data": {
    "id": "<brand-skill-id>",
    "brandId": "<brand-id>",
    "status": "pending"
  }
}
```

The response contains two IDs:

* `data.id` is the Brand Skill ID. The command saves it as `BRAND_SKILL_ID`;
  use it to check the build and delete the Brand Skill.
* `data.brandId` is the ID of the created Brand.

Save both values in your job record. The polling response also includes both IDs.

The [create reference](https://partners.rainbrand.com/api-reference/brand-skills/create-a-brand-skill.md) owns
the exact source schemas and limits.

> [!WARNING]
>
> The Brand Skills API does not accept PDFs. They are rejected from their
> verified contents, even when the URL or filename uses another extension.
> Rainbrand deletes the staged copy before returning `400 INVALID_SOURCE` and does
> not queue a Brand Skill. If cleanup fails after retries, the request returns
> an internal error instead. Other file types remain supported.

`instructions` is optional, applies only to this Brand Skill run, and may
contain up to 4,000 characters after surrounding whitespace is removed. Rainbrand
passes it to the Brand Agent as customer guidance for authoring the Skill. The
Agent decides how to apply it under its existing instructions, so do not treat
it as a strict output guarantee.

## 2. Check the build

```bash theme={null}
curl "https://www.rainbrand.com/api/v1/brand-skills/$BRAND_SKILL_ID" \
  --header "x-api-key: $RAINBRAND_API_KEY"
```

Repeat this request until `data.status` is `completed` or `failed`. Wait 10
seconds before the first check, then double the interval after each
non-terminal response up to 60 seconds. Add a small random delay when polling
several Brand Skills so their requests do not arrive together. If a check
returns `429 Too Many Requests`, wait for the number of seconds in the
`Retry-After` response header before checking again, or wait 60 seconds if the
header is absent.

When the build completes, `data.download` contains the temporary ZIP URL,
filename, and byte length. The [get reference](https://partners.rainbrand.com/api-reference/brand-skills/get-a-brand-skill.md)
contains the complete response schema.

## 3. Download and extract the Skill

Copy `data.download.url` from the completed response:

```bash theme={null}
export BRAND_SKILL_DOWNLOAD_URL="https://..."

curl --location "$BRAND_SKILL_DOWNLOAD_URL" --output brand-skill.zip
unzip brand-skill.zip -d brand-skill
```

Store the whole extracted folder and preserve its relative paths. Continue to
[Use the downloaded Skill](https://partners.rainbrand.com/using-the-skill.md) before wiring it into an agent.

## 4. Optional: remove API access immediately

Rainbrand removes the Brand Skill and its inputs and derived outputs within 30 days
of successful bundle delivery. You do not need to call `DELETE` to start this
clock.

After your system has stored the Skill, you may hide it from the API immediately:

```bash theme={null}
curl --request DELETE \
  "https://www.rainbrand.com/api/v1/brand-skills/$BRAND_SKILL_ID" \
  --header "x-api-key: $RAINBRAND_API_KEY"
```

Deletion makes the resource unavailable immediately without extending its
existing purge schedule. The create request's idempotency key becomes available
for a new Brand Skill as soon as deletion is requested.

> **[Build the production lifecycle](https://partners.rainbrand.com/integration-flow.md)**
>
> Add safe polling, failure handling, storage, and cleanup to your backend.


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