Glossaries

Glossaries are a powerful tool to make sure your translations are consistent and accurate. On this page, we’ll dive into the different glossary endpoints you can use to manage glossaries programmatically. We’ll look at how to create, update, and delete glossaries.

The glossary model

The glossary model contains metadata about your glossaries, such as their name, description, and base language. It also contains a reference to the entries in the glossary and information about when the glossary was created and last updated.

Properties

integer

Unique identifier for the glossary.

string

The name of the glossary.

string

An optional description of the glossary.

string

The base language for the glossary. All glossary entries need to contain at least a term in the base language.

boolean

Whether or not the glossary is active and can be used.

timestamp

Timestamp of when the glossary was last updated.

timestamp

Timestamp of when the glossary was created.

List all glossaries

GET /v1/glossaries This endpoint allows you to retrieve a paginated list of all your glossaries. By default, a maximum of 50 glossaries are shown per page.

Optional parameters

integer

Maximum number of glossaries to return (default: 50).

integer

Number of glossaries to skip (default: 0).

boolean

Filter by active status.

curl -G https://api.elanlanguages.ai/v1/glossaries \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

{
  "glossaries": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "base_language": "string",
      "is_active": true,
      "created_at": "2025-12-09T10:30:29.114Z",
      "updated_at": "2025-12-09T10:30:29.114Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}

Create a glossary

POST /v1/glossaries This endpoint allows you to add a new glossary. To add a glossary, you must provide a name and base language.

Required attributes

string

required

The name for the glossary.

string

required

The base language for the glossary.

Optional attributes

string

A description for the glossary.

curl https://api.elanlanguages.ai/v1/glossaries \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -d name="Standard Glossary" \
  -d base_language="en"

Response

{
  "id": 1,
  "name": "Standard Glossary",
  "description": "",
  "base_language": "en",
  "is_active": true,
  "created_at": "2025-12-09T10:34:41.135Z",
  "updated_at": "2025-12-09T10:34:41.135Z"
}

Retrieve a glossary

GET /v1/glossaries/:glossary_id This endpoint allows you to retrieve a glossary by providing its id. Refer to the list at the top of this page to see which properties are included with glossary objects.

curl https://api.elanlanguages.ai/v1/glossaries/1 \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

{
  "id": 1,
  "name": "Standard Glossary",
  "description": "",
  "base_language": "en",
  "is_active": true,
  "created_at": "2025-12-09T10:34:41.135Z",
  "updated_at": "2025-12-09T10:34:41.135Z"
}

Update a glossary

PUT /v1/glossaries/:glossary_id This endpoint allows you to perform an update on a glossary. All attributes are optional - only include the fields you want to update.

Optional attributes

string

The name for the glossary.

string

A description for the glossary.

string

The base language code for the glossary.

boolean

Whether or not the glossary is active and can be used.

curl -X PUT https://api.elanlanguages.ai/v1/glossaries/1 \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Glossary",
    "description": "Standard Glossary for Acme Inc.",
    "is_active": false
  }'

Response

{
  "id": 1,
  "name": "Standard Glossary",
  "description": "Standard Glossary for Acme Inc.",
  "base_language": "en",
  "is_active": false,
  "created_at": "2025-12-09T10:39:04.329Z",
  "updated_at": "2025-12-09T10:39:04.329Z"
}

Delete a glossary

DELETE /v1/glossaries/:glossary_id This endpoint allows you to delete glossaries. Note: This will also delete all entries in this glossary.

curl -X DELETE https://api.elanlanguages.ai/v1/glossaries/1 \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Download a glossary as CSV

GET /v1/glossaries/:glossary_id/download This endpoint allows you to download a glossary as a CSV file. The header row contains the glossary’s base language, followed by the other languages (sorted) and a notes column. Each subsequent row is one glossary entry; only preferred terms are exported. The resulting file is safe to re-upload via the import endpoint.

curl https://api.elanlanguages.ai/v1/glossaries/1/download \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

en,de,fr,notes
car,Auto,voiture,Automotive term
house,Haus,maison,

Import glossary from CSV

