# Create a brand kit

> Create a brand kit from your colours and your looks, fabrics, prints and other images. The kit is ready to read at once; its items are prepared so generation can use them.

**Endpoint:** `POST https://api.refabric.com/v1/tasks/brand_kit.create` · **Task:** `brand_kit.create` · **Scope:** `tasks:run` · **Category:** Records & libraries

Send your palette and your images — looks, fabrics, prints and other details — and get a brand kit back at once. Its items are then prepared, so a generation that takes the kit can use your colours and your items.

## Quick start

```python
import os
import time
import requests

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

job = requests.post(
    "https://api.refabric.com/v1/tasks/brand_kit.create",
    headers=headers,
    json={
        "name": "SS27 core",
        "items": [
            {
                "type": "look",
                "url": "https://files.example.com/brand_kit.create/1.jpg",
            },
        ],
    },
).json()
print(job["job_id"])

while True:
    status = requests.get(job["status_url"], headers=headers).json()
    if status["lifecycle"] == "terminal":
        break
    time.sleep(5)

print(requests.get(job["result_url"], headers=headers).json())
```

```javascript
const headers = {
  Authorization: `Key ${process.env.REFABRIC_API_KEY}`,
  "Content-Type": "application/json",
};

const job = await fetch("https://api.refabric.com/v1/tasks/brand_kit.create", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "name": "SS27 core",
    "items": [
      {
        "type": "look",
        "url": "https://files.example.com/brand_kit.create/1.jpg"
      }
    ]
  }),
}).then((r) => r.json());
console.log(job.job_id);

let status = job;
while (status.lifecycle !== "terminal") {
  await new Promise((r) => setTimeout(r, 5000));
  status = await fetch(job.status_url, { headers }).then((r) => r.json());
}

console.log(await fetch(job.result_url, { headers }).then((r) => r.json()));
```

```bash
curl -X POST "https://api.refabric.com/v1/tasks/brand_kit.create" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"name":"SS27 core","items":[{"type":"look","url":"https://files.example.com/brand_kit.create/1.jpg"}]}'
```

## Input schema

- `name` (string, _required_, min length 1, max length 200) — The kit's name, 1–200 characters. Required.
  Example: `SS27 core`
