Glossaries API

This guide walks you through the process of using Glossaries via the Palabra API. Glossaries let you define how the Speech-to-Speech Translation API recognizes and translates specific words or phrases. This is especially useful for ensuring consistent and accurate translations of professional, technical, or brand-specific terminology when integrating Palabra into your own applications or workflows.

Overview

To use glossaries, get a Palabra API Key and create a glossary metadata instance of the type you need. Then prepare your CSV file and upload it to that glossary. That's it — no further setup required: once uploaded, active glossaries are automatically applied to every relevant STS and ASR pipeline in your account.

You can also manage your existing glossaries at any time: retrieve them, download their CSV content, disable or edit them, or delete the ones you no longer need.

Endpoint reference

All endpoints are relative to https://api.palabra.ai.

Method	Endpoint	Purpose
`POST`	`/saas/glossary`	Submit glossary metadata and get a `glossary_id` for the next step
`POST`	`/saas/glossary/{glossary_id}/upload`	Upload a glossary's CSV file (attach a glossary content to the metadata instance)
`GET`	`/saas/glossaries`	List all glossaries
`GET`	`/saas/glossary/{glossary_id}/upload`	Retrieve a glossary's CSV file
`POST`	`/saas/glossary/{glossary_id}`	Update a glossary's name or status
`DELETE`	`/saas/glossary/{glossary_id}`	Delete a glossary

Prerequisites: Get an API Key

Log in to the Palabra Platform
Go to the API Keys page
Create a new API Key or use an existing one — you'll need it to authenticate requests (Authorization: Bearer <API_KEY> header)

Preparing your glossary file

Requirements for a glossary file:

Accepted formats: CSV
Maximum file size: 1 MB

The required file format depends on the Glossary Type:

Glossary	`glossary_type`	File format	Supported APIs
Translation	`translation`	Two words or phrases per row, separated by a comma — first the term in the Source Language, followed by the term in the Target Language.	STS
Validation	`asr`	Two words or phrases per row, separated by a comma — both terms in the Source Language.	STS, ASR
Recognition	`asr_hot`	One word per row (Source Language).	STS

Pay attention: Recognition glossaries (asr_hot) only work with the Speech-to-Speech API. They are not supported by the Speech-to-Text API.

Submitting glossary metadata

Glossary creation happens in two requests:

The client sends a POST request with the glossary metadata. The server creates the glossary entry and returns a glossary_id.
The client sends a POST request to upload the CSV file for that glossary.

This section covers the first request. At this stage, you do not upload the CSV file itself — only its metadata is submitted.

Endpoint

https://api.palabra.ai/saas/glossary

Sample payload

{
  "name": "Glossary#2",
  "is_enabled": true,
  "glossary_type": "translation",
  "source_lang": "en",
  "target_lang": "fr"
}

Field descriptions

Field	Required	Description
`name`	Required	A user-defined name for the glossary. This name will appear in your Palabra dashboard and help you identify the glossary later.
`is_enabled`	Required	Whether the glossary is active: `true` enables it for use by the API, `false` saves it without activating.
`glossary_type`	Required	Type of glossary to create — `translation`, `asr`, or `asr_hot`. Determines how terms are formatted and interpreted; see the glossary type table above for details.
`source_lang`	Required	The language code for the source language of the glossary (e.g., `en`, `fr`, `bg`). Used to interpret input terms.
`target_lang`	Conditionally required	The language code for the target language, required only if `glossary_type` is `translation`. Ignored for `asr` and `asr_hot`.

Note: The name, is_enabled, glossary_type, and source_lang fields are required. target_lang is required only when glossary_type is translation.

Example: Glossary creation request

fetch('https://api.palabra.ai/saas/glossary', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>'
  },
  body: JSON.stringify({
    data: {
      name: 'Glossary#2',
      is_enabled: true,
      glossary_type: 'translation',
      source_lang: 'en',
      target_lang: 'fr'
    }
  })
})
  .then(response => response.json())
  .catch(error => {
    console.error('Error creating glossary:', error);
  });

Response

{
    "glossary_id": "62edf6b3-458a-4bed-ab6e-e0b257bb4471",
    "user_id": "02117a4f-a847-4264-9807-704d279bbf3a",
    "name": "Glossary#2",
    "is_enabled": true,
    "glossary_type": "translation",
    "source_lang": "en",
    "target_lang": "fr",
    "utc_created_at": "2025-06-23T11:30:44.445612"
}

Uploading a glossary file

Once you have a glossary_id from the previous step, upload your CSV file with a POST request to the following endpoint:

https://api.palabra.ai/saas/glossary/${id}/upload

const formData = new FormData();
formData.append('file', file);

fetch('https://api.palabra.ai/saas/glossary/62edf6b3-458a-4bed-ab6e-e0b257bb4471/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>'
  },
  body: formData
})
  .then(response => response.json())
  .catch(error => {
    console.error('Upload error:', error);
  });

Using glossaries

After you upload the file, the glossary is ready to use. All active glossaries are automatically applied to every relevant Speech-to-Speech Translation and Speech-to-Text pipeline in your Palabra account — no extra setup needed. Which pipelines a glossary applies to depends on its type: Translation and Validation glossaries work with both APIs, while Recognition glossaries only work with Speech-to-Speech (see the glossary type table above).

Retrieving glossaries list

Retrieve all glossaries created under your account.

Endpoint

GET https://api.palabra.ai/saas/glossaries

Query parameters

Parameter	Required	Description
`sort`	Optional	Sort order: `asc` or `desc`.
`page_size`	Optional	Number of items per page, from `1` to `100`.
`token`	Optional	Pagination token for retrieving the next page. Cannot be combined with `sort` or `page_size`.

Example: Retrieve glossaries request

fetch('https://api.palabra.ai/saas/glossaries?sort=desc&page_size=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>'
  }
})
  .then(response => response.json())
  .catch(error => {
    console.error('Error retrieving glossaries:', error);
  });

Response

{
    "ok": true,
    "data": {
        "items": [
            {
                "glossary_id": "62edf6b3-458a-4bed-ab6e-e0b257bb4471",
                "user_id": "02117a4f-a847-4264-9807-704d279bbf3a",
                "name": "Glossary#2",
                "is_enabled": true,
                "glossary_type": "translation",
                "source_lang": "en",
                "target_lang": "fr",
                "utc_created_at": "2025-06-23T11:30:44.445612",
                "utc_updated_at": "2025-06-23T11:30:44.445612"
            }
        ],
        "page_size": 10,
        "count": 1,
        "next": null
    }
}

Retrieving a glossary file

Download the CSV file that was uploaded for a glossary using its glossary_id.

Endpoint

GET https://api.palabra.ai/saas/glossary/{glossary_id}/upload

Unlike the other glossary endpoints, this one doesn't return JSON — the response body is the raw CSV file (Content-Type: text/csv).

Example: Retrieve glossary file request

fetch('https://api.palabra.ai/saas/glossary/62edf6b3-458a-4bed-ab6e-e0b257bb4471/upload', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>'
  }
})
  .then(response => response.text())
  .then(csv => {
    console.info(csv);
  })
  .catch(error => {
    console.error('Error retrieving glossary file:', error);
  });

Response

term_source,term_target
hello,bonjour
goodbye,au revoir

Editing and disabling glossaries

You can update a glossary's name or is_enabled status at any time using its glossary_id.

Endpoint

POST https://api.palabra.ai/saas/glossary/{glossary_id}

Sample payload

{
  "data": {
    "name": "Glossary#2 updated",
    "is_enabled": false
  }
}

Field descriptions

Field	Required	Description
`name`	Required	Updated glossary name.
`is_enabled`	Required	Updated glossary status — same semantics as during creation: `true` activates the glossary, `false` deactivates it.

All active (is_enabled: true) glossaries are applied by default to every translation pipeline in your account. To temporarily deactivate a glossary without deleting it, update it with is_enabled: false.

This endpoint only updates the glossary's name and is_enabled fields — it doesn't let you change the glossary's content (the terms themselves). To change a glossary's content, delete it and create a new one with the updated CSV file.

Example: Update glossary request

fetch('https://api.palabra.ai/saas/glossary/62edf6b3-458a-4bed-ab6e-e0b257bb4471', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      name: 'Glossary#2 updated',
      is_enabled: false
    }
  })
})
  .then(response => response.json())
  .catch(error => {
    console.error('Error updating glossary:', error);
  });

Response

{
    "ok": true,
    "data": {
        "glossary_id": "62edf6b3-458a-4bed-ab6e-e0b257bb4471",
        "user_id": "02117a4f-a847-4264-9807-704d279bbf3a",
        "name": "Glossary#2 updated",
        "is_enabled": false,
        "glossary_type": "translation",
        "source_lang": "en",
        "target_lang": "fr",
        "utc_created_at": "2025-06-23T11:30:44.445612",
        "utc_updated_at": "2025-06-24T09:12:03.221190"
    }
}

Deleting glossaries

Deleting a glossary permanently removes it along with its uploaded file. This action is irreversible.

Endpoint

DELETE https://api.palabra.ai/saas/glossary/{glossary_id}

Example: Delete glossary request

fetch('https://api.palabra.ai/saas/glossary/62edf6b3-458a-4bed-ab6e-e0b257bb4471', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>'
  }
})
  .then(response => response.json())
  .catch(error => {
    console.error('Error deleting glossary:', error);
  });

Response

{
    "ok": true,
    "data": {
        "glossary_id": "62edf6b3-458a-4bed-ab6e-e0b257bb4471"
    }
}