aethexDocs

API Reference

Pronunciation Dictionaries

Tell your agents how to say the words they get wrong: brands, places, names. A dictionary lists words (grapheme) with a respelling the voice reads instead (phoneme), for example Cocody read as Ko-ko-di. The transcript and the conversation history keep the word as written.Workspace or agent. A dictionary belongs to the whole workspace (no agent_id) or to one agent. For the same word, the agent's entry wins over the workspace's. A dictionary applies to the agents whose language is in the same language family as its language; an agent's own dictionary must be in that agent's language.One dictionary per language. The workspace, and each agent, has one dictionary per language family, of up to 1,000 entries. To change it, replace its entries.Matching. Whole words only, case ignored, accents significant. An all-capitals entry such as MTN matches only in capitals (so UN leaves "un" alone) and also matches its letters spaced out, M T N. Straight and curly apostrophes are the same. The words of a multi-word entry may be separated by any whitespace. Where two entries overlap, the longest one wins.Respellings only. IPA is not supported: the voice reads plain text. A respelling must be plain words the voice reads as written: no digits, no markup, nothing the speech cleanup would change. A respelling sounds different from one voice to another, so listen to it on the agent's voice.When it applies. From the agent's next call, and to its WhatsApp voice notes. A call already in progress keeps the entries it started with.

Base URL
https://api.aethexai.com/api/v1
Endpoints
5
Scopes
pronunciation:readpronunciation:write
POST/pronunciation-dictionaries

Create a dictionary for the workspace or for one agent, with its entries.

Create Dictionary

Creates a dictionary and its entries in one request, and returns it with its entries. Leave out agent_id for a workspace dictionary. Nothing is created if any entry is refused.

Request body

7
  • namestringrequired

    Name of the dictionary, up to 255 characters.

  • descriptionstringoptional

    Optional free-text description.

  • languagestringrequired

    Language of the dictionary, one of the values an agent's language accepts (for example english or french). The dictionary applies to the agents whose language is in the same language family.

  • agent_idstringoptional

    ID of the agent the dictionary belongs to. Leave it out for a dictionary that applies to every agent of the workspace. The agent's language must be in the same language family as language.

  • entriesobject[]optional

    The words and their respellings, up to 1,000. Defaults to none.

  • entries[].graphemestringrequired

    The word as written, up to 100 characters, for example Cocody. Several words are allowed (Côte d'Ivoire). Each word can appear once, case and apostrophe style ignored.

  • entries[].phonemestringrequired

    How the voice should read it, up to 200 characters, for example Ko-ko-di. Plain words only: no digits, no markup, nothing the speech cleanup would change.

Errors

4
403Language not available

The dictionary's language is a local African language or Arabic: those are part of the Aethex enterprise platform.

Use english or french in its standard form, or move the work to the Aethex enterprise platform.

404Not Found

No agent of your workspace has this agent_id.

Check the ID with GET /agents, or leave agent_id out for a workspace dictionary.

409Dictionary already exists

The workspace (no agent_id), or this agent, already has a dictionary in this language family.

Replace the entries of the existing dictionary instead (PUT on its /entries); the error gives its id.

422Unprocessable Entity

language is not an agent language; the agent speaks a language of another family; an entry is empty, too long, contains markup or a control character, or its respelling contains a digit or would be changed by the speech cleanup; a word appears twice.

The response names the word and the reason. Correct it and send the request again.

GET/pronunciation-dictionaries

List the workspace's dictionaries, with their entry counts.

List Dictionaries

Returns every dictionary of the workspace, workspace-wide and per-agent, oldest first, each with entry_count. The entries themselves are not included: read them with GET /pronunciation-dictionaries/:id.

GET/pronunciation-dictionaries/:id

Get one dictionary with its entries.

Get Dictionary

Returns the dictionary with all its entries, sorted by word (case ignored).

Path & Query

1
  • idstringrequired

    Dictionary ID.

Errors

1
404Not Found

No dictionary of your workspace has this ID.

Check the ID with GET /pronunciation-dictionaries.

PUT/pronunciation-dictionaries/:id/entries

Replace every entry of a dictionary, from JSON or a CSV file.

Replace Entries

Replaces all the entries of the dictionary with the ones sent, and returns the dictionary with its new entries. Send an empty list to empty it. Nothing changes if any entry is refused.JSON. Content-Type: application/json, with the entries in entries.CSV. Content-Type: text/csv, UTF-8, a first line grapheme,phoneme, then one entry per line; blank lines are skipped. For example grapheme,phoneme then Cocody,Ko-ko-di.The body can be up to 1 MB (1,000,000 bytes).

Path & Query

1
  • idstringrequired

    Dictionary ID.

Request body

3
  • entriesobject[]required

    The new entries (JSON body), up to 1,000. They replace every entry the dictionary has.

  • entries[].graphemestringrequired

    The word as written, up to 100 characters, for example Cocody. Several words are allowed (Côte d'Ivoire). Each word can appear once, case and apostrophe style ignored.

  • entries[].phonemestringrequired

    How the voice should read it, up to 200 characters, for example Ko-ko-di. Plain words only: no digits, no markup, nothing the speech cleanup would change.

Errors

3
403Language not available

The dictionary's language is a local African language or Arabic: those are part of the Aethex enterprise platform.

Use english or french in its standard form, or move the work to the Aethex enterprise platform.

404Not Found

No dictionary of your workspace has this ID.

Check the ID with GET /pronunciation-dictionaries.

422Unprocessable Entity

An entry is refused (empty, too long, markup or a control character, a digit in the respelling, a respelling the speech cleanup would change, a word given twice), the Content-Type is neither application/json nor text/csv, the body is larger than 1 MB, or the CSV is not UTF-8, lacks the grapheme,phoneme header or has a line without exactly two columns. A dictionary whose language is no longer an agent language cannot be edited.

The response names the word, or the CSV line, and the reason. Correct it and send the request again. For a dictionary in a language that is no longer an agent language, create a new dictionary and delete the old one.

DELETE/pronunciation-dictionaries/:id

Delete a dictionary and its entries.

Delete Dictionary

Deletes the dictionary and all its entries. Calls that start afterwards no longer use them.

Path & Query

1
  • idstringrequired

    Dictionary ID.

Errors

1
404Not Found

No dictionary of your workspace has this ID.

Check the ID with GET /pronunciation-dictionaries.