- `items` (array<object>, _optional_, at most 240 items) — The kit's images, each {type, url, name} — up to 60 of each type. The kit's `data.items[]` shows each with its `status` until it is ready.
  Example: `[{"type":"look","url":"https://files.example.com/brand_kit.create/1.jpg"},{"type":"fabric","url":"https://files.example.com/brand_kit.create/2.jpg","name":"12oz selvedge"},{"type":"print","url":"file:8812"},{"type":"other","url":"https://files.example.com/brand_kit.create/3.jpg","name":"copper rivet"}]`
  - `type` (string, _required_) — What the image shows. An image that is none of the other kinds — a trim, hardware or any other detail — is `other`. Required.
    Values: `fabric` (A fabric: its swatch or a photo of it. When the image is a fabric swatch or a photo of a fabric.); `print` (A print or pattern. When the image is a print or pattern.); `look` (A garment or outfit, as a photo or a design. When the image is a garment or an outfit.); `other` (Any other image the record holds. When the image is none of the other kinds.)
    Example: `look`
  - `url` (string, _required_, max length 2048, pattern: ^(https://|art:|file:).+$) — The item's image, as one string: a URL, an upload (`file:…`) or a file of yours (`art:…` or an `items[].url` of another record's `data`). Any public image URL is accepted — it does not have to be yours; a URL that is not public is refused (`image_not_public`). A URL already in the kit is not added twice (reported in `summary.warnings`, `item_duplicate`).
    Example: `https://files.example.com/brand_kit.create/1.jpg`
  - `name` (string, _optional_, max length 200) — Optional. Your own name for it (`12oz selvedge`); the kit shows it instead of a generated label.
    Example: `12oz selvedge`
- `colours` (array<object>, _optional_, at most 10 items) — The kit's palette, up to 10 colours, each {hex, name, pantone}. A design made with the kit uses these colours as its palette.
  Example: `[{"hex":"#1A2B3C","name":"ink","pantone":"19-4010 TCX"},{"hex":"#F4EFE6"}]`
  - `hex` (string, _required_, pattern: ^#[0-9A-Fa-f]{6}$) — The colour as #RRGGBB, like "#E8D9C4".
  - `name` (string, _optional_) — A name for the colour.
  - `pantone` (string, _optional_) — Its Pantone code, when known.

## Required-fields example

```json
{
  "name": "SS27 core",
  "items": [
    {
      "type": "look",
      "url": "https://files.example.com/brand_kit.create/1.jpg"
    }
  ]
}
```

## Full example

```json
{
  "name": "SS27 core",
  "colours": [
    {
      "hex": "#1A2B3C",
      "name": "ink",
      "pantone": "19-4010 TCX"
    },
    {
      "hex": "#F4EFE6"
    }
  ],
  "items": [
    {
      "type": "look",
      "url": "https://files.example.com/brand_kit.create/1.jpg"
    },
    {
      "type": "fabric",
      "url": "https://files.example.com/brand_kit.create/2.jpg",
      "name": "12oz selvedge"
    },
    {
      "type": "print",
      "url": "file:8812"
    },
    {
      "type": "other",
      "url": "https://files.example.com/brand_kit.create/3.jpg",
      "name": "copper rivet"
    }
  ]
}
```

## Output schema

- `files` (array<object>, _optional_) — Exactly one file: the kit, `brand_kit:<id>` — the same file `GET /v1/files/brand_kit:<id>` answers. Its `data.items[]` are the items with their `status`; pass the kit to a generation in `brand_kit`, and an item's `url` into any image field.
- `summary` (object, _optional_) — How many items were sent and are ready, and why any are not.
  - `requested` (integer, _optional_) — Items sent.
  - `delivered` (integer, _optional_) — Items ready to use.
  - `warnings` (array<object>, _optional_) — `{code, field, message}` rows: `output_not_produced` (`field: "items"`) when some items are not usable — they are in the kit with `status: failed` and the kit is still usable; `item_duplicate` (`field: "items"`) when some items were not added because their URL was already in the kit.

## Response example

```json
{
  "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
  "lifecycle": "queued",
  "status_url": "http://v3-api.refabric.com/v1/jobs/5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
  "result_url": "http://v3-api.refabric.com/v1/jobs/5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968/result",
  "cancel_url": "http://v3-api.refabric.com/v1/jobs/5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968/cancel"
}
```

## Result example

```json
{
  "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
  "files": [
    {
      "file": "brand_kit:28",
      "url": "https://files.example.com/brand_kit.create/1.jpg",
      "media_type": "application/json",
      "task": "brand_kit.create",
      "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
      "created_at": "2026-09-30T09:00:00Z",
      "data": {
        "name": "SS27 core",
        "status": "ready",
        "colours": [
          {
            "hex": "#1A2B3C",
            "name": "ink",
            "pantone": "19-4010 TCX"
          },
          {
            "hex": "#F4EFE6"
          }
        ],
        "items": [
          {
            "type": "fabric",
            "name": "12oz selvedge",
            "url": "https://files.example.com/brand_kit.create/2.jpg"
          },
          {
            "type": "print",
            "name": "paisley print",
            "url": "https://files.example.com/brand_kit.create/4.jpg"
          },
          {
            "type": "other",
            "name": "copper rivet",
            "url": "https://files.example.com/brand_kit.create/3.jpg"
          },
          {
            "type": "look",
            "name": "denim trucker jacket",
            "url": "https://files.example.com/brand_kit.create/1.jpg"
          }
        ]
      }
    }
  ],
  "has_more": false,
  "summary": {
    "requested": 4,
    "delivered": 4
  }
}
```

The kit is readable at GET /v1/files/brand_kit:<id> right away; its items show `status: processing` until they are ready.

## Built for

- A brand's palette and materials, ready for generation
- Your own fabrics and prints, kept in one place
- New designs in your brand's look

## What you get

- One `brand_kit:` record — its name, its colours and its items, each item with its `status` until it is ready.
- A `summary` that counts the items sent and the items ready, and says in `warnings` when some are not usable or were already in the kit.

## Specs

- **Input formats:** Images, each one string: a URL, an upload (`file:…`) or a file from an earlier result (`art:…`). Upload types and sizes: `GET /v1/meta` `limits.upload`.
- **Input count:** `items`: up to 240, each with its image
- **Output format:** One `brand_kit:` record: its `data` is JSON in the record vocabulary, its `url` a preview image.
- **Outputs per job:** One record file, however many items you send.

## Choosing a task

- Use this when you want your own colours and images kept as they are, for generation to use. Use `moodboard.create` when you want a direction read from images: what they share in colour, fabric, print and items.

## Errors

- `invalid_request`
- `invalid_option`
- `field_not_accepted`
- `name_required`
- `invalid_colour`
- `too_many_items`
- `too_many_colours`
- `kit_empty`
- `image_not_public`
- `not_found`
- `processing_failed`

## Related

- `image.generate` — It runs after: it takes this task's result.
- `range_plan.create` — It runs after: it takes this task's result.
- `moodboard.create` — It does a neighbouring job.

## Good to know

- `name` is at most 200 characters.
- `items` holds at most 240 items.
- `items[].url` is at most 2048 characters.
- `items[].name` is at most 200 characters.
- `colours` holds at most 10 items.

## For agents and code generation

- https://api.refabric.com/v1/tasks/brand_kit.create/llms.txt
- https://api.refabric.com/v1/tasks/brand_kit.create/openapi.json
- GET https://api.refabric.com/v1/tasks/brand_kit.create