Refabric Docs

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

Records & libraries

Create a range plan

Plan a collection from your moodboards: isolate garments from runway looks, or design new pieces line by line. The plan is delivered as one record whose items are its images.

Endpoint: POST https://api.refabric.com/v1/tasks/range_plan.createTask: range_plan.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/range_plan.create",
    headers=headers,
    json={
        "kind": "new_designs",
        "gender": "womenswear",
        "moodboards": [
            "moodboard:5b3d2c1a-7e6f-4a8b-9c0d-1e2f3a4b5c6d",
        ],
        "garments": [
            {
                "garment_type": "jackets",
            },
        ],
    },
).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

    Who the collection is for. Required for both kinds.

    Values

    • womenswear — A womenswear collection. For a womenswear collection.
    • menswear — A menswear collection. For a menswear collection.
    • unisex — A collection for everyone: no gender scope. For a collection with no gender scope.

    Example: womenswear

  • array<string>required

    The moodboards the plan is made from, as ["moodboard:<id>", …] — yours (GET /v1/refs/moodboard) or curated ones (GET /v1/refs/moodboard?curated=true), at least one, each finished with its analysis. With runway_looks the looks come from them; with new_designs the collection follows them.

    at least 1 items

    Example: ["moodboard:5b3d2c1a-7e6f-4a8b-9c0d-1e2f3a4b5c6d"]

  • stringrequired

    Which kind of range plan to make. Each kind takes its own fields; the schema shows them per kind.

    Values

    • runway_looks — Isolate garments from real runway looks: pick looks from your moodboards in looks and name the garment to take from each. Every look becomes one flat garment image. When your moodboards hold runway looks and you want their garments as flat images.
    • new_designs — Design new pieces as one collection: list the garment lines in garments, each with how many images to make. The collection follows the moodboards (and an optional brand kit). When you want new pieces designed as one collection.

    Example: new_designs

  • stringoptionalDefault:

    The plan's name, shown on the plan and in the ready mail. Optional.

    Example: SS27 capsule

  • stringoptionalDefault: 2K

    The size of every image of the plan. 2K is sharp enough for screens and review; ask for 4K when the result will be printed or zoomed into.

    Values

    • 2K — Standard size, for screens and review.
    • 4K — Large size, for print and zoom. When the image will be printed or zoomed into.

    Example: 2K

  • stringoptional

    A brand kit whose fabrics, prints, colours and looks the collection is designed with, as "brand_kit:<id>" (GET /v1/refs/brand_kit).

    pattern: ^brand_kit:[0-9]+$

    Example: brand_kit:28

  • array<string>optional

    A reference house the collection follows. Its values may change; read them live at GET /v1/vocab/brand_house.

    Example: ["Jacquemus"]

  • array<object>optional

    At least one: the runway looks to isolate, each {image, prompt}. Every look becomes one flat image of the garment its prompt names.

    at least 1 items

  • array<object>optional

    At least one: the garment lines to design, each {garment_type, image_count, prompt, references}. A row's references are at most 1 fabric (use_case: "fabric") and 3 details (no use_case).

    at least 1 items

    Example: [{"garment_type":"jackets","image_count":4,"prompt":"boxy, cropped, raw hems","references":[{"image":"https://files.example.com/range_plan.create/1.jpg","use_case":"fabric"},{"image":"art:c10d55"}]},{"garment_type":"linen wrap skirt","image_count":2}]

Output schema

  • array<object>optional

    ONE file: the plan, range_plan:<id> (application/json). Its data.items are the plan's cells, type: design, each named by its garment line (garment_type) or by the prompt you sent for a runway look, with its image url; a cell that failed carries status: failed. Read it again with GET /v1/files/range_plan:<id>.

  • objectoptional

    How many cells the plan has, how many have an image, and a warning when some have none.

Required-fields example

