Skip to content

Search a field's vocabulary

GET
/fields/{id}/values

Searches the terms of one field’s vocabulary, for pickers and curation screens. Any signed-in user can call this; a field with a read_capability also needs that capability, granted globally.

Use it instead of loading the whole options document from GET /fields, which can be very large. It doesn’t keep the terms private: GET /fields and GET /fields/{id} return the full vocabulary to every signed-in user.

q is matched against each term’s slug, label and aliases, ignoring case and spaces at either end, at every level of the vocabulary. Results are ranked: exact matches first, then terms that start with q, then, with match=substring, terms that contain it; within a rank they are sorted by label, then slug. Without q, the terms are listed in label order. A field without a vocabulary returns no terms.

There is no paging. limit is at most 200, and matched gives the full number of matches. The same vocabulary and query always give the same order.

id
required
string format: uuid

The field definition’s id.

q
string
<= 200 characters

The text to match. Leave it out or empty to list terms in label order. The 200-character limit shown isn’t checked.

match
string
default: prefix
Allowed values: prefix substring

prefix, the default, matches terms whose slug, label or alias starts with q. substring also matches terms that contain it anywhere; those come after the prefix matches. Any other value is treated as prefix.

limit
integer
default: 50 >= 1 <= 200

Maximum number of terms to return. Values below 1 or above 200 are clamped, not refused. matched in the response gives the full count.

status
string
default: active
Allowed values: active deprecated archived any

Which terms to include: active (the default), deprecated, archived or any. Pickers should offer only active terms. Any other value is treated as active.

The matching terms, up to limit.

One set of results from a vocabulary search. matched is the full count, so a client can say how many terms it isn’t showing.

object
values
required

The matching terms, best matches first.

Array<object>

One vocabulary term.

object
value
required

The term’s slug, which is what records store. Unique across the field’s whole vocabulary.

string
label
required

Display text. The slug when the term has no label of its own.

string
path
required

Labels from the top of the vocabulary down to this term, including the term’s own label. One item for a term at the top level.

Array<string>
status
required

active terms can be chosen. deprecated terms still display on records that have them but shouldn’t be offered for new values. archived terms are retired; with replaced_by set, the term was merged into another.

string
Allowed values: active deprecated archived
replaced_by

For a merged term, the slug it was merged into, which may itself have been merged later. A value written through the field-value routes that names the merged term is redirected along these links to the first term that isn’t archived; if they don’t reach one (a missing term, a loop or a very long chain), it isn’t redirected. The result is then checked like any other value, so a deprecated term is accepted only on a record that already holds it.

string
nullable
aliases

Other spellings of this term, matched when a value is written through the field-value routes. On a term that isn’t archived they stand for this term; on a merged term they stand for wherever replaced_by leads; on a term archived without a merge they match nothing. Adding or removing one doesn’t change values already stored.

Array<string>
matched
required

How many terms matched, before limit was applied.

integer
returned
required

How many are in values. Never greater than limit.

integer
limit
required

The limit actually used, after clamping to 1-200.

integer
truncated
required

True when matched exceeded limit.

boolean
vocabulary_size
required

How many terms the vocabulary has, at every level and in every status, whatever the query. Useful for deciding whether loading the whole list is reasonable.

integer
open_vocabulary
required

Whether saving a value on this field can add new terms: true only for a multi_select field with open_vocabulary turned on.

boolean
can_extend
required

Whether you may add new terms to this field when saving a value: the field adds terms, and you hold fields.vocabulary.extend (system.admin also counts; fields.admin doesn’t). Use it to decide whether to offer a way to create a term. It doesn’t say whether you may edit a particular asset or collection.

boolean

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed