# 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). **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`. | | `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. | | `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`. | | `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`. | ## 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.opendatadiscovery.org/developer-guides/api-reference/glossary.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.