# Using the Files & Records API

> List, read, upload and delete files and records through the API, and what only the panel can do.

The Files part of the Platform API is four operations: upload a file, list what a task can reference,
read one file or record, and delete a produced file. Every one of them works with handles — the same
strings a task input takes.

## List what you can reference

`GET /v1/refs/{kind}` lists one kind, a page at a time. Every row has the `file` handle to pass, a
`name` and a preview `url`, plus a few words for its kind.

::::code-group
```python
page = s.get(f"{API}/refs/model", params={"limit": 50}).json()
for item in page["items"]:
    print(item["file"], item.get("name"))
# while page["has_more"]: pass page["next_cursor"] as ?cursor=
```

```javascript
const page = await (await fetch(`${API}/refs/model?limit=50`, { headers })).json();
for (const item of page.items) console.log(item.file, item.name);
// while page.has_more: pass page.next_cursor as ?cursor=
```

```bash
curl -s "https://api.refabric.com/v1/refs/model?limit=50" -H "Authorization: Key $REFABRIC_API_KEY"
```
::::

- `q` filters `file` and `model` lists by text (live list: `GET /v1/vocab/ref_kind`).
- `base=model:<id>` lists one model's styles.
- `curated=true` lists Refabric's curated moodboards or fabrics instead of yours.

[List what you can reference →](https://docs.refabric.com/api-reference/platform/files/list-what-you-can-reference)

## Read one

`GET /v1/files/{handle}` answers the file line, and for a record its `data`. `view=basic` leaves out
the large parts (a record's `items`).

```bash
curl -s "https://api.refabric.com/v1/files/moodboard:3f2a…?view=basic" -H "Authorization: Key $REFABRIC_API_KEY"
```

[Read a file →](https://docs.refabric.com/api-reference/platform/files/read-a-file)

## Upload

`POST /v1/files` gives an image an id before any job uses it — by url or by bytes
([Upload](https://docs.refabric.com/task-apis/files-and-media#upload)).

[Upload a file →](https://docs.refabric.com/api-reference/platform/files/upload-a-file)

## Delete

`DELETE /v1/files/{ref}` deletes a produced file (`art:…`); deletion applies to produced files
([Retention & deletion](https://docs.refabric.com/records-and-libraries/retention-and-deletion)).

[Delete a file →](https://docs.refabric.com/api-reference/platform/files/delete-a-file)

## API boundaries

Keys and webhook endpoints are managed in the panel; their routes answer a key with
`403 session_required`.

| Only in the panel | Where |
|---|---|
| Create, roll and revoke API keys | **Panel › Developers › Keys** |
| Register webhook endpoints, read the delivery log, replay a delivery | **Panel › Developers › Webhooks** |

Everything else the panel shows — jobs, the request log, usage, metrics, errors, limits, files and
records, your balance — is read through the same public operations your key can call.

## Related

::::cards
:::card{title="Records & libraries" href="/records-and-libraries/overview"}
Files, records and library items, and how they differ.
:::
:::card{title="Platform API for Files" href="/api-reference/platform/files"}
Every Files operation, with its parameters and answers.
:::
::::