For AI agents: this page is also available as Markdown at https://docs.refabric.com/api-reference/platform/reference-data/read-a-vocabulary.md, and the index of every page is https://docs.refabric.com/llms.txt.
Platform API › Reference data
Read a vocabulary
One named list of values by name, each value with what it means.
https://api.refabric.com/v1/vocab/{name}import requests
url = "https://api.refabric.com/v1/vocab/{name}"
response = requests.get(url)
print(response.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": []
}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
Authorization
No key needed.
Parameters
Path parameters
- stringrequired
Header parameters
- stringoptional
The contract version you wrote against (a date). Absent: the current version.
format: date
- stringoptional
Your own id for this request; we answer it back under X-Client-Request-ID.
max length 128
Response
200 — Done: the answer is in the body.
- stringrequired
The vocabulary's name.
Example:
resolution - stringrequired
What it chooses.
Example:
How large the image is. - array<object>required
Its values; for a list whose values may change, as of now.
Example:
[{"description":"About 2048 px.","label":"2K","value":"2k"}]- stringrequired
The value, as it is sent and answered.
Example:
2k - stringrequired
Its short name for a screen.
Example:
2K - stringrequired
What choosing it does.
Example:
About 2048 px. - stringoptionalnullable
When to pick it rather than the default.
Example:
Print. - stringoptionalnullable
The group it belongs to.
Example:
record_part - stringoptionalnullable
When it was added.
Example:
2026-10-01 - stringoptionalnullable
A preview picture to show next to it.
Example:
https://files.refabric.com/vocab/studio.png - booleanoptionalnullable
Present and
trueon the default value.Example:
true - booleanoptionalnullable
Present and
truewhen it is on its way out.Example:
true - array<string>optionalnullable
Older spellings still accepted.
Example:
["pose_setting"] - array<object>optionalnullable
Where this value is accepted.
- stringrequired
The task, or the operation's request line.
Example:
image.generate - stringrequired
The field inside it.
Example:
aspect_ratio - stringrequired
Whether it is sent or answered.
Values
input— A request sends it.output— An answer or a webhook carries it.
Example:
input
- stringoptionalnullable
The value used when none is sent.
Example:
2k - stringoptionalnullable
The concept it belongs to.
Example:
image - stringoptionalnullable
The vocabulary it narrows.
Example:
use_case - array<object>optionalnullable
The groups its values fall into.
- stringrequired
The group's name.
Example:
record_part - stringrequired
What its values have in common.
Example:
A part.
- stringoptionalnullable
Present when its values may change; read them live.
Values
data— Its values may change; read them live.
Example:
data - array<object>optionalnullable
Where it is used.
- stringrequired
The task, or the operation's request line.
Example:
image.generate - stringrequired
The field inside it.
Example:
aspect_ratio - stringrequired
Whether it is sent or answered.
Values
input— A request sends it.output— An answer or a webhook carries it.
Example:
input
- 401 — No valid API key was sent.
- 403 — Your key or your plan does not allow this.
- 404 — Nothing has this address.
- 429 — Too many requests: wait for the number of seconds in the Retry-After header.
- 500 — Something went wrong on our side; retry, and quote the request id if it keeps happening.