Create a fabric

Endpoint: POST https://api.refabric.com/v1/tasks/fabric.createTask: fabric.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/fabric.create",
    headers=headers,
    json={
        "name": "Washed linen",
        "images": [
            "https://cdn.example.com/linen-flat.jpg",
            "file:913",
        ],
    },
).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

• namestringrequired

  The fabric's name, as it is listed in your library.

  min length 1 · max length 255

  Example: Washed linen

• imagesarray<string>required

  1–4 photos of the fabric, each ONE string: a url, a file from an earlier result (art:…), an upload (file:…) or an items[].url of a record. The FIRST is the reference: a flat, well-lit swatch — the fabric and its own colour are made from it; the others help fill in its facts. Addresses that are not publicly reachable are refused.

  at least 1 items · at most 4 items

  Example: ["https://cdn.example.com/linen-flat.jpg","file:913"]

• descriptionstringoptional

  Your own words about the fabric; returned as data.description.

  max length 2000

  Example: SS27 shirting base

• external_idstringoptional

  Your own code for the fabric, to match it in your system; returned as data.external_id.

  max length 255

  Example: LIN-0042

• factsobjectoptional

  What you already know about the fabric, in the shape data.facts returns. Each fact you send is used as given; the rest are filled in for you.

  Example: {"fabric_type":"Linen","composition":[{"name":"Linen","percentage":100}],"pattern":"Solid","weight_gsm":180}

  Show child attributes
• coloursarray<object>optional

  Up to 24 EXTRA colours to render the fabric in, each {hex}. The fabric's own colour is taken from the first photo and is not sent. Each extra colour is priced; see /estimate.

  at most 24 items

  Example: [{"hex":"#1F3A5F"},{"hex":"#C8B89A"}]

  Show child attributes

Output schema

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

• summaryobjectoptional

  How many colourways were asked for and rendered, and which extra colours did not render.

  Show child attributes

Required-fields example

{
  "name": "Washed linen",
  "images": [
    "https://cdn.example.com/linen-flat.jpg",
    "file:913"
  ]
}

Full example

{
  "name": "Washed linen",
  "description": "SS27 shirting base",
  "external_id": "LIN-0042",
  "images": [
    "https://cdn.example.com/linen-flat.jpg",
    "file:913"
  ],
  "facts": {
    "fabric_type": "Linen",
    "composition": [
      {
        "name": "Linen",
        "percentage": 100
      }
    ],
    "pattern": "Solid",
    "weight_gsm": 180
  },
  "colours": [
    {
      "hex": "#1F3A5F"
    },
    {
      "hex": "#C8B89A"
    }
  ]
}

Response example

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

Result example

{
  "job_id": "0d9e8f7a6b5c4d3e8f2a9b8c7d6e5f41",
  "files": [
    {
      "file": "fabric:5f0c1d2e-8a41-4b7e-9c3d-1a2b3c4d5e60",
      "url": "https://files.example.com/fabric.create/1.png",
      "media_type": "application/json",
      "task": "fabric.create",
      "job_id": "0d9e8f7a6b5c4d3e8f2a9b8c7d6e5f41",
      "created_at": "2026-09-30T09:15:00Z",
      "data": {
        "name": "Washed linen",
        "description": "SS27 shirting base",
        "status": "ready",
        "external_id": "LIN-0042",
        "facts": {
          "weight_gsm": 180,
          "composition": [
            {
              "name": "Linen",
              "percentage": 100
            }
          ],
          "pattern": "Solid",
          "fabric_type": "Linen"
        },
        "colours": [
          {
            "hex": "#E9E2D0",
            "pantone": "11-0507"
          },
          {
            "hex": "#1F3A5F",
            "pantone": "19-4027"
          },
          {
            "hex": "#C8B89A",
            "pantone": "15-1214"
          }
        ],
        "items": [
          {
            "type": "fabric",
            "name": "#E9E2D0",
            "url": "https://files.example.com/fabric.create/1.png"
          },
          {
            "type": "fabric",
            "name": "#E9E2D0",
            "url": "https://files.example.com/fabric.create/2.png"
          },
          {
            "type": "fabric",
            "name": "#1F3A5F",
            "url": "https://files.example.com/fabric.create/3.png"
          },
          {
            "type": "fabric",
            "name": "#C8B89A",
            "status": "failed"
          }
        ]
      }
    }
  ],
  "has_more": false,
  "summary": {
    "requested": 3,
    "delivered": 2,
    "warnings": [
      {
        "code": "output_not_produced",
        "field": "colours[1]",
        "message": "This colour did not render. It was not charged and shows status failed in the fabric."
      }
    ]
  }
}

Send photos of a fabric and get a fabric in your library, with its type, composition, pattern and weight filled in and rendered in every extra colour you ask for. Pass the fabric to generation to design with it.

Built for

• Your suppliers' fabrics, ready to design with
• One fabric in several colourways
• A fabric library matched to your own codes (external_id)

What you get

• One fabric: record — its name, description, status, your external_id, its facts and its colours.
• Each colourway's images in the record's data.items, named by the colour.
• A summary that counts the colourways asked for and rendered, and names in warnings each extra colour that did not render.

Specs

Choosing a task

• Use this when the fabric is not in your library yet. Use fabric.add_colour when the fabric is already made and you want one more colour of it.

Errors

• field_not_accepted
• invalid_request
• name_required
• images_required
• too_many_images
• image_not_public
• not_found
• invalid_colour
• too_many_colours
• invalid_weight
• permission_denied
• insufficient_credits
• processing_failed

Related

• fabric.add_colour · It runs after: it takes this task's result.
• image.generate · It runs after: it takes this task's result.

Good to know

• name is at most 255 characters.
• description is at most 2000 characters.
• external_id is at most 255 characters.
• images holds at least 1 items.
• images holds at most 4 items.
• facts.fabric_type is at most 255 characters.
• facts.composition[].percentage is from 0 to 100.
• facts.pattern is at most 255 characters.
• facts.weight_gsm is from 1 to 10000.
• colours holds at most 24 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/fabric.create/llms.txt
• https://api.refabric.com/v1/tasks/fabric.create/openapi.json
• GET https://api.refabric.com/v1/tasks/fabric.create