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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The field definition’s id.
Query Parameters
Section titled “Query Parameters ”The text to match. Leave it out or empty to list terms in label order. The 200-character limit shown isn’t checked.
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.
Maximum number of terms to return. Values below 1 or above 200 are clamped, not refused. matched in the response gives the full count.
Which terms to include: active (the default), deprecated,
archived or any. Pickers should offer only active terms. Any
other value is treated as active.
Responses
Section titled “ Responses ”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
The matching terms, best matches first.
One vocabulary term.
object
The term’s slug, which is what records store. Unique across the field’s whole vocabulary.
Display text. The slug when the term has no label of its own.
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.
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.
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.
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.
How many terms matched, before limit was applied.
How many are in values. Never greater than limit.
The limit actually used, after clamping to 1-200.
True when matched exceeded limit.
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.
Whether saving a value on this field can add new terms: true only for a multi_select field with open_vocabulary turned on.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed