# List what you can reference

> One page of everything of this kind a task input may take — your uploads and the library — each with the `file` handle a task accepts.

`GET https://api.refabric.com/v1/refs/{kind}`

**Filters and sorting**

- `curated=true` lists Refabric's own records instead of yours.
- `q` searches files and models; `base` lists one model's saved styles.

**Authentication.** A key with `files:read`: the files are your account's.

**Key features**

- Pages of 20 items by default, 100 at most; the listing's own order.

**Common use cases**

- Offer a picker of poses, models or backgrounds a task can take.

**See also**

- `GET /v1/files/{ref}`

Authentication: `Authorization: Key $REFABRIC_API_KEY`, scope `files:read`.

## Path parameters

- `kind` (string, _required_) — What to list: the kind of handle a task field takes.
  Values: `art` (A file a task delivered.); `file` (A file you uploaded: a product photo or another image.); `background` (A background from your library.); `pose` (A pose from your library.); `model` (A model, or one of its saved styles.); `pose_preset` (A saved set of poses and views a shoot can use as a whole.); `moodboard` (A moodboard.); `brand_kit` (A brand kit.); `fabric` (A fabric.); `range_plan` (A range plan.); `photoshoot` (The result of a shoot.)

## Query parameters

- `limit` (integer, _optional_, default: `20`, 1 to 100) — Items per page: default 20, at most 100.
- `cursor` (string | null, _optional_) — The previous page's `next_cursor`, copied back as it came, for the next page. Never build one.
- `base` (string | null, _optional_, max length 100) — `model` only: list the saved STYLES of one base model, as `model:<id>` (a style is passed into `models[]` like a model). Sent to another kind, it is refused.
- `curated` (boolean, _optional_, default: `false`) — For a structured-result kind (`moodboard`, `fabric`): list Refabric's own curated records instead of yours.
- `q` (string | null, _optional_, max length 100) — Free-text filter for `file` and `model`; sent to another kind, it is refused.

## Header parameters

- `Refabric-Version` (string, _optional_, format: date) — The contract version you wrote against (a date). Absent: the current version.
- `X-Request-ID` (string, _optional_, max length 128) — Your own id for this request; we answer it back under X-Client-Request-ID.

## Response 200

Done: the answer is in the body.

- `items` (array<object>, _required_) — This page's items, in the listing's order.
  - `file` (string, _required_) — The opaque `<kind>:<id>` handle — pass this VERBATIM into a task's input field or `GET /v1/files/{ref}`.
    Example: `file:1234`
  - `url` (string, _required_) — The PREVIEW image — the small copy where one exists, the image itself where it does not. It is for rendering the row; addressing the thing is `file`'s job. Empty when the row carries no image yet.
    Example: `https://files.refabric.com/thumb/1234.png`
  - `name` (string | null, _optional_) — A human-readable name for a picker row; falls back to the kind. A `background` and a `pose` have none (their row is the image and its one word).
    Example: `Linen shirt`
  - `external_id` (string | null, _optional_) — `file` (a product) only: your own id for it (SKU), when you gave one.
    Example: `SKU-1`
  - `gender` (string | null, _optional_) — `model` and `pose` only: who is pictured, when known.
    Values: `woman` (An adult woman. When the person pictured is an adult woman.); `man` (An adult man. When the person pictured is an adult man.); `girl` (A girl (a child). When the person pictured is a girl.); `boy` (A boy (a child). When the person pictured is a boy.)
    Example: `woman`
  - `base` (string | null, _optional_) — `model` only, a style: the base model it is a style of (`model:…`).
    Example: `model:9f3c01`
  - `kind` (string | null, _optional_) — `background` only: what the backdrop shows, when known.
    Values: `scene` (A photo of a place or setting. A shoot sets the model in this place.); `studio` (A plain studio backdrop of one colour. A shoot puts the model on that exact colour, as a clean studio photo. When the photo is a plain one-colour backdrop (white, grey, beige) and you want studio shots on that colour.)
    Example: `studio`
  - `deletable` (boolean | null, _optional_) — Whether `DELETE /v1/files/{ref}` deletes it: true for `art:…` of your own; any other answers `422 file_not_deletable`.
    Example: `true`
- `has_more` (boolean, _required_) — Whether another page follows this one.
  Example: `false`
- `next_cursor` (string | null, _optional_) — Send it back as `cursor` for the next page. Absent on the last page. Opaque: never build or edit one.
  Example: `eyJsIjoiY2hhbmdlbG9nIn0`

```json
{
  "items": [],
  "next_cursor": "eyJsIjoiY2hhbmdlbG9nIn0",
  "has_more": false
}
```

## Response 400

The request cannot be read as it was sent (a header, the URL or the body's form).

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 401

No valid API key was sent.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 403

Your key or your plan does not allow this.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 404

Nothing has this address.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 422

A field is missing or has a value this operation cannot use.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 429

Too many requests: wait for the number of seconds in the Retry-After header.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 500

Something went wrong on our side; retry, and quote the request id if it keeps happening.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Request

```python
import os
import requests

url = "https://api.refabric.com/v1/refs/{kind}"

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/refs/{kind}';
const options = {method: 'GET', headers: {Authorization: `Key ${process.env.REFABRIC_API_KEY}`}};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}
```

```bash
curl --request GET \
    --url https://api.refabric.com/v1/refs/{kind} \
    --header "Authorization: Key $REFABRIC_API_KEY"
```