> ## 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. # Publish the draft > Makes the agent's draft the live version: new calls use it from now on. The previously published version becomes `outdated` and stays available for rollback (`POST .../versions/{versionId}/republish`). The draft is validated in full first; a draft that fails is refused with 422 and nothing changes. No request body. Needs the publish permission, which organization API keys carry. ## OpenAPI ````yaml /api-reference/voice-openapi.json post /v1/projects/{projectId}/agents/{id}/publish openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: Voice agents, outbound calls, conversations, campaigns, 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. paths: /v1/projects/{projectId}/agents/{id}/publish: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/AgentId' post: tags: - Agents summary: Publish the draft description: >- Makes the agent's draft the live version: new calls use it from now on. The previously published version becomes `outdated` and stays available for rollback (`POST .../versions/{versionId}/republish`). The draft is validated in full first; a draft that fails is refused with 422 and nothing changes. No request body. Needs the publish permission, which organization API keys carry. operationId: publishAgent responses: '200': description: >- The draft is now live. `warnings` is present only when the agent's language model could not be confirmed as currently available; the publish still succeeded. content: application/json: schema: $ref: '#/components/schemas/PublishVersionResponse' example: publishedVersion: id: 0d4e5f60-1a2b-4c3d-9e8f-7a6b5c4d3e21 agent_id: 3f0c6a52-8d7e-4b8a-9a43-0f2b5c1e9d11 version_number: 4 status: published created_at: 1760090000000 created_by: org-token:42 first_published_at: 1760093600000 published_at: 1760093600000 published_by: org-token:42 greeting_message: >- Hello! You've reached Acme billing. What can I do for you today? tools_snapshot: [] dictionaries_snapshot: [] outdatedVersion: id: 9a8b7c6d-1234-4f56-8a90-abcdef012345 agent_id: 3f0c6a52-8d7e-4b8a-9a43-0f2b5c1e9d11 version_number: 3 status: outdated created_at: 1760000000000 created_by: org-token:42 first_published_at: 1760000000000 published_at: 1760000000000 published_by: org-token:42 tools_snapshot: [] dictionaries_snapshot: [] '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`), or the agent is a Voice Assist agent and your organization does not have Voice Assist. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- The agent has no draft to publish (`error: no_draft_to_publish`), or the project or agent does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: no_draft_to_publish message: No draft to publish '422': description: >- The draft's configuration is not valid (`error: schema_validation_failed`); `message` names each problem and `details` locates it. Nothing was published. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: schema_validation_failed message: 'agent_model_config.tts_dialect: required for ar' details: - path: agent_model_config.tts_dialect message: required for ar components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id AgentId: name: id in: path required: true schema: type: string description: Agent id schemas: PublishVersionResponse: type: object required: - publishedVersion properties: publishedVersion: $ref: '#/components/schemas/AgentVersion' outdatedVersion: allOf: - $ref: '#/components/schemas/AgentVersion' nullable: true description: >- The version that was live before, now `outdated`; `null` when there was none. warnings: type: array description: >- Present only when there is something to report. The publish succeeded. items: type: object properties: code: type: string description: '`llm_model_unavailable` or `llm_model_unverified`.' path: type: string provider: type: string model: type: string message: type: string reason: type: string 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 or take a call; the body carries `agent_type` and `agent_id`), `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), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503) and `REGION_PROFILE_CONFLICT` (503). ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. properties: error: type: string message: type: string 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: {} AgentVersion: description: >- The full configuration of one agent version, with the tools and dictionaries attached to it as they were when the version was saved. Fields not listed here may also be present. properties: agent_engine: type: string agent_id: type: string agent_model_config: additionalProperties: true nullable: true type: object agent_type: type: string allow_language_switch: type: boolean builtin_tools: type: array items: type: string created_at: type: integer created_by: type: string dictionaries_snapshot: description: Frozen dictionary definitions bound to this version, sorted by ord. items: properties: description: type: string nullable: true id: type: string name: type: string ord: type: integer terms: additionalProperties: true type: object required: - id - name - terms - ord type: object type: array dynamic_prompt: type: boolean first_published_at: type: integer nullable: true goodbye_message: type: string nullable: true greeting_message: type: string hold_phrases_snapshot: description: >- Frozen Hold Phrase Set definitions bound to this version, sorted by ord. items: properties: description: type: string nullable: true id: type: string name: type: string ord: type: integer phrases: additionalProperties: type: array items: type: string type: object required: - id - name - phrases - ord type: object type: array id: type: string language_controls_enabled: type: boolean preferred_language: type: string nullable: true published_at: type: integer nullable: true published_by: type: string nullable: true sheet_refs: additionalProperties: type: string type: object status: enum: - draft - published - outdated type: string task_groups: items: additionalProperties: true type: object nullable: true type: array task_prompt_json: additionalProperties: true nullable: true type: object tools_instructions: additionalProperties: true nullable: true type: object tools_snapshot: description: Frozen tool definitions bound to this version, sorted by sort_order. items: properties: async_config: additionalProperties: false description: >- per-tool non-blocking execution. Absent/null means the tool is synchronous and behaves exactly as before the feature. Rejected on builtin tools (end_call / connect_to_human / get_dtmf). Chained agents only: realtime agents accept the block but ignore it at runtime in v1. nullable: true properties: ack_message: description: >- Spoken before the wait begins so the caller is never left unacknowledged. Delivered through the model, not read verbatim. Null falls back to hold_message. nullable: true type: string ack_messages: additionalProperties: type: string description: >- Per-language acknowledgements keyed by multi_language label. nullable: true type: object cancellable: default: false description: >- Whether the caller may abandon a run in progress. Enabling it on any tool exposes two extra call-management tools to the model. type: boolean enabled: description: Master switch; when false every other field is inert. type: boolean filler_delay_ms: default: 5000 description: Continuous session idle required before each filler play. minimum: 0 type: integer filler_interval_ms: description: Gap between plays. Null plays at most once. minimum: 1 nullable: true type: integer filler_max_plays: description: >- Cap on filler plays. Requires filler_interval_ms — a cap with no interval can never be reached and is rejected at save and publish. minimum: 1 nullable: true type: integer filler_phrases: description: >- Idle-gap filler pool. Null falls back to hold_messages / hold_message / the agent-level Hold Phrases library. items: type: string nullable: true type: array filler_phrases_by_language: additionalProperties: type: array items: type: string nullable: true type: object max_lifetime_ms: default: 300000 description: >- Job deadline. Bounds both the callback token's validity and the caller-facing timeout. maximum: 900000 minimum: 1000 type: integer on_duplicate: default: reject description: >- What happens when the model re-calls this tool while it is still running. Defaults to reject so a caller repeating themselves cannot double-submit a booking or payment. enum: - allow - reject type: string required: - enabled type: object configs: additionalProperties: true type: object description: type: string hold_message: type: string nullable: true id: type: string name: type: string parameter_mapping: additionalProperties: true nullable: true type: object parameters: additionalProperties: true type: object session: $ref: '#/components/schemas/ToolSession' sort_order: type: integer type: type: string required: - id - name - type - configs - parameters - sort_order type: object type: array tts_director_prompt: type: string nullable: true version_number: minimum: 1 type: integer required: - id - agent_id - version_number - status - created_at - created_by - tools_snapshot - dictionaries_snapshot type: object ToolSession: type: object nullable: true additionalProperties: false description: >- The tool's part in the call-scoped caller authentication session. Null means the tool takes no part. A non-null `verification` makes it a verification tool and carries the verification policy; caller authentication is on for an agent exactly when an attached tool verifies the caller or requires a verified caller. On PATCH, an absent key keeps the stored value and an explicit null clears it. properties: requires_verified_caller: type: boolean description: >- The runtime refuses the tool until a verification tool verified the caller. stores: type: array maxItems: 20 items: type: object additionalProperties: false required: - from - as - visibility properties: from: type: string description: Dot path into the JSON response. as: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: Session name, referenced as {{session.}}. visibility: type: string enum: - private - visible verification: type: object nullable: true additionalProperties: false properties: success: type: object additionalProperties: false properties: status_in: type: array items: type: integer minimum: 100 maximum: 599 field: type: string equals: oneOf: - type: string - type: number - type: boolean ttl_from: type: string max_attempts: type: integer minimum: 1 maximum: 10 description: >- Failed verifications allowed per call (default 3). With several verifiers on an agent, the smallest wins. on_exhausted: type: string enum: - end_call - transfer - continue description: >- What happens when the attempts run out (default end_call). Taken from the verifier with the smallest max_attempts. `transfer` needs a connect_to_human tool attached to the agent. unreachable_counts_as_failure: type: boolean description: >- Count a timeout / connection error / 5xx as a failed attempt (default false; true on any verifier wins). default_ttl_s: type: integer nullable: true minimum: 60 maximum: 86400 description: >- Session lifetime when the response gives none (null - until the call ends). The smallest non-null value wins. responses: Unauthorized: description: No credential was sent, or the API key is invalid or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token 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.