Skip to content
OnCoreDocs
Dictionaries

GEThttps://core-api.heysadie.ai/dictionaries

limit offset type success data dictionaries id tenantId name entries term soundsLike language word respell phonemes caseSensitive createdAt updatedAt total metadata timestamp version path error code message details field

List dictionaries

List the tenant's dictionaries. Pass `type` to return only `keywords` or only `pronunciations`. Each row includes its full `entries` array, so this is also how you read current entries before a `PUT`, which replaces that array rather than merging into it.

Try it in the API Explorer

Example request

Terminal
curl "https://core-api.heysadie.ai/dictionaries?limit=10&offset=0" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Authentication

Authenticate with an API key in the Authorization header using the ApiKey scheme. See Authentication for how keys work and where to get them.

Authorizationstringrequired

API key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.

X-Tenant-Idstring (uuid)optional

Required when authenticating with an organization key: it selects the tenant the request acts on. Omit with tenant keys.

Request

Query parameters

limitstringoptional

Page size. Default 10, maximum 100. Note this resource does not use the platform-wide 50/500 defaults.

offsetstringoptional

Rows to skip. Default 0.

typeenumoptional

Return only dictionaries of this kind. Omit to return both kinds.

Allowed values:"keywords""pronunciations"

Responses

200
successbooleanrequired

true on every 2xx

dataobjectoptional

The result

Show 2 child properties
dictionariesobject[]required
Show 7 item properties
idstringrequired

The dictionary's UUID. Link a dictionary to an assistant by this value.

tenantIdstringrequired

UUID of the tenant that owns the dictionary.

typeenumrequired

Which entry shape `entries` holds. `keywords` holds recognition terms that bias what the transcriber hears; `pronunciations` holds rules that control how the assistant says a word. Fixed at creation and cannot be changed.

Allowed values:"keywords""pronunciations"
namestringrequired

Human-readable label, shown wherever the dictionary is listed or linked. Not used for matching.

entriesobject[]required

The dictionary's rules, in the shape `type` dictates. At most 100 entries per dictionary. Note a separate runtime limit: across an assistant's own entries plus every dictionary it links, only the first 100 recognition terms are sent, counted in linking order. Pronunciations have no combined limit.

Show 8 properties across 2 possible shapes
termstringrequired

Recognition-term entries only. The word to bias the transcriber toward, spelled the way you want it to appear in the transcript. At most 50 characters; longer terms are rejected because oversized terms degrade the surrounding transcript rather than simply failing.

soundsLikestring[]optional

Recognition-term entries only. Phonetic hints for the term. Accepted and stored, but not currently forwarded to any transcriber, so a rule must not depend on it today.

languagestring | nulloptional

Recognition-term entries only. One of the languages a call can settle on: `en`, `fr`, `de`, `es`, `it`, `pt`, `ar`, `nl`, `hi`, `ru`, `ja`. Locales such as `en-AU` are stored as the base code. `english` and any other string are rejected. Applied only when the assistant's transcriber is set to a single language: on a multilingual transcriber every term is sent whatever this says, because terms are handed to the transcriber as the call connects, before any language has been detected. Leave unset to apply on every call.

wordstringrequired

Pronunciation entries only. The word whose pronunciation changes. Matched on whole words only, so `Quatre` does not fire inside `Quatres`, and case-insensitively unless `caseSensitive` is true. At most 50 characters.

respellstringoptional

Pronunciation entries only. A plain-text spelling of how the word should sound, such as `Kat`. Works on nearly every voice and is the fallback whenever `phonemes` cannot be used, so supplying it keeps the rule alive everywhere. Letters are handed to the voice, so it is read with that voice's own accent. At most 100 characters.

phonemesstringoptional

Pronunciation entries only. Space-separated IPA, one token per sound, such as `k a t`. Multi-character symbols stay in one token (`tʃ`, `eɪ`). Rendered into the live voice's own markup at synthesis time. Only Cartesia `sonic-3`, `sonic-3.5` and `sonic-3.6` speak phonemes; on every other voice the rule falls back to `respell`, and a rule with no `respell` then does nothing. Phonemes are read with the voice's accent too, so a rule that is only correct in one language needs a voice in that language. At most 200 characters, and may not contain `<`, `>` or `|`, which are provider markup.

languagestring | nulloptional

Pronunciation entries only. One of the languages a call can settle on: `en`, `fr`, `de`, `es`, `it`, `pt`, `ar`, `nl`, `hi`, `ru`, `ja`. Locales such as `fr-CA` are stored as the base code. `english` and any other string are rejected. The rule applies only on replies the call has resolved to that language, re-evaluated on every turn, so it works even on a multilingual transcriber. Leave unset to apply on every reply.

caseSensitivebooleanoptional

Pronunciation entries only. When true, only the exact capitalization in `word` matches. Defaults to false, which matches any capitalization.

createdAtstring (date-time) | string (date) | number | nullrequired

When the dictionary was created.

updatedAtstring (date-time) | string (date) | number | nullrequired

When the dictionary was last modified.

totalnumberrequired
metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

400The request is invalid. `details` lists each field that failed
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 3 child properties
codeenumrequired

A parameter or body field broke a rule

Allowed values:"VALIDATION_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

detailsobject[]optional

One entry per field that failed

Show 2 item properties
fieldstringrequired

The offending field

messagestringrequired

The rule it broke

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

401Missing or invalid credentials
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

No valid credentials

Allowed values:"UNAUTHORIZED"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

403The credentials are valid but may not use this route
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

The credentials may not use this route

Allowed values:"FORBIDDEN"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

404Not found, or outside the caller's scope
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An id names nothing the caller can see

Allowed values:"RESOURCE_NOT_FOUND"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

500An unexpected server error
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An unexpected server failure

Allowed values:"INTERNAL_SERVER_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested