For AI agents: this page is also available as Markdown at https://docs.refabric.com/records-and-libraries/using-records-in-tasks.md, and the index of every page is https://docs.refabric.com/llms.txt.
Records & libraries
Using records in tasks
How to pass a file, a record or a library item to a task, which form to prefer, and what a record does to the result.
A task field that takes a record or an image accepts a handle as one string. The field's schema says which forms it takes; this page explains the forms and how they behave.
Accepted forms
| Form | Example | Where it comes from | Accepted by |
|---|---|---|---|
| a delivered file | art:x1 | a job result's files[].file | every media field |
| an upload | file:1234 | POST /v1/files | every media field |
| a record handle | moodboard:…, brand_kit:…, fabric:… | a record-making job's result, or GET /v1/refs/{kind} | the field that takes that kind |
| a library handle | model:…, pose:…, background:… | GET /v1/refs/{kind} | the field that takes that kind |
| a part of a record | a data.items[].url | GET /v1/files/{handle} | every media field |
| a url | https://… | anywhere public | every media field |
A job id is not a handle: pass a file of the job (files[].file), never its job_id.
Which form to prefer
- A handle we gave you (
art:…,file:…, a record or library handle). It never changes, and a file we made keeps its context — what made it and where it belongs. - A url we gave you. It works, and points at the same file, but a url can change; store the handle instead (Files and media).
- A url of another site. It is fetched when you submit and kept as your own
file:…(Files and media).
{ "prompt": "a resort dress", "moodboards": ["moodboard:3f2a…"],
"references": [ { "image": "fabric:91c0…", "use_case": "fabric" } ] }How records are made
- By a task. Moodboards, brand kits, range plans, fabrics, poses and backgrounds are made by their own tasks, listed under records and libraries in the Task API Reference. A shoot makes a shoot record.
- By upload.
POST /v1/filesmakes a product (file:…) — not a record of another kind (Upload). - In the app. Models and their styles, and saved pose sets, are created in the app;
GET /v1/refs/modelandGET /v1/refs/pose_presetlist the ones you can use.
What a record does to a result
A record is evidence the task works from; each task's page says what it takes from it.
A change to a record applies to future jobs; earlier outputs keep their files. For example,
fabric.add_colour adds a colour to a fabric, and the jobs that used the fabric before keep their
files.