Glossaries API

The Glossaries API lets you manage terminology databases for your organization. Glossaries enforce consistent translation of brand names, technical terms, and product-specific vocabulary across all your projects.

Tip

Glossaries work at the organization level and can be shared across all projects. They integrate with Comvi’s QA checks to automatically flag incorrect terminology usage.

---

Term types

Each term in a glossary has a type that controls how it is handled:

Type	Description
preferred	The recommended translation for this term
admitted	An acceptable alternative translation
deprecated	An outdated term that should be replaced
forbidden	A term that must not be used in translations

---

List glossaries

Returns all glossaries in an organization.

GET /api/v1/organizations/:orgId/glossaries

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1/glossaries

Example response

[
  {
    "id": 1,
    "organizationId": 1,
    "sourceLocaleId": 10,
    "name": "Product Terminology",
    "description": "Official product names and technical terms",
    "isDefault": true,
    "type": "organization",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-03-20T14:00:00Z"
  }
]

Response fields

Field	Type	Description
id	integer	Glossary ID
organizationId	integer	Organization this glossary belongs to
sourceLocaleId	integer	Source language locale ID
name	string	Glossary name
description	string | null	Optional description
isDefault	boolean	Whether this is the default glossary for the organization
type	string	"organization" or "project" scope
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

---

Create glossary

Create a new terminology glossary in an organization.

POST /api/v1/organizations/:orgId/glossaries

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID

Request body

Field	Type	Required	Description
name	string	Yes	Glossary name
description	string	No	Optional description
sourceLocaleId	integer	Yes	Source language locale ID

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal Terms",
    "description": "Legal and compliance terminology",
    "sourceLocaleId": 10
  }' \
  https://api.comvi.io/api/v1/organizations/1/glossaries

Example response

{
  "id": 2,
  "organizationId": 1,
  "sourceLocaleId": 10,
  "name": "Legal Terms",
  "description": "Legal and compliance terminology",
  "isDefault": false,
  "type": "organization",
  "createdAt": "2025-03-25T12:00:00Z",
  "updatedAt": "2025-03-25T12:00:00Z"
}

---

Get glossary

Retrieve a single glossary by ID.

GET /api/v1/organizations/:orgId/glossaries/:glossaryId

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID
glossaryId	integer	Yes	Glossary ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1/glossaries/1

Example response

Returns the same glossary object format as the Create glossary response.

---

Update glossary

Update a glossary’s name or description.

PATCH /api/v1/organizations/:orgId/glossaries/:glossaryId

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID
glossaryId	integer	Yes	Glossary ID

Request body

Field	Type	Required	Description
name	string	No	Updated name
description	string	No	Updated description

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Terminology v2"}' \
  https://api.comvi.io/api/v1/organizations/1/glossaries/1

Response

Returns the updated glossary object.

---

Delete glossary

Permanently delete a glossary and all of its terms.

DELETE /api/v1/organizations/:orgId/glossaries/:glossaryId

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID
glossaryId	integer	Yes	Glossary ID

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1/glossaries/1

Response

Returns 204 No Content on success.

---

List terms

Returns paginated terms in a glossary, including their translations.

GET /api/v1/organizations/:orgId/glossaries/:glossaryId/terms

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID
glossaryId	integer	Yes	Glossary ID

Query parameters

Parameter	Type	Required	Description
cursor	string	No	Pagination cursor from a previous response
limit	integer	No	Items per page (1-100, default: 50)
search	string	No	Search terms by text (max 255 characters)
termType	string	No	Filter by type: preferred, admitted, deprecated, forbidden

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  "https://api.comvi.io/api/v1/organizations/1/glossaries/1/terms?search=dashboard&limit=10"

Example response

{
  "terms": [
    {
      "id": 101,
      "conceptId": 50,
      "term": "Dashboard",
      "definition": "The main overview page of the application",
      "termType": "preferred",
      "partOfSpeech": "noun",
      "gender": null,
      "isCaseSensitive": true,
      "isTranslatable": true,
      "translations": [
        {
          "id": 201,
          "localeId": 11,
          "localeCode": "fr",
          "localeName": "French",
          "text": "Tableau de bord",
          "termType": "preferred"
        },
        {
          "id": 202,
          "localeId": 12,
          "localeCode": "de",
          "localeName": "German",
          "text": "Dashboard",
          "termType": "preferred"
        }
      ],
      "createdAt": "2025-02-01T10:00:00Z",
      "updatedAt": "2025-03-15T14:00:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6MTAxfQ==",
  "hasMore": true
}

Term fields

Field	Type	Description
id	integer	Term ID
conceptId	integer	Parent concept ID (groups related terms)
term	string	Source text of the term
definition	string | null	Explanation of the term’s meaning
termType	string	preferred, admitted, deprecated, or forbidden
partOfSpeech	string | null	Grammatical category (e.g., noun, verb)
gender	string | null	Grammatical gender
isCaseSensitive	boolean	Whether QA checks enforce exact case matching
isTranslatable	boolean	If false, the term should stay untranslated
translations	array	Translations of this term in target languages
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

---

Create term

Add a new term to a glossary.

POST /api/v1/organizations/:orgId/glossaries/:glossaryId/terms

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID
glossaryId	integer	Yes	Glossary ID

Request body

Field	Type	Required	Description
term	string	Yes	Source text (1-500 characters)
definition	string	No	Term definition (up to 2000 characters)
termType	string	No	preferred (default), admitted, deprecated, forbidden
partOfSpeech	string	No	Grammatical category (up to 50 characters)
gender	string	No	Grammatical gender (up to 20 characters)
isCaseSensitive	boolean	No	Enforce case matching in QA (default: false)
isTranslatable	boolean	No	Whether the term should be translated (default: true)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "term": "Comvi",
    "definition": "The product name, should never be translated",
    "termType": "preferred",
    "isCaseSensitive": true,
    "isTranslatable": false
  }' \
  https://api.comvi.io/api/v1/organizations/1/glossaries/1/terms

Example response

{
  "id": 102,
  "conceptId": 51,
  "term": "Comvi",
  "definition": "The product name, should never be translated",
  "termType": "preferred",
  "partOfSpeech": null,
  "gender": null,
  "isCaseSensitive": true,
  "isTranslatable": false,
  "translations": [],
  "createdAt": "2025-03-25T12:00:00Z",
  "updatedAt": "2025-03-25T12:00:00Z"
}

---

Add term translation

Add a translation for a term in a target language.

POST /api/v1/organizations/:orgId/glossaries/:glossaryId/terms/:termId/translations

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID
glossaryId	integer	Yes	Glossary ID
termId	integer	Yes	Term ID

Request body

Field	Type	Required	Description
localeId	integer	Yes	Target language locale ID
text	string	Yes	Translated text (1-1000 characters)
termType	string	No	Term type for this translation (preferred, admitted, deprecated, forbidden)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "localeId": 11,
    "text": "Tableau de bord",
    "termType": "preferred"
  }' \
  https://api.comvi.io/api/v1/organizations/1/glossaries/1/terms/101/translations

---

Errors

Status	Error Code	Description
403	FORBIDDEN	Missing glossary management permission
404	NOT_FOUND	Glossary or term not found
400	VALIDATION_ERROR	Invalid input (e.g., term text too long)

---

Next Steps

Glossaries in the Platform Manage glossaries from the dashboard.

Translation Memory API Leverage previous translations for consistency.

Machine Translation API Use glossaries with machine translation.

Translations API Manage translation keys and values.