Get an agent - Clarity Support Docs

Get an agent

curl --request GET \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/agents/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://voice-api.onclarity.com/v1/projects/{projectId}/agents/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/agents/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3f0c6a52-8d7e-4b8a-9a43-0f2b5c1e9d11",
  "name": "Billing assistant",
  "project_id": "7b1d2e44-51c0-4f3a-8e5b-2a9c0d6f1e33",
  "created_at": 1760000000000,
  "updated_at": 1760086400000,
  "agent_type": "chained",
  "agent_engine": "livekit",
  "preferred_language": "English (US)",
  "allow_language_switch": false,
  "greeting_message": "Hi, thanks for calling Acme billing. How can I help?",
  "goodbye_message": "Thanks for calling. Goodbye!",
  "agent_model_config": {
    "asr_provider": "deepgram",
    "asr_model": "nova-3",
    "llm_provider": "openai",
    "llm_model": "gpt-6-luna",
    "tts_provider": "elevenlabs"
  },
  "max_call_duration_sec": 900,
  "summary_enabled": true,
  "livekit_region": null,
  "builtin_tools": [
    "lk_endCall"
  ],
  "demo": null
}

{
  "error": "Invalid or revoked token"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Agent not found"
}

GET

projects

{projectId}

agents

{id}

Get an agent

curl --request GET \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/agents/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://voice-api.onclarity.com/v1/projects/{projectId}/agents/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/agents/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3f0c6a52-8d7e-4b8a-9a43-0f2b5c1e9d11",
  "name": "Billing assistant",
  "project_id": "7b1d2e44-51c0-4f3a-8e5b-2a9c0d6f1e33",
  "created_at": 1760000000000,
  "updated_at": 1760086400000,
  "agent_type": "chained",
  "agent_engine": "livekit",
  "preferred_language": "English (US)",
  "allow_language_switch": false,
  "greeting_message": "Hi, thanks for calling Acme billing. How can I help?",
  "goodbye_message": "Thanks for calling. Goodbye!",
  "agent_model_config": {
    "asr_provider": "deepgram",
    "asr_model": "nova-3",
    "llm_provider": "openai",
    "llm_model": "gpt-6-luna",
    "tts_provider": "elevenlabs"
  },
  "max_call_duration_sec": 900,
  "summary_enabled": true,
  "livekit_region": null,
  "builtin_tools": [
    "lk_endCall"
  ],
  "demo": null
}

{
  "error": "Invalid or revoked token"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Agent not found"
}

Authorizations

Authorization

string

header

required

Your organization API key (it starts with anek_org_). The same key works on the Voice API and the Support API. See Authentication.

Path Parameters

projectId

string

required

Project id

string

required

Agent id

Response

The agent.

An agent and its configuration. Fields not listed here may also be present. See GET /v1/agents/config-schema for the full format.

string

required

name

string

required

project_id

string

required

created_at

integer<int64>

required

Creation time, epoch milliseconds.

updated_at

integer<int64> | null

Last edit or publish, epoch milliseconds.

agent_engine

string

Always livekit for current agents.

published_version_id

string | null

The live version's id. Present on list items.

published_version_number

integer | null

The live version's number. Present on list items.

has_draft

boolean

An unpublished draft exists. Present on list items.

draft_catalog_sync_only

boolean

The draft exists only because a shared tool, dictionary or hold-phrase set used by this agent was edited elsewhere, not because the agent itself was edited. Present on list items.

llm_refs

object[]

The language models the agent runs on (live version, else the draft), with fallbacks. Present on list items.

Show child attributes

card

object

What the agent's card shows of its live version, else its draft. Present on list items.

Show child attributes

agent_type

string

chained (default): speech recognition, a language model and a voice in sequence. realtime: a speech-to-speech model. assist: a Voice Assist agent, which listens to a call handled by a person and suggests answers to them; it never speaks and needs the Voice Assist product. The type cannot change between assist and a voice type after creation.

preferred_language

string | null

The conversation language, as a label from GET .../agents/chained-options (for example "English (US)", "Arabic (Najdi)"). It decides which speech providers and voices are available. For a bilingual agent it names the primary language.

allow_language_switch

boolean

Let the agent switch language when the caller does.

greeting_message

string

What the agent says when the call connects.

goodbye_message

string | null

What the agent says before it hangs up. Empty means "Goodbye."

Maximum string length: 500

silence_goodbye_message

string | null

What the agent says when it hangs up because the caller went silent. Empty means goodbye_message.

end_call_description

string | null

Replaces the built-in description of the end_call tool (when the agent should hang up). Empty means the built-in text.

Maximum string length: 2000

tts_director_prompt

string | null

Delivery notes for the voice: tone, pace, accent.

Maximum string length: 4000

dialect_notes

string | null

Vocabulary and register guidance for the agent's dialect, added to its instructions.

dialect_notes_ref

string | null

The organization dialect-notes template the notes follow while unedited (or, when dialect_notes_customized is true, were edited from); null means the notes are the agent's own text. On a bilingual agent it names the main language (Arabic when the pair has it, else the first language).

dialect_notes_customized

boolean | null

