Glossary

Business Glossary HTTP endpoints — term CRUD + lookup, term-side and resource-side linkage, faceted search, ownership and tags.

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 page under Data Glossary.

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.

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.

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.

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.

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).
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.

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).
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.

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).
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).

See also

• API Reference hub — the full per-feature index.

• Business Glossary — feature description, term creation flow, term-to-term linking.