{
  "kind": "new_designs",
  "gender": "womenswear",
  "moodboards": [
    "moodboard:5b3d2c1a-7e6f-4a8b-9c0d-1e2f3a4b5c6d"
  ],
  "garments": [
    {
      "garment_type": "jackets"
    }
  ]
}

Full example

{
  "kind": "new_designs",
  "name": "SS27 capsule",
  "gender": "womenswear",
  "moodboards": [
    "moodboard:5b3d2c1a-7e6f-4a8b-9c0d-1e2f3a4b5c6d"
  ],
  "brand_kit": "brand_kit:28",
  "brands": [
    "Jacquemus"
  ],
  "garments": [
    {
      "garment_type": "jackets",
      "image_count": 4,
      "prompt": "boxy, cropped, raw hems",
      "references": [
        {
          "image": "https://files.example.com/range_plan.create/1.jpg",
          "use_case": "fabric"
        },
        {
          "image": "art:c10d55"
        }
      ]
    },
    {
      "garment_type": "linen wrap skirt",
      "image_count": 2
    }
  ],
  "resolution": "2K"
}

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": "range_plan:crp_5f0c2a1e9b8d",
      "url": "https://files.example.com/range_plan.create/2.png",
      "media_type": "application/json",
      "task": "range_plan.create",
      "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
      "created_at": "2026-09-30T10:14:02Z",
      "data": {
        "name": "SS27 capsule",
        "status": "ready",
        "items": [
          {
            "type": "design",
            "name": "jackets",
            "url": "https://files.example.com/range_plan.create/3.png"
          },
          {
            "type": "design",
            "name": "jackets",
            "url": "https://files.example.com/range_plan.create/4.png"
          },
          {
            "type": "design",
            "name": "jackets",
            "url": "https://files.example.com/range_plan.create/5.png"
          },
          {
            "type": "design",
            "name": "jackets",
            "url": "https://files.example.com/range_plan.create/6.png"
          },
          {
            "type": "design",
            "name": "linen wrap skirt",
            "url": "https://files.example.com/range_plan.create/7.png"
          },
          {
            "type": "design",
            "name": "linen wrap skirt",
            "status": "failed"
          }
        ]
      }
    }
  ],
  "has_more": false,
  "summary": {
    "requested": 6,
    "delivered": 5,
    "warnings": [
      {
        "code": "output_not_produced",
        "field": "items",
        "message": "1 of the plan's 6 cells have no image; they are in the plan with status failed."
      }
    ]
  }
}

A runway-looks plan takes kind: runway_looks and looks: [{"image": <a look url from a moodboard's data.items>, "prompt": "the trench coat"}] instead of garments and brand_kit.

Name your moodboards and get a collection plan back as one record. With `runway_looks`, each look you pick becomes a flat image of the garment you name. With `new_designs`, each garment line is designed piece by piece from the moodboards, your brand kit and your references. You get a mail when the plan is ready.

Built for

  • A season's line plan from your trend boards
  • Key garments isolated from runway looks
  • New designs per garment line, in your brand's look

What you get

  • One range_plan: record; its data.items are the plan's cells, each named by its garment line or your look's prompt, with its image url.
  • A summary that counts the plan's cells and the cells with an image, and warns when some have none.

Specs

Input formatsImages, 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 countlooks: at least 1, each with its image; garments: at least 1, each with its image
Output formatOne range_plan: record: its data is JSON in the record vocabulary, its url a preview image.
Output resolution2K, 4K
Outputs per jobOne record file, however many cells the plan has.

Errors

Related

Good to know

  • moodboards holds at least 1 items.
  • looks holds at least 1 items.
  • garments holds at least 1 items.
  • garments[].image_count is from 1 to 20.
  • garments[].references holds at most 4 items.
  • looks is taken only with kind: runway_looks.
  • garments is taken only with kind: new_designs.
  • brand_kit is taken only with kind: new_designs.

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

For agents and code generation

Schema changes follow Versioning.