# 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

1. **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.
2. **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](https://docs.refabric.com/task-apis/files-and-media#file-and-url)).
3. **A url of another site.** It is fetched when you submit and kept as your own `file:…`
   ([Files and media](https://docs.refabric.com/task-apis/files-and-media#reuse-pass-a-file-back)).

```json
{ "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](https://docs.refabric.com/task-api-reference).
  A shoot makes a shoot record.
- **By upload.** `POST /v1/files` makes a product (`file:…`) — not a record of another kind
  ([Upload](https://docs.refabric.com/task-apis/files-and-media#upload)).
- **In the app.** Models and their styles, and saved pose sets, are created in the app;
  `GET /v1/refs/model` and `GET /v1/refs/pose_preset` list the ones you can use.

## What a record does to a result

:::note
A record is evidence the task works from; each task's page says what it takes from it.
:::

:::note
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.
:::

## Related

::::cards
:::card{title="Records & libraries" href="/records-and-libraries/overview"}
The kinds, and which are yours or Refabric's.
:::
:::card{title="Common task arguments" href="/task-apis/common-task-arguments"}
The media, model, pose and background fields.
:::
:::card{title="Recipes" href="/task-apis/recipes"}
Chains that pass one step's record to the next.
:::
::::