Create a glossary term

import requests
url = "https://example.ada.support/api/v2/glossary/"
payload = {
    "external_id": "refund-policy",
    "translation_mode": "custom",
    "user_terms": [
        {
            "term": "money back",
            "language": "en"
        }
    ],
    "ai_agent_terms": [
        {
            "term": "refund",
            "language": "en"
        }
    ],
    "definition": "Money returned to a customer after a purchase."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "65a17e3f43bec88e2792d0eb",
  "external_id": "refund-policy",
  "translation_mode": "custom",
  "user_terms": [
    {
      "term": "money back",
      "language": "en"
    }
  ],
  "ai_agent_terms": [
    {
      "term": "refund",
      "language": "en"
    }
  ],
  "voice_detection_enabled": false,
  "definition": "Money returned to a customer after a purchase.",
  "voice_pronunciations": null,
  "availability_rules": null
}

Create a glossary term for the AI Agent. external_id is your own identifier for the term and must be unique within the AI Agent.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

external_idstringRequiredformat: "^[\w +,\-.@#_$%&']+$"1-100 characters

Your own identifier for the term, unique within the AI Agent

translation_modeenumOptionalDefaults to default

custom restates detected user_terms using ai_agent_terms; default only surfaces the definition. Defaults to default.

user_termslist of objects or nullOptional

The wordings a customer might use, per language

ai_agent_termslist of objects or nullOptional

The wordings the AI Agent should use, per language

voice_detection_enabledbooleanOptionalDefaults to false

Improve how reliably the term is recognized in speech. Requires a voice platform on the AI Agent. Defaults to false.

definitionstring or nullOptional1-1000 characters

A business definition of the term, shown to the AI Agent

voice_pronunciationslist of objects or nullOptional

Phonetic respellings the AI Agent speaks in place of the written form on voice calls; omit or send null for none

availability_rulesobject or nullOptional

The structured rule gating when this term applies; omit or send null for no rule, and an unknown variable id or a malformed rule is rejected with a 400

Response

Created

idstringRead-only

The unique identifier for the glossary term

external_idstringformat: "^[\w +,\-.@#_$%&']+$"1-100 characters

Your own identifier for the term, unique within the AI Agent

translation_modeenum

custom tells the AI Agent to answer using the matching ai_agent_terms wording whenever it detects one of the user_terms. default only surfaces the term’s definition to the agent (and, with voice_detection_enabled, biases speech recognition) without changing its wording.

user_termslist of objects or null

The wordings a customer might use, per language. null when none are configured.

ai_agent_termslist of objects or null

The wordings the AI Agent should use, per language. Only meaningful in custom mode; null when none are configured.

voice_detection_enabledboolean

Whether the term is passed to the voice agent to improve how reliably it is recognized in speech. Requires a voice platform on the AI Agent.

definitionstring or null1-1000 characters

A business definition of the term, shown to the AI Agent when the term is detected. null when unset.

voice_pronunciationslist of objects or null

Phonetic respellings applied to the AI Agent’s outgoing speech on voice calls, or null when none are configured

availability_rulesobject or null

The structured rule that gates when this term applies, with variables referenced by id, or null when no rule is attached

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error