> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/developer-guides/api-reference/glossary.md). # Glossary The Business Glossary surface — `Glossary` and `Terms` are registered aliases on `main-concepts.md` "Terms & Aliases" — is exposed under `/api/terms/` plus a small set of linkage endpoints owned by the data-entity and dataset-field controllers. The endpoints below back the in-app `Dictionary` tab and the Term-to-\* linking workflows. For the term creation flow, the description-text vs direct-link distinction, and the user-side walkthrough, see the [Business Glossary](/features/data-glossary/business-glossary.md) page under [Data Glossary](/features/data-glossary.md). ## Authentication and authorization caveats Several glossary write endpoints do not gate the way an operator reasoning from the permission catalog would expect. Read these before authoring separation-of-duties roles — each lets a holder of a narrow `TERM_*` permission perform an action that looks like it should require a different, dedicated permission. {% hint style="warning" %} **Creating or updating a term auto-creates its namespace without `NAMESPACE_CREATE`.** Both `createTerm` (`POST /api/terms`, gated by `TERM_CREATE`) and `updateTerm` (`PUT /api/terms/{term_id}`, gated by `TERM_UPDATE`) call the namespace service's get-or-create on the submitted namespace name. A caller who holds only `TERM_CREATE` or `TERM_UPDATE` — and explicitly not `NAMESPACE_CREATE` — can mint a brand-new platform-wide namespace just by typing a novel name into the term form. If you separate namespace administration from term authoring, this path bypasses that separation. {% endhint %} {% hint style="warning" %} **Replacing a term's tags auto-creates any missing tags without `TAG_CREATE`.** `createTermTagsRelations` (`PUT /api/terms/{term_id}/tags`, gated by `TERM_TAGS_UPDATE`) calls the tag service's get-or-create for every name in the submitted list. A caller who holds only `TERM_TAGS_UPDATE` — and not `TAG_CREATE` — can mint new platform-wide tags through this endpoint. The tag directory accretes silently; the dedicated tag-creation permission does not gate this path. {% endhint %} {% hint style="danger" %} **The `DATA_ENTITY_ADD_TERM` / `DATA_ENTITY_DELETE_TERM` gates on the term-to-entity link endpoints never fire — those endpoints are open to any authenticated user.** The security-rule registry binds the two permissions to the **singular** paths `/api/dataentities/{id}/term` and `/api/dataentities/{id}/term/{term_id}`, while the endpoints the contract and this page expose are the **plural** `/api/dataentities/{id}/terms` (`addDataEntityTerm`) and `/api/dataentities/{id}/terms/{term_id}` (`deleteTermFromDataEntity`). The path-matcher never matches, so the requests fall through to the global "any authenticated user" rule. The direct term-to-term link endpoints (`POST`/`DELETE /api/terms/{term_id}/term`) have no security rule registered at all and are likewise open to any authenticated user. Do not rely on `DATA_ENTITY_ADD_TERM` / `DATA_ENTITY_DELETE_TERM` for separation-of-duties on term linkage until the platform-side path fix lands. {% endhint %} **Term CRUD and lookup** | Method | Path | Operation ID | Purpose | | -------- | ---------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/terms` | `getTermsList` | Paginated list of terms. Optional `query` (free-text), `updated_at_range_start_date_time`, and `updated_at_range_end_date_time` filters. | | `POST` | `/api/terms` | `createTerm` | Create a new term. Body: `TermFormData` (name, namespace, description). Returns `TermDetails`. Gated by `TERM_CREATE`; auto-creates the namespace without `NAMESPACE_CREATE` (see [caveats](#authentication-and-authorization-caveats)). | | `GET` | `/api/terms/{term_id}` | `getTermDetails` | Get full term details (metadata, ownership, tags, link counts). | | `PUT` | `/api/terms/{term_id}` | `updateTerm` | Update an existing term. Body: `TermFormData`. Returns the updated `TermDetails`. | | `DELETE` | `/api/terms/{term_id}` | `deleteTerm` | Delete a term. | | `GET` | `/api/terms/namespaces/{namespace_name}/names/{term_name}` | `getTermByNamespaceAndName` | Resolve a term by its namespace and name (the natural-key lookup form). Returns `TermRef`. | **Term-side linkage — read and write from a term** The first three endpoints read the entities, columns, and other terms linked to a given term. The last two are the term-to-term linking writes — for the user-facing description of the two link modes (description-text mentions vs direct links), see [Business Glossary → Term-to-term linking](/features/data-glossary/business-glossary.md#term-to-term-linking). | Method | Path | Operation ID | Purpose | | -------- | -------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/terms/{term_id}/linked_entities` | `getTermLinkedEntities` | Paginated list of data entities currently linked to the term. Optional `entity_class_id` filter. | | `GET` | `/api/terms/{term_id}/linked_columns` | `getTermLinkedColumns` | Paginated list of dataset fields (columns) linked to the term. | | `GET` | `/api/terms/{term_id}/linked_terms` | `getTermLinkedTerms` | Paginated list of other terms linked to this term (the term-to-term graph). | | `POST` | `/api/terms/{term_id}/term` | `addLinkedTermToTerm` | Create a direct term-to-term link. Body: `LinkedTermFormData` carrying the target term's id. Bi-directionally visible from either term. No RBAC permission is registered for this path — open to any authenticated user (see [caveats](#authentication-and-authorization-caveats)). | | `DELETE` | `/api/terms/{term_id}/term/{linked_term_id}` | `deleteLinkedTermFromTerm` | Remove a direct term-to-term link. | **Linkage from the linked resource's side** These four endpoints attach or detach a term from the perspective of the resource the term is being linked **to**. The dataset-field endpoints accept and return `LinkedTerm`. For term ↔ query-example linking, see [Query Examples → Per-entity / per-term lookup and linking](/developer-guides/api-reference/query-examples.md#per-entity--per-term-lookup-and-linking-6-endpoints). | Method | Path | Operation ID | Purpose | | -------- | ------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/dataentities/{data_entity_id}/terms` | `addDataEntityTerm` | Link a term to a data entity. Body: `DataEntityTermFormData`. Returns `LinkedTerm`. The `DATA_ENTITY_ADD_TERM` gate is registered on a different (singular) path and never fires — open to any authenticated user (see [caveats](#authentication-and-authorization-caveats)). | | `DELETE` | `/api/dataentities/{data_entity_id}/terms/{term_id}` | `deleteTermFromDataEntity` | Remove a term link from the data entity. | | `POST` | `/api/datasetfields/{dataset_field_id}/terms` | `addDatasetFieldTerm` | Link a term to a dataset field (column). Body: `DatasetFieldTermFormData`. Returns `LinkedTerm`. | | `DELETE` | `/api/datasetfields/{dataset_field_id}/terms/{term_id}` | `deleteTermFromDatasetField` | Remove a term link from the dataset field. | **Faceted search** The same multi-step facet flow the main catalog uses — start a search, then read / update / paginate against the resulting `search_id` (a UUID). | Method | Path | Operation ID | Purpose | | ------ | -------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/terms/search` | `termSearch` | Start a search. Body: `TermSearchFormData`. Returns `TermSearchFacetsData` carrying the `search_id` and initial facet aggregations. | | `GET` | `/api/terms/search/{search_id}` | `getTermSearchFacetList` | Re-read the current facets for a search. | | `PUT` | `/api/terms/search/{search_id}` | `updateTermSearchFacets` | Update the search query and re-aggregate facets. | | `GET` | `/api/terms/search/{search_id}/facet/{facet_type}` | `getTermFiltersForFacet` | Countable filter values for one facet (paginated, with optional `query`). `facet_type` is one of the `MultipleFacetType` enum values. | | `GET` | `/api/terms/search/{search_id}/results` | `getTermSearchResults` | Paginated result list for the search. | | `GET` | `/api/terms/search/suggestions?query=…` | `getTermSearchSuggestions` | Top-five matching term names for the search-input typeahead. | **Term ownership and tags** | Method | Path | Operation ID | Purpose | | -------- | ----------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/api/terms/{term_id}/ownership` | `createTermOwnership` | Add an ownership entry to the term. Body: `OwnershipFormData`. Returns `Ownership`. | | `PUT` | `/api/terms/{term_id}/ownership/{ownership_id}` | `updateTermOwnership` | Update an existing ownership (typically to change role). Body: `OwnershipUpdateFormData`. | | `DELETE` | `/api/terms/{term_id}/ownership/{ownership_id}` | `deleteTermOwnership` | Remove an ownership entry. | | `PUT` | `/api/terms/{term_id}/tags` | `createTermTagsRelations` | Replace the term's tag set. Body: `TagsFormData` (the full target list). Tags that don't yet exist on the platform are created. Returns the updated `TagList`. Gated by `TERM_TAGS_UPDATE`; auto-creates tags without `TAG_CREATE` (see [caveats](#authentication-and-authorization-caveats)). | ## See also * [API Reference hub](/developer-guides/api-reference.md) — the full per-feature index. * [Business Glossary](/features/data-glossary/business-glossary.md) — feature description, term creation flow, term-to-term linking.