> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish an AI phone agent

> Make an agent’s draft live. Calls that start afterwards use it, and it is recorded as a new version.

Requires the `phone:write` scope.

Send the `revision` you read from [Get draft](https://docs.open.cx/api-reference/phone/get_draft.md) as `expected_revision`. Publishing is all or nothing: either every setting in the draft goes live, or none does.

Refusals carry a `code` beside the `message`, so your code can branch on the reason:

| Status | `code` | Meaning |
| - | - | - |
| `201` | | The draft is live. The response returns the new `version` and the draft's new `revision`. |
| `409` | `draft_stale` | The draft changed after the revision you sent. Read it again, review it and retry. |
| `409` | `number_held` | A phone number in the draft was given to another agent, IVR or interpreter in the meantime. The message names it; free the number or remove it from the draft. |
| `400` | `draft_invalid` | A setting is invalid (for example an inactive workflow, or an instruction or knowledge item the agent can no longer use). Things deleted since they were added to the draft are dropped from it, not refused. |
| `400` | `nothing_to_publish` | The draft has no changes to publish. |

Calls already in progress finish with the settings they started with.

A new agent created with `POST /phone` takes no calls until its first publish.

To put an earlier version live again, use [Publish earlier version](https://docs.open.cx/api-reference/phone/publish_version.md). The draft is reset to that version too, so its unpublished changes are discarded.


## OpenAPI

````yaml post /phone/{phone_agent_id}/publish
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /phone/{phone_agent_id}/publish:
    post:
      summary: Publish an AI phone agent
      description: >-
        Make the draft live: real calls use it from the next call on, and it is
        recorded as a new version. Refused with 409 when the draft changed after
        the revision you send, or when one of its phone numbers was given to
        something else meanwhile (the message names it); with 400 when a setting
        is invalid or nothing changed.
      operationId: publishPhoneAgent
      parameters:
        - schema:
            type: string
          in: path
          name: phone_agent_id
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishPhoneAgentDraftDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneAgentPublishResultDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    PublishPhoneAgentDraftDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/PublishPhoneAgentDraftDtoInput'
      type: object
      properties:
        expected_revision:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            The draft revision the publisher reviewed. Publishing refuses a
            newer draft.
      required:
        - expected_revision
    PhoneAgentPublishResultDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/PhoneAgentPublishResultDto'
      type: object
      properties:
        agent_id:
          type: string
        version:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        revision:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - agent_id
        - version
        - revision
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.