# (NEW!) List Controlled Vocabularies (Paginated)

Retrieve a paginated, searchable list of controlled vocabularies for UI consumption. Response fields are lightweight by default (valueCount only); each vocabulary's values are returned per row via the include query parameter.

Defaults:
- sortField defaults to name.
- order defaults to asc.
- from defaults to 0.
- limit defaults to 100, maximum 100.
- includeSystem defaults to false.
- searchTerm, inUse, and include are unset by default, applying no filter.

Business Rules:
- searchTerm is a case-insensitive partial match on vocabulary name. It is trimmed before use, so a blank or whitespace-only value is treated as if omitted.
- order is matched case-insensitively — asc, ASC, and Asc are equivalent.
- limit above the maximum is silently capped, not rejected. limit=500 returns 100 results and no error. A limit below 1 or a non-integer limit is still rejected with a 400. This differs from GET /metadata/templates and GET /attributes, which reject an over-maximum limit with a 400.
- inUse accepts a boolean (true/false — aggregate: used anywhere at all) or one of metadataAttributes, metadataCascades, metadataTables, metadataGroups, metadataTemplates, filtering to vocabularies referenced in that specific usage category. Omitted applies no filter. inUse is also a valid sortField value.
- includeSystem defaults to false. When true, also returns platform-owned system vocabularies used internally by various platform functionalities, alongside user-created ones.
- include is a comma-separated list; values is currently the only accepted entry. Omitted returns summary fields only (valueCount); include=values adds values[] to each row. Unlike GET /metadata/cascades, include=values does not clamp limit.
- usedIn is shaped { metadataAttributes: [], metadataCascades: [], metadataTables: [], metadataGroups: [], metadataTemplates: [] }. A vocabulary's only direct reference is a dropdown attribute pointing at it, so metadataAttributes is the direct edge and the remaining categories are rollups through it. This shape is deliberately not the same as GET /attributes' usedIn, which carries a presets category and no metadataAttributes.

The user submitting the request must have the Metadata Template Management admin privilege.

Endpoint: GET /metadata/vocabularies
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

## Query parameters:

  - `searchTerm` (string)
    Case-insensitive partial match on vocabulary name. Trimmed before use — a blank or whitespace-only value is treated as if omitted.
    Example: "usage"

  - `inUse` (string)
    Filters by usage status. true/false filters on aggregate usage (referenced anywhere at all). One of metadataAttributes, metadataCascades, metadataTables, metadataGroups, metadataTemplates filters to vocabularies referenced in that specific usage category. Omitted applies no filter.
    Enum: "true", "false", "metadataAttributes", "metadataCascades", "metadataTables", "metadataGroups", "metadataTemplates"

  - `includeSystem` (boolean)
    When true, also returns platform-owned system vocabularies used internally by various platform functionalities, in addition to user-created ones. Defaults to false.

  - `from` (integer)
    Result offset from which to start. Must be an integer of 0 or greater. Defaults to 0.

  - `limit` (integer)
    Number of results to return per page. Defaults to 100, minimum 1, maximum 100. A value above 100 is silently capped at 100 rather than rejected — the request succeeds and returns at most 100 results. A value below 1, or a non-integer, is rejected with a 400.
    Example: 100

  - `sortField` (string)
    Field to sort results by. Defaults to name.
    Enum: "name", "createdEpoch", "lastUpdatedEpoch", "inUse", "valueCount"

  - `order` (string)
    Sort direction. Matched case-insensitively. Defaults to asc.
    Enum: "asc", "desc"

  - `include` (string)
    Comma-separated additional data to return per row. values is currently the only accepted entry, adding values[] to each result. Omitted returns summary fields only.
    Enum: "values"

## Response 200 fields (application/json):

  - `hitCount` (integer)
    Total number of vocabularies matching the search criteria.
    Example: 14

  - `results` (array)
    Array of vocabulary summary objects.

  - `results.id` (string)
    Unique ID of the vocabulary.
    Example: "34abed31-4546-4f15-ae07-3d22b9b056d5"

  - `results.name` (string)
    Display name of the vocabulary.
    Example: "Usage Mediums"

  - `results.searchField` (string)
    System-generated slug used for search indexing. Permanent once created.
    Example: "usage_mediums"

  - `results.type` (string,null)
    Vocabulary type. null when never set.
    Example: "controlledVocabulary"

  - `results.featured` (boolean,null)
    System-assigned. null if never set.

  - `results.valueCount` (integer)
    Number of values defined on the vocabulary. Always present, including when values[] is omitted.
    Example: 12

  - `results.values` (array)
    The vocabulary's values. Only present when the include query parameter contains values.

  - `results.values.id` (string)
    Value id.
    Example: "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74"

  - `results.values.name` (string)
    Display value.
    Example: "Digital"

  - `results.createdBy` (string,null)
    User-profile id of the vocabulary's creator. null for platform-owned vocabularies.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `results.createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1770714900000

  - `results.createdDate` (string,null)
    ISO 8601 creation date.
    Example: "2026-02-10T09:15:00Z"

  - `results.lastUpdatedBy` (string,null)
    User-profile id of the last user to update the vocabulary. null when never updated.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `results.lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1771432800000

  - `results.lastUpdatedDate` (string,null)
    ISO 8601 last-updated date.
    Example: "2026-02-18T16:40:00Z"

  - `results.inUse` (boolean)
    Derived from usedIn — true when any usedIn category is non-empty.
    Example: true

  - `results.usedIn` (object)
    Where the vocabulary is currently referenced.

  - `results.usedIn.metadataAttributes` (array)
    Attributes backed by this vocabulary. Empty array if none.

  - `results.usedIn.metadataAttributes.id` (string)
    Example: "99ff8765-aa11-bb22-cc33-dd44ee55ff66"

  - `results.usedIn.metadataAttributes.name` (string)
    Example: "Asset Category"

  - `results.usedIn.metadataCascades` (array)
    Cascades that reference this vocabulary. Empty array if none.

  - `results.usedIn.metadataTables` (array)
    Tables that reference this vocabulary. Empty array if none.

  - `results.usedIn.metadataGroups` (array)
    Groups that reference this vocabulary. Empty array if none.

  - `results.usedIn.metadataTemplates` (array)
    Templates that reference this vocabulary. Empty array if none.

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)