Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/api-reference/platform/files/upload-a-file.md, and the index of every page is https://docs.refabric.com/llms.txt.

Platform API › Files

Upload a file

201 with the file's address (file:…), which any task input takes.

POSThttps://api.refabric.com/v1/files
import os
import requests

url = "https://api.refabric.com/v1/files"

payload = { "url": "string" }
headers = {
    "Authorization": f"Key {os.environ['REFABRIC_API_KEY']}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
{
  "url": "https://files.refabric.com/art/3f2a.png",
  "media_type": "image/png",
  "file": "art:3f2a",
  "task": "image.expand",
  "job_id": "9b2f4c1d0e8a",
  "created_at": "2026-10-05T09:30:12Z",
  "data": {}
}

Modes

  • 1. By URL (JSON {url}) — a public https address; a URL that already has an address answers that file.
  • 2. By bytes (multipart) — the file itself.

Authentication. A key with files:write: an upload is stored in your account.

Key features

  • Accepted types: PNG, JPEG, WebP, GIF, BMP or PDF. The size cap is read live from GET /v1/meta.

Common use cases

  • Give a product photo an address once and pass it to several tasks.
  • Attach what you know about the product (name, external_id, items).

Conflicts. The same url answers the same file; the same url with different details answers 409 conflict. Bytes sent again create a new file.

See also

  • GET /v1/files/{ref}
  • POST /v1/tasks/{name}

Authorization

Authorization: Key $REFABRIC_API_KEYScope: files:write

Parameters

Header parameters

  • stringoptional

    The contract version you wrote against (a date). Absent: the current version.

    format: date

  • stringoptional

    Your own id for this request; we answer it back under X-Client-Request-ID.

    max length 128

Body

application/json

  • stringrequired

    A URL of a stored object. The same file sent at different spellings of its URL is one file.

    min length 1

  • stringoptionalDefault:

    The product's name, shown in listings.

  • stringoptionalnullable

    Your own id for the product (SKU). A number is taken as text.

  • stringoptionalDefault:

    A fit note: how the garment fits or should sit.

  • stringoptional

    What the product is. The shoots read it from the product: how it is worn, framed and restored.

    Values

    • top — Shirts, blouses, T-shirts, knitwear and other upper-body garments. When the product is worn on the upper body.
    • bottom — Trousers, skirts, shorts and other lower-body garments. When the product is worn on the lower body.
    • dress — Dresses and jumpsuits — one piece covering upper and lower body. When the product is one piece covering upper and lower body.
    • outerwear — Coats, jackets and blazers worn over other garments. When the product is worn over other garments.
    • full_look — A complete outfit of several garments worn together. When the photo shows a whole outfit rather than one garment.
    • accessory — Bags, belts, hats, scarves, jewellery and similar items. When the product is an accessory: a bag, belt, hat, scarf or jewellery.
    • shoe — Footwear. When the product is footwear.
    • swimwear — Swimsuits, bikinis and swim shorts. When the product is swimwear.
    • lingerie — Underwear and sleepwear. When the product is underwear or sleepwear.
  • array<object>optional

    Your other photos of the product: its back/side, its label, its details.

Response

201 — Created: the body is what was made.

  • stringrequired

    Where the file is. A public, permanent address you can open or download.

    Example: https://files.refabric.com/art/3f2a.png

  • stringrequired

    The file's standard media type.

    Example: image/png

  • stringrequired

    Its address; pass it to a task as it is.

    Example: art:3f2a

  • stringoptionalnullable

    The task that made it.

    Example: image.expand

  • stringoptionalnullable

    The job that made it.

    Example: 9b2f4c1d0e8a

  • stringoptionalnullable

    When it was made, ISO-8601 in UTC.

    Example: 2026-10-05T09:30:12Z

  • objectoptionalnullable

    What the file means, in the record vocabulary.

  • 400 — The request cannot be read as it was sent (a header, the URL or the body's form).
  • 401 — No valid API key was sent.
  • 403 — Your key or your plan does not allow this.
  • 409 — The request conflicts with the current state of what it names.
  • 413 — The body is larger than this operation takes.
  • 415 — The body's media type is not one this operation takes.
  • 422 — A field is missing or has a value this operation cannot use.
  • 429 — Too many requests: wait for the number of seconds in the Retry-After header.
  • 500 — Something went wrong on our side; retry, and quote the request id if it keeps happening.