# Add a colour to a fabric

> Render one more colour of a fabric you made with fabric.create. The result is the same fabric record with the new colour in it.

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

Name a finished fabric of yours and one colour, and get the same fabric back with that colour rendered. The new colourway appears beside the fabric's other colours.

## 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/fabric.add_colour",
    headers=headers,
    json={
        "fabric": "fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60",
        "colour": {
            "hex": "#7A1F2B",
        },
    },
).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/fabric.add_colour", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "fabric": "fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60",
    "colour": {
      "hex": "#7A1F2B"
    }
  }),
}).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/fabric.add_colour" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"fabric":"fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60","colour":{"hex":"#7A1F2B"}}'
```

## Input schema

- `fabric` (string, _required_, pattern: ^fabric:[0-9a-fA-F-]{32,36}$) — The fabric to add the colour to, as "fabric:<id>" — one you made with `fabric.create` (`GET /v1/refs/fabric`). It must have finished (`status: ready`).
  Example: `fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60`
- `colour` (object, _required_) — The colour to render the fabric in, {hex, pantone?}. It appears in the fabric's `data.colours` and `data.items`.
  Example: `{"hex":"#7A1F2B"}`
  - `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
{
  "fabric": "fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60",
  "colour": {
    "hex": "#7A1F2B"
  }
}
```

## Full example

```json
{
  "fabric": "fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60",
  "colour": {
    "hex": "#7A1F2B"
  }
}
```

## Output schema

- `files` (array<object>, _optional_) — One file, the fabric record `fabric:<fabric_id>` (`application/json`): its `data` is name · description · status · external_id · facts · colours[{hex, pantone}] · items[{type: fabric, name: <hex>, url, status}] — each colour's images are items named by the colour. Read it again any time with GET /v1/files/fabric:<id>; pass the handle as a reference (`"image": "fabric:<id>"`, `use_case: "fabric"`) to image.generate.

## Response example

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

## Result example

```json
{
  "job_id": "c1a2b3c4000040008000000000000009",
  "files": [
    {
      "file": "fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60",
      "url": "https://files.example.com/fabric.add_colour/1.png",
      "media_type": "application/json",
      "task": "fabric.create",
      "job_id": "0d9e8f7a6b5c4d3e8f2a9b8c7d6e5f41",
      "created_at": "2026-09-30T09:15:00Z",
      "data": {
        "name": "Washed linen",
        "status": "ready",
        "colours": [
          {
            "hex": "#E9E2D0",
            "pantone": "11-0507"
          },
          {
            "hex": "#7A1F2B",
            "pantone": "19-1557"
          }
        ],
        "items": [
          {
            "type": "fabric",
            "name": "#E9E2D0",
            "url": "https://files.example.com/fabric.add_colour/1.png"
          },
          {
            "type": "fabric",
            "name": "#7A1F2B",
            "url": "https://files.example.com/fabric.add_colour/2.png"
          }
        ]
      }
    }
  ],
  "has_more": false
}
```

The answer is the fabric record, now with the new colour; its `job_id` is the fabric.create job that made the fabric, as on every read of the record.

## Built for

- A new season's colour for a fabric you already have
- A colour a buyer asks for after the fabric is made

## What you get

- The same `fabric:` record, with the new colour in `data.colours` and its images in `data.items`.

## Specs

- **Output format:** One `fabric:` record: its `data` is JSON in the record vocabulary, its `url` a preview image.
- **Outputs per job:** One record file: the fabric you named.

## Choosing a task

- Use this when the fabric is already made and you want one more colour of it. Use `fabric.create` when the fabric is not in your library yet; send its extra colours with it.

## Errors

- `field_not_accepted`
- `invalid_request`
- `invalid_colour`
- `not_found`
- `fabric_not_recolourable`
- `fabric_not_ready`
- `permission_denied`
- `insufficient_credits`
- `processing_failed`

## Related

- `fabric.create` — It runs before: its result is this input.
- `image.generate` — It runs after: it takes this task's result.

## For agents and code generation

- https://api.refabric.com/v1/tasks/fabric.add_colour/llms.txt
- https://api.refabric.com/v1/tasks/fabric.add_colour/openapi.json
- GET https://api.refabric.com/v1/tasks/fabric.add_colour