# 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](https://docs.refabric.com/task-apis/files-and-media#two-kinds)).

## 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 to `poses`, a background to `background`.
- `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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#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](https://docs.refabric.com/api-reference/platform/files/list-what-you-can-reference)).

```bash
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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#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`).

## Related

::::cards
:::card{title="Using records in tasks" href="/records-and-libraries/using-records-in-tasks"}
Which forms a field accepts, and which to prefer.
:::
:::card{title="Using the Files & Records API" href="/records-and-libraries/using-the-files-and-records-api"}
List, read and delete files and records.
:::
:::card{title="Retention & deletion" href="/records-and-libraries/retention-and-deletion"}
What deleting each kind changes.
:::
::::