For AI agents: this page is also available as Markdown at https://docs.refabric.com/records-and-libraries/overview.md, and the index of every page is https://docs.refabric.com/llms.txt.
Records & libraries
Records & libraries
The reusable things tasks make and take — records, library items and your uploads — and how they differ from plain files.
A file is one image, video, SVG or PDF. A record is a structured result with an id — a
moodboard, a fabric, a brand kit, a range plan, a shoot — whose content is its data and whose url
is only a preview. A library item is a pose, a background or a model that a task can place in
its result. You address all of them the same way: a handle, <kind>:<id>, that any field taking
that kind accepts as it is.
A record is not a folder of files. A moodboard's images are its data.items[].url, not separate
files, and a job that makes a record lists only the record (Files and media).
How it works
- Tasks in the records and libraries category make records and library items; shoot tasks make a
shoot record. Your uploads (
POST /v1/files) are products (file:…). - Every record and library item has a handle. Pass it to the field that takes its kind — a moodboard
to
moodboards, a pose toposes, a background tobackground. GET /v1/refs/{kind}lists what you can pass for a kind;GET /v1/files/{handle}reads one.
Kinds
The kinds are the ref_kind vocabulary, listed
live with what each one is. They fall into three groups:
| Group | Use it for | Example | What it contains |
|---|---|---|---|
| Your files | the images you send and the images jobs make | file:1234 (an upload), art:x1 (a delivered file) | the bytes at url; an upload's data holds what you said about the product |
| Records | evidence a later task designs or shoots from | moodboard:…, fabric:…, brand_kit:…, range_plan:…, photoshoot:… | data — the record's fields and items[]; url is a preview |
| Library items | who appears, how they stand, what is behind them | model:…, pose:…, background:…, pose_preset:… | the image at url; a model's data may describe it |
Yours and Refabric's
Models, poses and backgrounds list every one your account can use. Records list your own; for a
moodboard or a fabric,
curated=true lists Refabric's curated ones instead (List what you can reference).
curl -s "https://api.refabric.com/v1/refs/moodboard?curated=true" -H "Authorization: Key $REFABRIC_API_KEY"Is it ready?
A record can exist before it can be used. Its data.status is one of the
record_status values; pass it to a task once
it is ready. A record that is still processing is refused by the task that needs it, with a code
that says so (for example moodboard_not_ready).