Dictionaries

Custom dictionaries let you control how the TTS pipeline pronounces specific words. Each dictionary is scoped to a project and contains word → replacement/IPA mappings that are applied before synthesis. Use these endpoints to sync dictionaries from your own data sources (PIM, CMS, internal glossary). The TTS-side cache is invalidated after every mutation, so the next synthesis request picks up your changes immediately.

Authentication uses your project-scoped API key. Master-key callers must supply ?project_id=<id> on every request because the master key is not pinned to a project.

Common Request Fields

Field	Location	Type	Applies to	Description
`project_id`	query	integer	Every endpoint on this page	Required for master-key callers. Optional for project-scoped keys; if supplied, it must match the key’s project.
`dict_id`	path	integer	Single-dictionary and entry endpoints	Dictionary ID returned by list or create.
`entry_id`	path	integer	Update/delete entry	Entry ID returned by list or add.

The project_id query parameter is omitted from the examples because ordinary Dashboard API keys are already project-scoped.

Response Objects

Dictionary responses contain:

Field	Type	Description
`id`	integer	Dictionary ID
`project_id`	integer	Owning project ID
`name`	string	Display name
`description`	string \| null	Optional description
`language`	string \| null	Optional BCP-47 language filter
`is_active`	boolean	Whether the dictionary applies by default
`created_at`	string	Creation timestamp
`updated_at`	string	Last-update timestamp

Entry responses contain:

Field	Type	Description
`id`	integer	Entry ID
`dictionary_id`	integer	Parent dictionary ID
`word`	string	Source text to match
`replacement`	string	Replacement text sent to synthesis
`ipa`	string \| null	Optional IPA transcription
`case_sensitive`	boolean	Whether matching preserves case
`created_at`	string	Creation timestamp
`updated_at`	string	Last-update timestamp

Wrapper responses contain:

Operation	Fields
List dictionaries	`dictionaries` (array of dictionary objects)
List entries	`entries` (array), `total` (integer before pagination), `limit` (integer), `offset` (integer)
Bulk replace	`upserted` (integer), `deleted` (integer), `total` (integer; resulting payload size)
Delete dictionary/entry	`deleted` (boolean, always `true` on a successful response)

List Dictionaries

Return every dictionary in the caller’s project.

Query Parameters

integer

Required for master-key callers; rejected for project-scoped keys whose value disagrees with the key’s project.

Response

{
  "dictionaries": [
    {
      "id": 1,
      "project_id": 42,
      "name": "Brand names",
      "description": "Customer product names",
      "language": "en",
      "is_active": true,
      "created_at": "2026-05-20T09:00:00+00:00",
      "updated_at": "2026-05-20T09:05:00+00:00"
    }
  ]
}

Example

curl -X GET "https://api.kugelaudio.com/v1/dictionaries" \
  -H "Authorization: Bearer YOUR_API_KEY"

from kugelaudio import KugelAudio

client = KugelAudio(api_key="YOUR_API_KEY")
for d in client.dictionaries.list():
    print(f"{d.id}: {d.name} ({d.language})")

import { KugelAudio } from 'kugelaudio';

const client = new KugelAudio({ apiKey: 'YOUR_API_KEY' });
const dictionaries = await client.dictionaries.list();
for (const d of dictionaries) {
  console.log(`${d.id}: ${d.name} (${d.language})`);
}

KugelAudio client = KugelAudio.fromEnv();
for (Dictionary d : client.dictionaries().list()) {
    System.out.println(d.getId() + ": " + d.getName());
}

Create Dictionary

Body

string

required

Display name (1-200 characters). Must be unique within the project.

string

Free-form description (maximum 2000 characters). Omit or send an empty string for no description.

string

BCP-47 language tag (en, de-DE, …), maximum 16 characters. Omit or send an empty string for all languages.

Example

curl -X POST "https://api.kugelaudio.com/v1/dictionaries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Brand names", "language": "en"}'

d = client.dictionaries.create(name="Brand names", language="en")
print(d.id)

const d = await client.dictionaries.create({ name: 'Brand names', language: 'en' });
console.log(d.id);

Dictionary d = client.dictionaries().create("Brand names", null, "en");
System.out.println(d.getId());

Get Dictionary

Returns the dictionary record. Returns 403 Forbidden if the dictionary belongs to a project your API key is not scoped to.

Update Dictionary

Only the provided fields are changed.

Body

string

New name (1-200 characters).

string

New description (maximum 2000 characters). Send an empty string to clear it; null leaves it unchanged.

string

New language tag (maximum 16 characters). Send an empty string to clear it; null leaves it unchanged.

boolean

Disable a dictionary without deleting it.

Example

curl -X PATCH "https://api.kugelaudio.com/v1/dictionaries/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

client.dictionaries.update(1, is_active=False)

await client.dictionaries.update(1, { isActive: false });

client.dictionaries().update(1, null, null, null, false);

Delete Dictionary

Deletes the dictionary and all its entries.

Response

{ "deleted": true }

List Entries

Query Parameters

string

Case-insensitive substring filter on word.

