Create an agent

curl --request POST \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Billing assistant",
  "agent_type": "chained",
  "preferred_language": "English (US)",
  "greeting_message": "Hi, thanks for calling Acme billing. How can I help?",
  "goodbye_message": "Thanks for calling. Goodbye!",
  "task_prompt_json": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "You are a friendly billing assistant for Acme. Help callers understand their invoices."
          }
        ]
      }
    ]
  },
  "max_call_duration_sec": 900,
  "summary_enabled": true
}
'

import requests

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

payload = {
    "name": "Billing assistant",
    "agent_type": "chained",
    "preferred_language": "English (US)",
    "greeting_message": "Hi, thanks for calling Acme billing. How can I help?",
    "goodbye_message": "Thanks for calling. Goodbye!",
    "task_prompt_json": {
        "type": "doc",
        "content": [
            {
                "type": "paragraph",
                "content": [
                    {
                        "type": "text",
                        "text": "You are a friendly billing assistant for Acme. Help callers understand their invoices."
                    }
                ]
            }
        ]
    },
    "max_call_duration_sec": 900,
    "summary_enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Billing assistant',
    agent_type: 'chained',
    preferred_language: 'English (US)',
    greeting_message: 'Hi, thanks for calling Acme billing. How can I help?',
    goodbye_message: 'Thanks for calling. Goodbye!',
    task_prompt_json: {
      type: 'doc',
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'You are a friendly billing assistant for Acme. Help callers understand their invoices.'
            }
          ]
        }
      ]
    },
    max_call_duration_sec: 900,
    summary_enabled: true
  })
};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/agents', 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,
  "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,
  "builtin_tools": [
    "lk_endCall"
  ],
  "demo": null
}

{
  "error": "An agent with this name already exists in this project"
}

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

{
  "error": "publish_capability_required",
  "code": "PUBLISH_CAPABILITY_REQUIRED"
}

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

{
  "error": "Demo domain already in use"
}

{
  "error": "name: String must contain at least 1 character(s)",
  "issues": [
    {
      "path": "name",
      "code": "too_small",
      "message": "String must contain at least 1 character(s)",
      "minimum": 1
    }
  ]
}

Agents

Create an agent

Creates an agent and publishes its first version, so it is live as soon as it is created. Only name is required: every setting you leave out takes the platform default (speech recognition, language model and voice included). The full configuration format, with every field and allowed value, is served by GET /v1/agents/config-schema; the providers, models and voices available to this project by GET /v1/projects/{projectId}/agents/chained-options.

Needs the publish permission, which organization API keys carry.

POST

projects

{projectId}

agents

Create an agent

curl --request POST \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Billing assistant",
  "agent_type": "chained",
  "preferred_language": "English (US)",
  "greeting_message": "Hi, thanks for calling Acme billing. How can I help?",
  "goodbye_message": "Thanks for calling. Goodbye!",
  "task_prompt_json": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "You are a friendly billing assistant for Acme. Help callers understand their invoices."
          }
        ]
      }
    ]
  },
  "max_call_duration_sec": 900,
  "summary_enabled": true
}
'

import requests

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

payload = {
    "name": "Billing assistant",
    "agent_type": "chained",
    "preferred_language": "English (US)",
    "greeting_message": "Hi, thanks for calling Acme billing. How can I help?",
    "goodbye_message": "Thanks for calling. Goodbye!",
    "task_prompt_json": {
        "type": "doc",
        "content": [
            {
                "type": "paragraph",
                "content": [
                    {
                        "type": "text",
                        "text": "You are a friendly billing assistant for Acme. Help callers understand their invoices."
                    }
                ]
            }
        ]
    },
    "max_call_duration_sec": 900,
    "summary_enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Billing assistant',
    agent_type: 'chained',
    preferred_language: 'English (US)',
    greeting_message: 'Hi, thanks for calling Acme billing. How can I help?',
    goodbye_message: 'Thanks for calling. Goodbye!',
    task_prompt_json: {
      type: 'doc',
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'You are a friendly billing assistant for Acme. Help callers understand their invoices.'
            }
          ]
        }
      ]
    },
    max_call_duration_sec: 900,
    summary_enabled: true
  })
};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/agents', 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,
  "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,
  "builtin_tools": [
    "lk_endCall"
  ],
  "demo": null
}

{
  "error": "An agent with this name already exists in this project"
}

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

{
  "error": "publish_capability_required",
  "code": "PUBLISH_CAPABILITY_REQUIRED"
}

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

{
  "error": "Demo domain already in use"
}

{
  "error": "name: String must contain at least 1 character(s)",
  "issues": [
    {
      "path": "name",
      "code": "too_small",
      "message": "String must contain at least 1 character(s)",
      "minimum": 1
    }
  ]
}

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

Body

application/json

An agent configuration. Only name is required; omitted fields take their defaults. Unknown fields are ignored. See GET /v1/agents/config-schema for the full format.

name

string

required

The agent's name, unique in the project.

Minimum string length: 1

agent_type

enum<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.

Available options:

chained,

realtime,

assist

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.

Maximum string length: 500

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.

Maximum string length: 4000

dialect_notes_ref

string | null

The organization dialect-notes template the notes follow while unedited; null means the notes are the agent's own text.

prompt_template_selections

object[]

Organization prompt templates appended to the instructions, in order.

dynamic_prompt

boolean

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.

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.

start_tools

object | null

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

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).

Required range: 30 <= x <= 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.

callbacks

object | null

Webhooks called by the platform. on_finish posts the call record to your URL when a call ends: url, method (POST, PUT, PATCH), authentication (none, bearer with token, api_key with key and header), headers, timeout_ms, extra_fields.

demo

object | null

A public demo page for the agent: domain (lowercase letters, digits, hyphens), user, password (required the first time), company_name, agent_role, logo_url, colors (background, primary). null turns it off. The password is never returned.

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

Response

The agent was created and its first version published.

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

agent_type

string

preferred_language

string | null

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.

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; null means the notes are the agent's own text.

prompt_template_selections

object[]

Organization prompt templates appended to the instructions, in order.

dynamic_prompt

boolean

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

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.

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