Records & libraries

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.createTask: brand_kit.createScope: tasks:runCategory: Records & libraries

Quick start

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())

cURL waits for the result with Prefer: wait; when the job outlives the wait, it answers 202 with the job's URLs.

Input schema

stringrequired
The kit's name, 1–200 characters. Required.
min length 1 · max length 200
Example: SS27 core
array<object>optional
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.
at most 240 items
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"}]
- stringrequired
  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
- stringrequired
  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).
  max length 2048 · pattern: ^(https://|art:|file:).+$
  Example: https://files.example.com/brand_kit.create/1.jpg
- stringoptional
  Optional. Your own name for it (12oz selvedge); the kit shows it instead of a generated label.
  max length 200
  Example: 12oz selvedge
array<object>optional
The kit's palette, up to 10 colours, each {hex, name, pantone}. A design made with the kit uses these colours as its palette.
at most 10 items
Example: [{"hex":"#1A2B3C","name":"ink","pantone":"19-4010 TCX"},{"hex":"#F4EFE6"}]
- stringrequired
  The colour as #RRGGBB, like "#E8D9C4".
  pattern: ^#[0-9A-Fa-f]{6}$
- stringoptional
  A name for the colour.
- stringoptional
  Its Pantone code, when known.

Output schema

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.
objectoptional
How many items were sent and are ready, and why any are not.
- integeroptional
  Items sent.
- integeroptional
  Items ready to use.
- 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.

Required-fields example

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

Full example

{
  "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"
    }
  ]
}

Response example

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

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

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.

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

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.

Pricing: Estimate a request before you run it, or see the price of each option.

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

Schema changes follow Versioning.