integer

default:"100"

Page size, 1-500.

integer

default:"0"

Pagination offset.

Response

{
  "entries": [
    {
      "id": 11,
      "dictionary_id": 1,
      "word": "Postgres",
      "replacement": "post-gres",
      "ipa": null,
      "case_sensitive": false,
      "created_at": "2026-05-20T09:00:00+00:00",
      "updated_at": "2026-05-20T09:00:00+00:00"
    }
  ],
  "total": 12,
  "limit": 100,
  "offset": 0
}

Add Entry

Body

string

required

Word to match (≤ 200 chars).

string

required

Text the engine pronounces instead (≤ 1000 chars).

string

Optional IPA transcription (maximum 200 characters). Takes precedence over replacement when set.

boolean

default:"false"

Match the original case exactly.

Example

curl -X POST "https://api.kugelaudio.com/v1/dictionaries/1/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"word": "Postgres", "replacement": "post-gres"}'

e = client.dictionaries.entries.add(
    dictionary_id=1,
    word="Postgres",
    replacement="post-gres",
)

const e = await client.dictionaries.entries.add(1, {
  word: 'Postgres',
  replacement: 'post-gres',
});

DictionaryEntry e = client.dictionaries().entries().add(
    1, new DictionaryEntryInput("Postgres", "post-gres"));

Bulk Replace Entries

Replace every entry in the dictionary. Entries currently in the dictionary whose word is not in the supplied list are deleted. The operation is idempotent — calling twice with the same payload converges to the same final state.

Body

array

required

Array of { word, replacement, ipa?, case_sensitive? } items. word and replacement are required on every item; their limits and case_sensitive: false default match Add Entry. Duplicate word values within the payload are rejected.

Response

{ "upserted": 25, "deleted": 3, "total": 25 }

Example

curl -X PUT "https://api.kugelaudio.com/v1/dictionaries/1/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {"word": "Postgres",   "replacement": "post-gres"},
      {"word": "Kubernetes", "replacement": "koo-ber-net-eez"}
    ]
  }'

result = client.dictionaries.entries.replace_all(
    dictionary_id=1,
    entries=[
        {"word": "Postgres",   "replacement": "post-gres"},
        {"word": "Kubernetes", "replacement": "koo-ber-net-eez"},
    ],
)
print(result.upserted, result.deleted)

const result = await client.dictionaries.entries.replaceAll(1, [
  { word: 'Postgres',   replacement: 'post-gres' },
  { word: 'Kubernetes', replacement: 'koo-ber-net-eez' },
]);
console.log(result.upserted, result.deleted);

BulkReplaceResult result = client.dictionaries().entries().replaceAll(
    1,
    List.of(
        new DictionaryEntryInput("Postgres",   "post-gres"),
        new DictionaryEntryInput("Kubernetes", "koo-ber-net-eez")));

Update Entry

Only non-null fields are sent.

Body

string

New word (1-200 characters).

string

New replacement (1-1000 characters).

string

New IPA transcription (maximum 200 characters). Send an empty string to clear it; null leaves it unchanged.

boolean

Delete Entry

Response

{ "deleted": true }

Deletion is idempotent after the parent dictionary has been authorized: a missing entry_id also returns { "deleted": true }.

Error responses

Status	Code	Meaning
400	`VALIDATION_ERROR`	Missing or invalid field; e.g. master-key call without `project_id`.
401	`UNAUTHORIZED`	API key missing, invalid, or not project-scoped.
403	`UNAUTHORIZED`	API key is scoped to a different project than the target.
404	`NOT_FOUND`	Dictionary does not exist, or an entry requested for update does not exist.
503	`INTERNAL_ERROR`	Dictionary management is unavailable on this deployment.

Get started

Build a voice agent

Generate audio

Voices

Deploy

SDK Reference

API Reference

Common Request Fields

Response Objects

List Dictionaries

Query Parameters

Response

Example

Create Dictionary

Body

Example

Get Dictionary

Update Dictionary

Body

Example

Delete Dictionary

Response

List Entries

Query Parameters

Response

Add Entry

Body

Example

Bulk Replace Entries

Body

Response

Example

Update Entry

Body

Delete Entry

Response

Error responses

​Common Request Fields

​Response Objects

​List Dictionaries

​Query Parameters

​Response

​Example

​Create Dictionary

​Body

​Example

​Get Dictionary

​Update Dictionary

​Body

​Example

​Delete Dictionary

​Response

​List Entries

​Query Parameters

​Response

​Add Entry

​Body

​Example

​Bulk Replace Entries

​Body

​Response

​Example

​Update Entry

​Body

​Delete Entry

​Response

​Error responses

Common Request Fields

Response Objects

List Dictionaries

Query Parameters

Response

Example

Create Dictionary

Body

Example

Get Dictionary

Update Dictionary

Body

Example

Delete Dictionary

Response

List Entries

Query Parameters

Response

Add Entry

Body

Example

Bulk Replace Entries

Body

Response

Example

Update Entry

Body

Delete Entry

Response

Error responses