POST /v1/glossaries/import This endpoint allows you to create a new glossary from a CSV file. The CSV format should have language codes in the first row and term translations in subsequent rows. The first column defines the new glossary’s base language.

CSV Format

First row: language codes (e.g., en, de, fr) with an optional notes column at the end
First column: base/primary language — this defines the glossary’s base language
Subsequent rows: term translations, with optional entry-level notes in the last column

Example CSV:

en,de,fr,notes
car,Auto,voiture,Automotive term
house,Haus,maison,

All imported terms default to ‘preferred’ term type.

Required form fields

file

required

The CSV file to import.

string

required

The name for the new glossary.

Optional form fields

string

A description for the glossary.

curl https://api.elanlanguages.ai/v1/glossaries/import \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -F "file=@glossary.csv" \
  -F "name=Technical Glossary" \
  -F "description=Technical terms for product documentation"

Response

{
  "glossary_id": 1,
  "glossary_name": "Technical Glossary",
  "entries_created": 150,
  "entries_updated": 0,
  "terms_created": 450,
  "terms_updated": 0,
  "entries_skipped": 0,
  "skipped_details": [],
  "languages": ["en", "de", "fr"]
}

Import to existing glossary

POST /v1/glossaries/:glossary_id/import This endpoint allows you to import entries from a CSV file into an existing glossary, with optional explicit header mapping and merge strategy. By default, the CSV format should match the glossary’s base language in the first column.

CSV Format

First row: language codes (e.g., en, de, fr) with an optional notes column at the end
First column: must match the glossary’s base language
Subsequent rows: term translations, with optional entry-level notes in the last column

Example CSV:

en,de,fr,notes
car,Auto,voiture,Automotive term
house,Haus,maison,

All imported terms default to ‘preferred’ term type. Duplicate base-language terms are skipped by default — use the options field to overwrite existing entries instead.

Required form fields

file

required

The CSV file to import.

Optional form fields

string

A JSON array that explicitly maps each CSV column to a language code or notes, e.g. [{"map_header": "English", "map_value": "en"}, {"map_header": "Comments", "map_value": "notes"}].

string

A JSON object with merge options, e.g. {"overwrite": true, "notes_overwrite": true}. Set overwrite to true to update existing entries’ terms (and create missing-language terms); set notes_overwrite to true to replace existing notes when a row provides non-empty notes.

curl https://api.elanlanguages.ai/v1/glossaries/1/import \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -F "file=@additional-terms.csv"

Response

{
  "glossary_id": 1,
  "glossary_name": "Technical Glossary",
  "entries_created": 25,
  "entries_updated": 0,
  "terms_created": 75,
  "terms_updated": 0,
  "entries_skipped": 5,
  "skipped_details": [],
  "languages": ["en", "de", "fr"]
}

Preview a glossary import

POST /v1/glossaries/:glossary_id/import/preview This endpoint allows you to preview a CSV import without writing anything to the glossary. It parses the uploaded file and returns the raw headers, a suggested column mapping with a confidence level (one of high, medium, low), sample rows, and aggregate stats (new vs. duplicate base terms, in-file duplicates, empty rows). Use it to build a column-mapping step or an import summary before committing via the import endpoint. If the base-language column cannot be located, the response includes a warning.

Required form fields

file

required

The CSV file to preview.

curl https://api.elanlanguages.ai/v1/glossaries/1/import/preview \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -F "file=@additional-terms.csv"

Response

{
  "raw_headers": ["en", "de", "fr", "notes"],
  "suggested_mapping": [
    { "map_header": "en", "map_value": "en", "confidence": "high" },
    { "map_header": "de", "map_value": "de", "confidence": "high" },
    { "map_header": "fr", "map_value": "fr", "confidence": "high" },
    { "map_header": "notes", "map_value": "notes", "confidence": "high" }
  ],
  "sample_rows": [
    ["car", "Auto", "voiture", "Automotive term"],
    ["house", "Haus", "maison", ""]
  ],
  "total_rows": 24,
  "stats": {
    "new_terms": 20,
    "duplicate_terms": 3,
    "duplicate_in_file": 1,
    "empty_rows": 1,
    "rows_missing_base_lang": 0
  },
  "detected_encoding": "utf-8",
  "glossary_base_language": "en"
}

