# METADATA VOCABULARIES

Invoke the Controlled Vocabularies API to create, retrieve, update, and delete Controlled Vocabularies used to constrain the values available to a Metadata Attribute.

## (NEW!) List Controlled Vocabularies (Paginated)

 - [GET /metadata/vocabularies](https://api.tenovos.com/openapi/v1.5/metadata-vocabularies/listmetadatavocabularies.md): 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.

## Get Controlled Vocabularies

 - [GET /metadata/vocabulary](https://api.tenovos.com/openapi/v1.5/metadata-vocabularies/getallcontrolledvocab.md): Retrieve all the controlled vocabularies available to the current user.

In response, it will contain the list of metadata key/value pair and metadata definition attributes like id, name, type and search fields etc.

Average Response Time: 592ms

## Create Controlled Vocabulary

 - [POST /metadata/vocabulary](https://api.tenovos.com/openapi/v1.5/metadata-vocabularies/createcontrolledvocab.md): Create a Controlled Vocabulary. User must have permission to create a controlled vocabulary.

Response will contain the object of the metadata definition attributes, such as id, name, type and search fields, etc.

Average Response Time: 585ms

## Get Controlled Vocabulary

 - [GET /metadata/vocabulary/{id}](https://api.tenovos.com/openapi/v1.5/metadata-vocabularies/getcontrolledvocab.md): Retrieve the Controlled Vocabulary and its attributes by Controlled Vocabulary Id

In response, it will contain the list of metadata key/value pair and metadata definition attributes like id, name, type and search fields etc.

Average Response Time: 472ms

## Delete Controlled Vocabulary

 - [DELETE /metadata/vocabulary/{id}](https://api.tenovos.com/openapi/v1.5/metadata-vocabularies/deletecontrolledvocab.md): Delete a Controlled Vocabulary.

Average Response Time: 130ms

## Update Controlled Vocabulary

 - [PATCH /metadata/vocabulary/{id}](https://api.tenovos.com/openapi/v1.5/metadata-vocabularies/updatecontrolledvocab.md): Update a Controlled Vocabulary. User must have permission to update a controlled vocabulary.

In response, it will contain the object of metadata definition attributes like id, name, type and search fields etc.

Average Response Time: 1462ms (Add Controlled Vocabulary (CV) value)
Average Response Time: 716ms (Update a CV value )