# List tasks

> Every task you can run, each with its `inputSchema` and `outputSchema`.

`GET https://api.refabric.com/v1/tasks`

**Filters and sorting**

- `surface` lists only the tasks you may run there — with your key; without a key it is ignored.

**Authentication.** No key: the published tasks are the same for every reader. A key you send is still checked, and only `surface` reads it.

**Common use cases**

- Build a form or a tool definition from a task's `inputSchema`.
- See which tasks exist before you call one.

**See also**

- `GET /v1/tasks/{name}`
- `POST /v1/tasks/{name}`

Authentication: none — this operation needs no key.

## Query parameters

- `surface` (string, _optional_, default: ``) — Narrow to what you may run on this surface. Needs your key (or a signed-in session); without one it is ignored.

## 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_) — The tasks, in catalogue order.
  - `name` (string, _required_) — The task's name; run it at its path.
    Example: `image.generate`
  - `inputSchema` (object, _required_, follows https://json-schema.org/draft/2020-12/schema) — What a run takes: the request body's JSON Schema.
  - `title` (string | null, _optional_) — The task's name in words.
    Example: `Generate an image`
  - `description` (string | null, _optional_) — What the task does, in one sentence.
    Example: `Makes one.`
  - `category` (string | null, _optional_) — What kind of work a task does — the group it is listed under in the task catalogue.
    Values: `design_generation` (Makes new designs and patterns from your words, reference images or a moodboard.); `image_editing` (Changes one thing in an image you send — its background, frame, face, pose, fabric, views or finish — and keeps the rest.); `photoshoots` (Turns product photos into shoot photos: on a model, on a ghost mannequin or on a mannequin.); `video` (Turns an image into a short video.); `production_prep` (Takes what production needs from an image: its materials, colours or print, a larger copy, or a vector file.); `records_libraries` (Makes the records and library items other tasks take: moodboards, brand kits, range plans, fabrics, poses and backgrounds.)
    Example: `design_generation`
  - `outputSchema` (object | null, _optional_, follows https://json-schema.org/draft/2020-12/schema) — What a job's result holds: its files' `data` as a JSON Schema.
  - `unit` (string | null, _optional_) — What one unit of the task's work is.
    Example: `image`
  - `status` (string | null, _optional_) — Present when the task is on its way out.
    Values: `deprecated` (It still runs, and will be removed; its page says when.)
    Example: `deprecated`
  - `docs` (object | null, _optional_) — The task page's words.
    - `lead` (string, _required_) — The page's opening paragraph.
      Example: `Makes a design.`
    - `built_for` (array<string>, _required_) — What the task is for.
      Example: `["Concepts."]`
    - `what_you_get` (array<string>, _required_) — What a job delivers, one sentence each.
      Example: `["One image."]`
    - `outputs` (object, _required_) — How many files a job delivers and in which order.
      Example: `{"count":"One file per image.","count_depends_on":["image_count"]}`
      - `count` (string, _required_) — How many files a job delivers, in words.
        Example: `One file per image.`
      - `count_depends_on` (array<string>, _required_) — The input fields the count depends on.
        Example: `["image_count"]`
      - `order` (string | null, _optional_) — The files' order.
        Example: `The order of `images`.`
      - `absent_when` (string | null, _optional_) — When a file asked for is not delivered.
        Example: `A pose that cannot be made.`
    - `specs` (array<object>, _required_) — The Specs table, in its order.
      Example: `[{"key":"output_format","text":"PNG","title":"Output format"}]`
      - `key` (string, _required_) — Which row.
        Values: `input_formats` (Input formats); `input_count` (Input count); `output_format` (Output format); `output_resolution` (Output resolution); `aspect_ratios` (Aspect ratios); `outputs_per_job` (Outputs per job); `watermark` (Watermark); `commercial_use` (Commercial use); `content_checks` (Content checks); `reproducibility` (Reproducibility)
        Example: `output_format`
      - `title` (string, _required_) — The row's title.
        Example: `Output format`
      - `text` (string, _required_) — What the row says.
        Example: `PNG`
    - `limitations` (array<string>, _required_) — Good to know about this task.
    - `errors` (array<string>, _required_) — Every error code a call of the task can answer (`GET /v1/errors`).
      Example: `["invalid_request"]`
    - `compares` (array<object> | null, _optional_) — How it differs from neighbouring tasks.
      - `task` (string, _required_) — The other task.
        Example: `image.edit`
      - `use_this_when` (string, _required_) — When to use this task.
        Example: `You want a new design.`
      - `use_other_when` (string, _required_) — When to use the other one.
        Example: `You want to change one thing.`
    - `related` (array<object> | null, _optional_) — The tasks before and after it in a chain.
      - `task` (string, _required_) — The other task.
        Example: `image.upscale`
      - `relation` (string, _required_) — Where it sits.
        Values: `before` (It runs before: its result is this input.); `after` (It runs after: it takes this task's result.); `sibling` (It does a neighbouring job.)
        Example: `after`
    - `prompting` (string | null, _optional_) — How to write the prompt.
      Example: `Name the garment.`

```json
{
  "items": []
}
```

## 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 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 requests

url = "https://api.refabric.com/v1/tasks"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/tasks';
const options = {method: 'GET'};

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/tasks
```