Analyze text against glossaries

POST /v1/glossaries/analyze This endpoint allows you to analyze text against multiple glossaries using AI to find matches and violations. It returns matches (glossary terms correctly used in the text) and violations (forbidden terms used, preferred terms not used, etc.).

Required attributes

string

required

The text to analyze against the glossaries.

array

required

A list of glossary IDs to analyze against.

Optional attributes

string

Language code to filter glossary terms (e.g., en, de).

string

The AI provider to use for analysis (one of openai, anthropic, mistral) (default: “openai”).

curl -X POST https://api.elanlanguages.ai/v1/glossaries/analyze \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The API provides a programming interface for developers.",
    "glossaries": [1],
    "source_language": "en",
    "provider": "openai"
  }'

Response

{
  "matches": [
    {
      "entry_id": 1,
      "term": "API",
      "lang": "en",
      "term_type": "preferred",
      "found_text": "API",
      "match_type": "direct"
    }
  ],
  "violations": [
    {
      "entry_id": 1,
      "term": "Interface",
      "lang": "en",
      "term_type": "forbidden",
      "violation_type": "forbidden_term_used",
      "found_text": "programming interface",
      "suggested_replacement": "API"
    }
  ],
  "analyzed_text": "The API provides a programming interface for developers.",
  "glossaries": [1]
}

Search glossary terms

POST /v1/glossaries/search This endpoint allows you to search for terms across all glossaries in your organization. Returns partial matches across all languages and glossaries with context.

Required attributes

string

required

The search query to find matching terms.

Optional attributes

integer

Maximum number of results to return (default: 50, max: 100).

integer

Number of results to skip for pagination (default: 0).

curl -X POST https://api.elanlanguages.ai/v1/glossaries/search \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "interface",
    "limit": 10,
    "offset": 0
  }'

Response

{
  "results": [
    {
      "term_id": 1,
      "term": "API",
      "lang": "en",
      "description": "Application Programming Interface",
      "term_type": "preferred",
      "glossary_id": 1,
      "glossary_name": "Technical Glossary",
      "entry_id": 1
    },
    {
      "term_id": 3,
      "term": "Interface",
      "lang": "en",
      "description": "An alternative term",
      "term_type": "forbidden",
      "glossary_id": 1,
      "glossary_name": "Technical Glossary",
      "entry_id": 1
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

Guides

Jobs & Translation

Resources

Webhooks

Account

The glossary model

Properties

List all glossaries

Optional parameters

Create a glossary

Required attributes

Optional attributes

Retrieve a glossary

Update a glossary

Optional attributes

Delete a glossary

Download a glossary as CSV

Import glossary from CSV

CSV Format

Required form fields

Optional form fields

Import to existing glossary

CSV Format

Required form fields

Optional form fields

Preview a glossary import

Required form fields

Analyze text against glossaries

Required attributes

Optional attributes

Search glossary terms

Required attributes

Optional attributes

​The glossary model

​Properties

​List all glossaries

​Optional parameters

​Create a glossary

​Required attributes

​Optional attributes

​Retrieve a glossary

​Update a glossary

​Optional attributes

​Delete a glossary

​Download a glossary as CSV

​Import glossary from CSV

​CSV Format

​Required form fields

​Optional form fields

​Import to existing glossary

​CSV Format

​Required form fields

​Optional form fields

​Preview a glossary import

​Required form fields

​Analyze text against glossaries

​Required attributes

​Optional attributes

​Search glossary terms

​Required attributes

​Optional attributes

The glossary model

Properties

List all glossaries

Optional parameters

Create a glossary

Required attributes

Optional attributes

Retrieve a glossary

Update a glossary

Optional attributes

Delete a glossary

Download a glossary as CSV

Import glossary from CSV

CSV Format

Required form fields

Optional form fields

Import to existing glossary

CSV Format

Required form fields

Optional form fields

Preview a glossary import

Required form fields

Analyze text against glossaries

Required attributes

Optional attributes

Search glossary terms

Required attributes

Optional attributes