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