# Read a vocabulary

> One named list of values by name, each value with what it means.

`GET https://api.refabric.com/v1/vocab/{name}`

**Authentication.** No key: the reference is the same for every reader and shows nothing of an account.

**Common use cases**

- Read a shared list's values live.

**Conflicts.** An unknown name answers `404`. A list only one task field takes has no name here: its values are in the task's schema (`GET /v1/tasks/{name}`).

**See also**

- `GET /v1/vocab`

Authentication: none — this operation needs no key.

## Path parameters

- `name` (string, _required_)

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

- `name` (string, _required_) — The vocabulary's name.
  Example: `resolution`
- `description` (string, _required_) — What it chooses.
  Example: `How large the image is.`
- `values` (array<object>, _required_) — Its values; for a list whose values may change, as of now.
  Example: `[{"description":"About 2048 px.","label":"2K","value":"2k"}]`
  - `value` (string, _required_) — The value, as it is sent and answered.
    Example: `2k`
  - `label` (string, _required_) — Its short name for a screen.
    Example: `2K`
  - `description` (string, _required_) — What choosing it does.
    Example: `About 2048 px.`
  - `choose_when` (string | null, _optional_) — When to pick it rather than the default.
    Example: `Print.`
  - `group` (string | null, _optional_) — The group it belongs to.
    Example: `record_part`
  - `since` (string | null, _optional_) — When it was added.
    Example: `2026-10-01`
  - `image` (string | null, _optional_) — A preview picture to show next to it.
    Example: `https://files.refabric.com/vocab/studio.png`
  - `default` (boolean | null, _optional_) — Present and `true` on the default value.
    Example: `true`
  - `deprecated` (boolean | null, _optional_) — Present and `true` when it is on its way out.
    Example: `true`
  - `aliases` (array<string> | null, _optional_) — Older spellings still accepted.
    Example: `["pose_setting"]`
  - `used_in` (array<object> | null, _optional_) — Where this value is accepted.
    - `where` (string, _required_) — The task, or the operation's request line.
      Example: `image.generate`
    - `field` (string, _required_) — The field inside it.
      Example: `aspect_ratio`
    - `direction` (string, _required_) — Whether it is sent or answered.
      Values: `input` (A request sends it.); `output` (An answer or a webhook carries it.)
      Example: `input`
- `default` (string | null, _optional_) — The value used when none is sent.
  Example: `2k`
- `concept` (string | null, _optional_) — The concept it belongs to.
  Example: `image`
- `subset_of` (string | null, _optional_) — The vocabulary it narrows.
  Example: `use_case`
- `groups` (array<object> | null, _optional_) — The groups its values fall into.
  - `name` (string, _required_) — The group's name.
    Example: `record_part`
  - `description` (string, _required_) — What its values have in common.
    Example: `A part.`
- `source` (string | null, _optional_) — Present when its values may change; read them live.
  Values: `data` (Its values may change; read them live.)
  Example: `data`
- `used_in` (array<object> | null, _optional_) — Where it is used.
  - `where` (string, _required_) — The task, or the operation's request line.
    Example: `image.generate`
  - `field` (string, _required_) — The field inside it.
    Example: `aspect_ratio`
  - `direction` (string, _required_) — Whether it is sent or answered.
    Values: `input` (A request sends it.); `output` (An answer or a webhook carries it.)
    Example: `input`

```json
{
  "name": "resolution",
  "description": "How large the image is.",
  "values": [
    {
      "description": "About 2048 px.",
      "label": "2K",
      "value": "2k"
    }
  ],
  "default": "2k",
  "concept": "image",
  "subset_of": "use_case",
  "groups": [],
  "source": "data",
  "used_in": []
}
```

## 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 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/vocab/{name}"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/vocab/{name}';
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/vocab/{name}
```