> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml api-reference/voice-openapi.json POST /v1/projects/{projectId}/agents openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: >- Voice agents and their tools, outbound calls, conversations, campaigns, telephony, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. - name: Phone numbers description: >- The phone numbers of a project, where their calls come from, and how agents call out from them. - name: Inbound SIP trunks description: Bring calls from your own SIP infrastructure to Clarity agents. - name: Outbound SIP trunks description: >- The SIP endpoints Clarity dials through for outbound calls from your numbers. - name: Tools description: The tools agents call during a conversation, and which agents use them. paths: /v1/projects/{projectId}/agents: parameters: - $ref: '#/components/parameters/ProjectIdPath' post: tags: - Agents summary: Create an agent description: >- 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. operationId: createAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' example: 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 responses: '201': description: The agent was created and its first version published. content: application/json: schema: $ref: '#/components/schemas/Agent' example: 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 '400': description: >- An agent with this name already exists in the project, or the request names an agent type that is no longer supported (`code: AGENT_TYPE_NOT_SUPPORTED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: An agent with this name already exists in this project '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`), or you are creating a Voice Assist agent and your organization does not have Voice Assist (`code: VOICE_ASSISTANT_REQUIRED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: publish_capability_required code: PUBLISH_CAPABILITY_REQUIRED '404': $ref: '#/components/responses/NotFound' '409': description: The demo page domain is already used by another agent. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Demo domain already in use '422': $ref: '#/components/responses/AgentSaveValidationFailed' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: CreateAgentRequest: type: object required: - name description: >- 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. properties: name: type: string minLength: 1 description: The agent's name, unique in the project. agent_type: type: string enum: - chained - realtime - assist description: >- `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: type: string nullable: true description: >- 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: type: boolean description: Let the agent switch language when the caller does. greeting_message: type: string description: What the agent says when the call connects. goodbye_message: type: string nullable: true maxLength: 500 description: What the agent says before it hangs up. Empty means "Goodbye." silence_goodbye_message: type: string nullable: true maxLength: 500 description: >- What the agent says when it hangs up because the caller went silent. Empty means `goodbye_message`. end_call_description: type: string nullable: true maxLength: 2000 description: >- Replaces the built-in description of the end_call tool (when the agent should hang up). Empty means the built-in text. tts_director_prompt: type: string nullable: true maxLength: 4000 description: 'Delivery notes for the voice: tone, pace, accent.' dialect_notes: type: string nullable: true maxLength: 4000 description: >- Vocabulary and register guidance for the agent's dialect, added to its instructions. dialect_notes_ref: type: string nullable: true description: >- 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: type: boolean nullable: true description: >- `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: type: array items: additionalProperties: true type: object description: >- Organization prompt templates appended to the instructions, in order. dynamic_prompt: type: boolean hijri_date: type: boolean nullable: true description: >- 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; `true` / `false` set it. task_prompt_json: type: object nullable: true additionalProperties: true description: The agent's instructions (rich-text document). language_controls_enabled: type: boolean tools_instructions: type: object nullable: true additionalProperties: true description: Extra instructions on when to use the attached tools. vad_config: type: object nullable: true additionalProperties: true description: >- Voice activity detection tuning. See `GET /v1/agents/config-schema` for the full format. enable_engagement_checks: type: boolean description: Check in with the caller after a long silence. engagement_check_countdown_ms: type: integer nullable: true max_engagement_checks: type: integer nullable: true agent_model_config: allOf: - $ref: '#/components/schemas/AgentModelConfig' nullable: true sidekick_reminders: type: array nullable: true items: {} post_tool_reminder: type: string nullable: true greeting_vad_config: type: object nullable: true additionalProperties: true description: Voice activity detection tuning while the greeting plays. greeting_interruptible: type: boolean description: Whether the caller can interrupt the greeting. noise_reduction_enabled: type: boolean description: Filter background noise from the caller's audio. memory: type: boolean description: >- Give the agent a digest of the caller's recent support tickets at the start of the call. memory_days: type: integer nullable: true description: >- 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: type: integer nullable: true description: At most this many recent tickets (1–10). summary_enabled: type: boolean description: Write a summary of each call when it ends. realtime_warnings: type: object additionalProperties: true nullable: true description: >- In-call warnings raised to supervisors while a call is in progress. See `GET /v1/agents/config-schema` for the full format. caller_sentiment: type: object additionalProperties: true nullable: true description: >- Live caller-sentiment tracking. See `GET /v1/agents/config-schema` for the full format. background_audio: type: object additionalProperties: true nullable: true description: >- Background ambience and typing sounds while the agent thinks. See `GET /v1/agents/config-schema` for the full format. start_tools: type: object additionalProperties: true nullable: true description: >- Tools run when the call starts, before the greeting. See `GET /v1/agents/config-schema` for the full format. language_switching: type: object additionalProperties: true nullable: true description: >- Language-switching policy and custom instruction texts. `null` means platform defaults. speech_normalization: type: object additionalProperties: true nullable: true description: >- How the agent speaks numbers, dates, amounts, links and acronyms. `{"enabled": true}` uses the defaults; `null` turns it off. ivr_navigation_enabled: type: boolean description: >- On outbound calls, navigate phone menus with keypad tones. Requires `amd_enabled`. amd_enabled: type: boolean description: >- On outbound calls, detect an answering machine and end the call without the script. livekit_region: type: string nullable: true description: >- Pin calls to a media region: `me`, `eu` or `us`. `null` picks the region nearest the caller. max_call_duration_sec: type: integer nullable: true minimum: 30 maximum: 3600 description: Hard limit on a call's length, in seconds (30–3600, default 3600). max_llm_tokens_per_call: type: integer nullable: true description: >- End the call once the conversation model has used this many tokens (1,000–5,000,000). `null` means no limit. task_groups: type: array nullable: true items: $ref: '#/components/schemas/TaskGroup' description: Structured tasks (workflows) the agent can run. builtin_tools: type: array items: type: string description: Built-in tools to enable, for example `lk_endCall` (hang up). silence_recovery_config: type: object additionalProperties: true nullable: true description: >- What to do when the caller goes silent: `max_nudges` (0–10), `timeout_s` (0.5–60) and the nudge `note`. multi_language: type: object additionalProperties: true nullable: true description: >- 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. callbacks: type: object additionalProperties: true nullable: true description: >- 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: type: object additionalProperties: true nullable: true description: >- 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`), `ask_caller_id` (voice agents: the page asks for the caller's number and the call runs with it). `null` turns it off. The password is never returned. sheet_refs: type: object additionalProperties: type: string description: >- Google Sheet ids shared with every code tool of the agent, by argument name (for example `BOOKINGS_SHEET_ID`). Send `{}` to clear. prompt_field_whitelist: type: object additionalProperties: true nullable: true description: >- The call-context fields (caller number, custom fields passed when a call starts) the instructions may reference. `null` allows any. output_schema: type: object additionalProperties: true nullable: true description: >- 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: type: object additionalProperties: true nullable: true description: Rules the agent may apply at any point in the call (`global_rules`). assist_config: allOf: - $ref: '#/components/schemas/AssistConfig' nullable: true description: >- Voice Assist settings. Only for `agent_type: assist`; ignored for other types. Agent: type: object required: - id - name - project_id - created_at description: >- An agent and its configuration. Fields not listed here may also be present. See `GET /v1/agents/config-schema` for the full format. properties: id: type: string name: type: string project_id: type: string created_at: type: integer format: int64 description: Creation time, epoch milliseconds. updated_at: type: integer format: int64 nullable: true description: Last edit or publish, epoch milliseconds. agent_engine: type: string description: Always `livekit` for current agents. published_version_id: type: string nullable: true description: The live version's id. Present on list items. published_version_number: type: integer nullable: true description: The live version's number. Present on list items. has_draft: type: boolean description: An unpublished draft exists. Present on list items. draft_catalog_sync_only: type: boolean description: >- 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: type: array description: >- The language models the agent runs on (live version, else the draft), with fallbacks. Present on list items. items: properties: model: type: string place: enum: - voice - voice_assist type: string provider: type: string tier: enum: - primary - fallback_1 - fallback_2 type: string required: - provider - model - tier type: object card: type: object description: >- What the agent's card shows of its live version, else its draft. Present on list items. required: - language_label - tts_voice - tts_provider - tool_count properties: language_label: type: string description: The agent's languages, primary first, e.g. "Arabic · English". tts_voice: type: string nullable: true description: The voice it speaks with; null for Voice Assist agents. tts_provider: type: string nullable: true tool_count: type: integer nullable: true description: >- Tools in the live version; null when the agent was never published. agent_type: type: string description: >- `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: type: string nullable: true description: >- 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: type: boolean description: Let the agent switch language when the caller does. greeting_message: type: string description: What the agent says when the call connects. goodbye_message: type: string nullable: true maxLength: 500 description: What the agent says before it hangs up. Empty means "Goodbye." silence_goodbye_message: type: string nullable: true description: >- What the agent says when it hangs up because the caller went silent. Empty means `goodbye_message`. end_call_description: type: string nullable: true maxLength: 2000 description: >- Replaces the built-in description of the end_call tool (when the agent should hang up). Empty means the built-in text. tts_director_prompt: type: string nullable: true maxLength: 4000 description: 'Delivery notes for the voice: tone, pace, accent.' dialect_notes: type: string nullable: true description: >- Vocabulary and register guidance for the agent's dialect, added to its instructions. dialect_notes_ref: type: string nullable: true description: >- 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: type: boolean nullable: true description: >- `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: type: array items: additionalProperties: true type: object description: >- Organization prompt templates appended to the instructions, in order. dynamic_prompt: type: boolean hijri_date: type: boolean nullable: true description: >- 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: type: object nullable: true additionalProperties: true description: The agent's instructions (rich-text document). language_controls_enabled: type: boolean tools_instructions: type: object nullable: true additionalProperties: true description: Extra instructions on when to use the attached tools. vad_config: type: object nullable: true additionalProperties: true description: >- Voice activity detection tuning. See `GET /v1/agents/config-schema` for the full format. enable_engagement_checks: type: boolean description: Check in with the caller after a long silence. engagement_check_countdown_ms: type: integer nullable: true max_engagement_checks: type: integer nullable: true agent_model_config: allOf: - $ref: '#/components/schemas/AgentModelConfig' nullable: true sidekick_reminders: type: array nullable: true items: {} post_tool_reminder: type: string nullable: true greeting_vad_config: type: object nullable: true additionalProperties: true description: Voice activity detection tuning while the greeting plays. greeting_interruptible: type: boolean description: Whether the caller can interrupt the greeting. noise_reduction_enabled: type: boolean description: Filter background noise from the caller's audio. memory: type: boolean description: >- Give the agent a digest of the caller's recent support tickets at the start of the call. memory_days: type: integer nullable: true description: >- 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: type: integer nullable: true description: At most this many recent tickets (1–10). summary_enabled: type: boolean description: Write a summary of each call when it ends. realtime_warnings: type: object additionalProperties: true nullable: true description: >- In-call warnings raised to supervisors while a call is in progress. See `GET /v1/agents/config-schema` for the full format. caller_sentiment: type: object additionalProperties: true nullable: true description: >- Live caller-sentiment tracking. See `GET /v1/agents/config-schema` for the full format. background_audio: allOf: - $ref: '#/components/schemas/BackgroundAudioConfig' nullable: true description: >- Background ambience and typing sounds while the agent thinks. See `GET /v1/agents/config-schema` for the full format. start_tools: allOf: - $ref: '#/components/schemas/StartToolsConfig' nullable: true description: >- Tools run when the call starts, before the greeting. See `GET /v1/agents/config-schema` for the full format. language_switching: type: object additionalProperties: true nullable: true description: >- Language-switching policy and custom instruction texts. `null` means platform defaults. speech_normalization: type: object additionalProperties: true nullable: true description: >- How the agent speaks numbers, dates, amounts, links and acronyms. `{"enabled": true}` uses the defaults; `null` turns it off. ivr_navigation_enabled: type: boolean description: >- On outbound calls, navigate phone menus with keypad tones. Requires `amd_enabled`. amd_enabled: type: boolean description: >- On outbound calls, detect an answering machine and end the call without the script. livekit_region: type: string nullable: true description: >- Pin calls to a media region: `me`, `eu` or `us`. `null` picks the region nearest the caller. max_call_duration_sec: type: integer nullable: true description: Hard limit on a call's length, in seconds (30–3600, default 3600). max_llm_tokens_per_call: type: integer nullable: true description: >- End the call once the conversation model has used this many tokens (1,000–5,000,000). `null` means no limit. task_groups: type: array nullable: true items: $ref: '#/components/schemas/TaskGroup' description: Structured tasks (workflows) the agent can run. builtin_tools: type: array items: type: string description: Built-in tools to enable, for example `lk_endCall` (hang up). silence_recovery_config: type: object additionalProperties: true nullable: true description: >- What to do when the caller goes silent: `max_nudges` (0–10), `timeout_s` (0.5–60) and the nudge `note`. multi_language: type: object additionalProperties: true nullable: true description: >- 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: type: object additionalProperties: true nullable: true description: The demo page settings, without the password. `null` when off. sheet_refs: type: object additionalProperties: type: string description: >- Google Sheet ids shared with every code tool of the agent, by argument name (for example `BOOKINGS_SHEET_ID`). Send `{}` to clear. prompt_field_whitelist: type: object additionalProperties: true nullable: true description: >- The call-context fields (caller number, custom fields passed when a call starts) the instructions may reference. `null` allows any. output_schema: type: object additionalProperties: true nullable: true description: >- 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: type: object additionalProperties: true nullable: true description: Rules the agent may apply at any point in the call (`global_rules`). assist_config: allOf: - $ref: '#/components/schemas/AssistConfig' nullable: true description: >- Voice Assist settings. Only for `agent_type: assist`; ignored for other types. Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place a call or answer one itself — a campaign, an outbound caller ID, a dispatched call, an eval; a number's inbound dispatch rule accepts one; the body carries `agent_type` and `agent_id`), `ASSIST_FLEET_NOT_CONFIGURED` (422 on a dispatch rule naming a Voice Assist agent in a project whose LiveKit has no Voice Assist listener), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `INVALID_CUSTOMER_TIMEZONE` (400, `customer_timezone` is not a time zone name; the body carries the value), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503), `REGION_PROFILE_CONFLICT` (503), `LLM_SERVICE_TIER_UNAVAILABLE` (422, an agent's processing speed is not offered by its model or not enabled for the organization; `reason` says which) and `AUTH_UPSTREAM_UNAVAILABLE` (503 on any endpoint, with `Retry-After`: the credential could not be checked right now; it was not rejected and the request was not carried out). AgentModelConfig: type: object additionalProperties: true description: >- 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. properties: llm_service_tier: type: string enum: - standard - fast - ultrafast nullable: true description: >- Processing speed: how quickly OpenAI serves the agent's language model, for GPT models. `standard` is OpenAI's regular processing. `fast` skips OpenAI's queue, so each reply starts sooner; its tokens cost twice the standard price. `ultrafast` also writes the reply faster; its tokens cost six times the standard price. Leave the key out for the platform default: Fast on every GPT model that offers it, otherwise Standard. `fast` is that default, so it is not stored: sending `fast` or `null` is the same as leaving the key out, and a later read omits the key. Every GPT model offers Standard. Fast is offered by every GPT model except the nano models; Ultrafast only by GPT-6.1 Sol (`gpt-6.1-sol`) and GPT-6 Astra (`gpt-6-astra`). Models of other providers have no processing speed. `GET /v1/projects/{projectId}/agents/chained-options` lists, on each model, the speeds your organization can choose (`service_tiers`). Fast and Ultrafast are enabled per organization: Fast is on for every organization, and Clarity turns Ultrafast on when you ask for it. Saving a speed the model does not offer, or one your organization does not have, is refused with 422 `LLM_SERVICE_TIER_UNAVAILABLE` (`reason`: `model` or `organization`); a save that changes neither the speed nor the model is not checked again. If a speed is turned off for your organization later, an agent that stores it keeps working on the next slower speed the organization has. On a Voice Assist agent the speed applies to its live suggestions. example: ultrafast llm_thinking_level: deprecated: true description: >- No longer has any effect. Every call now uses the least reasoning its language model accepts, which gives the fastest replies. Older agent versions may still carry the key; saving an agent removes it. A realtime model's thinking setting (`rt_thinking_level`) is unchanged. llm_thinking_budget: type: integer deprecated: true nullable: true description: >- No longer has any effect (see `llm_thinking_level`). Older agent versions may still carry the key; saving an agent removes it. TaskGroup: type: object required: - task - description - fields - steps properties: task: type: string description: Task name (e.g. ticket_creation_workflow) description: type: string fields: additionalProperties: true type: object steps: type: array items: {} completion_message: type: string task_instruction: type: string description: >- When to run this task; used to derive workflow_instructions at runtime AssistConfig: type: object description: >- The assist block of an agent of type `assist`. Versioned with the agent: it is snapshotted into every version, replaced WHOLESALE on PATCH (an omitted key takes its default, never the stored value), and copied by clone / export / import. Null on every other agent type; a block sent for a voice agent is dropped. `kb_collection_id` and `kb_organization_id` are RESOLVED from the project's organization on every write — a client value is ignored. properties: company_context: type: string nullable: true default: null kb_enabled: type: boolean default: false kb_scope: $ref: '#/components/schemas/AssistKbScope' kb_collection_id: type: string nullable: true readOnly: true description: >- The organization's knowledge-base collection, resolved when the agent is saved with the knowledge base on; null when the organization has no articles yet or `kb_enabled` is false. kb_organization_id: type: integer nullable: true readOnly: true description: The organization the collection was resolved for. retrieval_query_chars: type: integer minimum: 200 maximum: 8000 default: 1500 retrieval_limit: type: integer minimum: 1 maximum: 20 default: 5 max_retries: type: integer minimum: 0 maximum: 5 default: 2 max_prompt_tokens: type: integer minimum: 512 nullable: true default: null description: >- Caps assist BELOW the provider's own window; the effective limit is the minimum of the two. hold_audio: $ref: '#/components/schemas/AssistHoldAudio' BackgroundAudioConfig: type: object description: >- Office ambience looped under the call and an optional typing sound while the agent is thinking. Voice agents (chained and realtime) only: dropped from an assist agent's body. `null`, or both switches off, means none; the runtime config then carries no `background_audio` key. additionalProperties: false required: - ambient_enabled - ambient_sound - ambient_volume - thinking_enabled - thinking_volume properties: ambient_enabled: type: boolean ambient_sound: type: string enum: - office_ambience - crowded_room - city_ambience ambient_volume: type: number minimum: 0 maximum: 1 example: 0.3 thinking_enabled: type: boolean thinking_volume: type: number minimum: 0 maximum: 1 example: 0.5 StartToolsConfig: type: object description: >- Up to three http lookup tools the agent runs as soon as the call starts, before the first model turn. The greeting may speak the visible values they store as `{{ data["session."] }}`; it then waits up to `budget_ms` and speaks the fallback when any value is missing. `null`, or no tools, means none. Voice agents only: dropped from an assist agent's body. additionalProperties: false required: - tools properties: tools: type: array minItems: 1 maxItems: 3 items: type: object additionalProperties: false required: - name properties: name: type: string description: Name of an attached http tool with no required parameters. confirmed_read_only: type: boolean description: Required true for a tool whose method is not GET or HEAD. budget_ms: type: integer minimum: 500 maximum: 4000 default: 1500 fallback_greeting: type: string description: >- Required when the greeting uses start-tool values. Must not use them itself. fallback_greetings: type: object additionalProperties: type: string description: >- Per `multi_language.languages[].label`, for each language greeting that uses start-tool values. ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. A refused processing speed answers with `error` and `code` both `LLM_SERVICE_TIER_UNAVAILABLE` and the fields `path`, `reason`, `tier`, `provider` and `model`. properties: error: type: string code: type: string description: >- A machine-readable code, on the failures that carry one: `LLM_SERVICE_TIER_UNAVAILABLE` for a processing speed the agent cannot use. message: type: string path: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: the refused field, `agent_model_config.llm_service_tier`. reason: type: string enum: - model - organization description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: `model` when the language model does not offer the speed (or the value is not a speed at all), `organization` when your organization does not have it. tier: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the refused value, as text. provider: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model provider. model: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model. issues: type: array items: type: object properties: path: type: string description: Dotted path of the offending field code: type: string message: type: string details: type: array items: {} AssistKbScope: nullable: true description: >- Which articles retrieval may use. Only meaningful with `kb_enabled: true` (refused otherwise, 422). A scope naming collections outside the project's organization is refused at write time (Principle I). oneOf: - type: object required: - all_articles properties: all_articles: type: boolean enum: - true - type: object required: - article_ids properties: article_ids: type: array minItems: 1 items: minimum: 1 type: integer - type: object required: - collection_ids properties: collection_ids: type: array minItems: 1 items: type: string AssistHoldAudio: type: object additionalProperties: false description: >- What a caller waiting for a human agent hears in a Voice Assist call: a greeting with a recording notice, then hold music on a loop until an agent joins; when the agent drops out of the call, a pause, then a short "your agent will be right back" message, then music again. Everything stops as soon as an agent joins, and none of it is in the call recording or the transcript. Every key is optional on write; an omitted key takes its default, and an agent saved before this setting existed behaves as the defaults (hold audio on). The phrases are spoken in the agent's primary language with the voice in `agent_model_config` (`tts_provider`, `tts_model`, `tts_dialect`, `tts_voice`), or the language's default voice when none is set. A change reaches calls after the agent is published. properties: enabled: type: boolean default: true description: >- Whether the caller hears hold audio at all. When false the caller waits in silence (a phone caller hears ringing until an agent answers); `agent_wait_seconds` still applies. greeting: $ref: '#/components/schemas/AssistHoldPhrase' agent_dropped: $ref: '#/components/schemas/AssistHoldPhrase' pause_seconds: type: integer minimum: 0 maximum: 60 default: 5 description: >- Seconds after an agent left the call before the "agent dropped out" message plays. An agent back within the pause stops it from playing. agent_wait_seconds: type: integer minimum: 10 maximum: 600 default: 60 description: >- Seconds the call waits for an agent who left it before the call ends. AssistHoldPhrase: type: object additionalProperties: false description: >- One hold phrase: `greeting` (the greeting with the recording notice, spoken once when the caller starts waiting) or `agent_dropped` (spoken once after an agent dropped out). Whether it plays is decided by the nearest of three levels: this agent's `choice`, then your organization's setting, then the platform's. properties: choice: type: string enum: - default - 'on' - 'off' default: default description: >- `default` follows your organization's setting for the phrase; `on` and `off` override it for this agent. text: type: string nullable: true minLength: 1 maxLength: 500 default: null description: >- This agent's own wording, in its primary language (surrounding spaces are trimmed; an empty text is refused). `null` uses your organization's text for that language, else the platform's. responses: Unauthorized: description: >- No credential was sent, or the API key is invalid or revoked. A key that could not be checked at all answers 503 `AUTH_UPSTREAM_UNAVAILABLE` instead (see Errors). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token NotFound: description: No such resource on this project content: application/json: schema: $ref: '#/components/schemas/Error' AgentSaveValidationFailed: description: >- The request failed validation: `error` lists each problem prefixed with the field it concerns, and `issues` carries the same information per field. Or `agent_model_config.llm_service_tier` names a processing speed this agent cannot use (`code: LLM_SERVICE_TIER_UNAVAILABLE`): `reason` is `model` when the agent's model does not offer it and `organization` when your organization does not have it; `tier`, `provider` and `model` say which. Nothing was saved. content: application/json: schema: $ref: '#/components/schemas/ValidationError' examples: invalidField: summary: A field failed validation value: 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 serviceTierUnavailable: summary: The processing speed is not available value: error: LLM_SERVICE_TIER_UNAVAILABLE code: LLM_SERVICE_TIER_UNAVAILABLE message: >- Processing speed "ultrafast" is not enabled for this organization; ask a Clarity administrator to enable it, or choose another speed. path: agent_model_config.llm_service_tier reason: organization tier: ultrafast provider: openai model: gpt-6.1-sol securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.