> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elanlanguages.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossaries

> On this page, we'll dive into the different glossary endpoints you can use to manage your company's 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

<ResponseField name="id" type="integer">
  Unique identifier for the glossary.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the glossary.
</ResponseField>

<ResponseField name="description" type="string">
  An optional description of the glossary.
</ResponseField>

<ResponseField name="base_language" type="string">
  The base language for the glossary. All glossary entries need to contain at
  least a term in the base language.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether or not the glossary is active and can be used.
</ResponseField>

<ResponseField name="updated_at" type="timestamp">
  Timestamp of when the glossary was last updated.
</ResponseField>

<ResponseField name="created_at" type="timestamp">
  Timestamp of when the glossary was created.
</ResponseField>

***

## 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

<ParamField query="limit" type="integer">
  Maximum number of glossaries to return (default: 50).
</ParamField>

<ParamField query="offset" type="integer">
  Number of glossaries to skip (default: 0).
</ParamField>

<ParamField query="is_active" type="boolean">
  Filter by active status.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.elanlanguages.ai/v1/glossaries \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}"
  ```
</CodeGroup>

```json Response theme={null}
{
  "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

<ParamField body="name" type="string" required>
  The name for the glossary.
</ParamField>

<ParamField body="base_language" type="string" required>
  The base language for the glossary.
</ParamField>

### Optional attributes

<ParamField body="description" type="string">
  A description for the glossary.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.elanlanguages.ai/v1/glossaries \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -d name="Standard Glossary" \
    -d base_language="en"
  ```
</CodeGroup>

```json Response theme={null}
{
  "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](#the-glossary-model) at the top of this page to see which properties are included with glossary objects.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.elanlanguages.ai/v1/glossaries/1 \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}"
  ```
</CodeGroup>

```json Response theme={null}
{
  "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

<ParamField body="name" type="string">
  The name for the glossary.
</ParamField>

<ParamField body="description" type="string">
  A description for the glossary.
</ParamField>

<ParamField body="base_language" type="string">
  The base language code for the glossary.
</ParamField>

<ParamField body="is_active" type="boolean">
  Whether or not the glossary is active and can be used.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.elanlanguages.ai/v1/glossaries/1 \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}"
  ```
</CodeGroup>

***

## 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](#import-to-existing-glossary).

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.elanlanguages.ai/v1/glossaries/1/download \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}"
  ```
</CodeGroup>

```text Response theme={null}
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

<ParamField body="file" type="file" required>
  The CSV file to import.
</ParamField>

<ParamField body="name" type="string" required>
  The name for the new glossary.
</ParamField>

### Optional form fields

<ParamField body="description" type="string">
  A description for the glossary.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

```json Response theme={null}
{
  "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

<ParamField body="file" type="file" required>
  The CSV file to import.
</ParamField>

### Optional form fields

<ParamField body="map_header" type="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"}]`.
</ParamField>

<ParamField body="options" type="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.
</ParamField>

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

```json Response theme={null}
{
  "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](#import-to-existing-glossary). If the base-language column cannot be located, the response includes a `warning`.

### Required form fields

<ParamField body="file" type="file" required>
  The CSV file to preview.
</ParamField>

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

```json Response theme={null}
{
  "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

<ParamField body="text" type="string" required>
  The text to analyze against the glossaries.
</ParamField>

<ParamField body="glossaries" type="array" required>
  A list of glossary IDs to analyze against.
</ParamField>

### Optional attributes

<ParamField body="source_language" type="string">
  Language code to filter glossary terms (e.g., `en`, `de`).
</ParamField>

<ParamField body="provider" type="string">
  The AI provider to use for analysis (one of `openai`, `anthropic`, `mistral`) (default: "openai").
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "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

<ParamField body="query" type="string" required>
  The search query to find matching terms.
</ParamField>

### Optional attributes

<ParamField body="limit" type="integer">
  Maximum number of results to return (default: 50, max: 100).
</ParamField>

<ParamField body="offset" type="integer">
  Number of results to skip for pagination (default: 0).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "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
}
```