Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-api-reference/fabric.add_colour.md, and the index of every page is https://docs.refabric.com/llms.txt.

Records & libraries

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_colourTask: fabric.add_colourScope: 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/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())

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

    pattern: ^fabric:[0-9a-fA-F-]{32,36}$

    Example: fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60

  • objectrequired

    The colour to render the fabric in, {hex, pantone?}. It appears in the fabric's data.colours and data.items.

    Example: {"hex":"#7A1F2B"}

Output schema

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

Required-fields example

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

Full example

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

Response example

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

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

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.

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 formatOne fabric: record: its data is JSON in the record vocabulary, its url a preview image.
Outputs per jobOne record file: the fabric you named.

Choosing a task

Errors

Related

Good to know

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

    For agents and code generation

    Schema changes follow Versioning.