true when dialect_notes is the author's edit of the dialect_notes_ref template: calls use the author's text and the ref records its origin. Stored only as true together with a ref; false and null are stored as null. A write that carries dialect_notes or dialect_notes_ref without it means "not edited". The second language of a bilingual agent carries the same key in its multi_language.languages[] entry.

prompt_template_selections

object[]

Organization prompt templates appended to the instructions, in order.

dynamic_prompt

boolean

hijri_date

boolean | null

Adds the Umm al-Qura Hijri date to the caller's local time the agent gets at call start ("Caller's local time", system__time_local). null, the default, follows the agent's languages: on when Arabic is the only language or one of two.

task_prompt_json

object | null

The agent's instructions (rich-text document).

language_controls_enabled

boolean

tools_instructions

object | null

Extra instructions on when to use the attached tools.

vad_config

object | null

Voice activity detection tuning. See GET /v1/agents/config-schema for the full format.

enable_engagement_checks

boolean

Check in with the caller after a long silence.

engagement_check_countdown_ms

integer | null

max_engagement_checks

integer | null

agent_model_config

object | null

Speech recognition, language model and voice settings (asr_*, llm_*, tts_* keys and turn-taking settings). Replaced as a whole on update. Omitted on create: the platform defaults. See GET /v1/agents/config-schema for the full format. Available providers, models and voices: GET /v1/projects/{projectId}/agents/chained-options. A Voice Assist agent keeps its speech recognition, its suggestion model and, of the voice keys, only tts_provider, tts_model, tts_dialect and tts_voice: the voice that speaks its hold phrases (assist_config.hold_audio). When any of them is set, tts_provider and tts_model are required and the voice must be one offered for the agent's primary language; with none set, the language's default voice speaks.

Show child attributes

sidekick_reminders

any[] | null

post_tool_reminder

string | null

greeting_vad_config

object | null

Voice activity detection tuning while the greeting plays.

greeting_interruptible

boolean

Whether the caller can interrupt the greeting.

noise_reduction_enabled

boolean

Filter background noise from the caller's audio.

memory

boolean

Give the agent a digest of the caller's recent support tickets at the start of the call.

memory_days

integer | null

How far back (days, 1–365) to look for the caller's tickets; 0 uses the caller's name and attributes only.

memory_max_tickets

integer | null

At most this many recent tickets (1–10).

summary_enabled

boolean

Write a summary of each call when it ends.

realtime_warnings

object | null

In-call warnings raised to supervisors while a call is in progress. See GET /v1/agents/config-schema for the full format.

caller_sentiment

object | null

Live caller-sentiment tracking. See GET /v1/agents/config-schema for the full format.

background_audio

object | null

Background ambience and typing sounds while the agent thinks. See GET /v1/agents/config-schema for the full format.

Show child attributes

start_tools

object | null

Tools run when the call starts, before the greeting. See GET /v1/agents/config-schema for the full format.

Show child attributes

language_switching

object | null

Language-switching policy and custom instruction texts. null means platform defaults.

speech_normalization

object | null

How the agent speaks numbers, dates, amounts, links and acronyms. {"enabled": true} uses the defaults; null turns it off.

On outbound calls, navigate phone menus with keypad tones. Requires amd_enabled.

amd_enabled

boolean

On outbound calls, detect an answering machine and end the call without the script.

livekit_region

string | null

Pin calls to a media region: me, eu or us. null picks the region nearest the caller.

max_call_duration_sec

integer | null

Hard limit on a call's length, in seconds (30–3600, default 3600).

max_llm_tokens_per_call

integer | null

End the call once the conversation model has used this many tokens (1,000–5,000,000). null means no limit.

task_groups

object[] | null

Structured tasks (workflows) the agent can run.

Show child attributes

builtin_tools

string[]

Built-in tools to enable, for example lk_endCall (hang up).

silence_recovery_config

object | null

What to do when the caller goes silent: max_nudges (0–10), timeout_s (0.5–60) and the nudge note.

multi_language

object | null

A second conversation language and the speech settings for it. null means a single-language agent. A bilingual agent is a single-language agent plus a second language: the main language (Arabic when the pair has it, else the first) lives in the agent's own fields — its voice in agent_model_config, greeting, goodbye, dialect notes and director prompt — so its entry carries only label and asr_language; the second language's entry carries its greeting, goodbye, dialect notes (dialect_notes, dialect_notes_ref, dialect_notes_customized) and director prompt, plus its own voice only with per_language_tts. The block itself carries no voice.

demo

object | null

The demo page settings, without the password. null when off.

sheet_refs

object

Google Sheet ids shared with every code tool of the agent, by argument name (for example BOOKINGS_SHEET_ID). Send {} to clear.

Show child attributes

prompt_field_whitelist

object | null

The call-context fields (caller number, custom fields passed when a call starts) the instructions may reference. null allows any.

output_schema

object | null

Fields to extract from the conversation when the call ends, by name, each with type, description, required, enum_values. null turns extraction off.

workflow_config

object | null

Rules the agent may apply at any point in the call (global_rules).

assist_config

object | null

Voice Assist settings. Only for agent_type: assist; ignored for other types.

Show child attributes