> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Publish the draft > Makes the draft the live version, numbered v1, v2, ... Fails with 409 if the draft was edited after expectedRevision, if another version was published since the draft started, or if it changes nothing; with 400 and the issues if the version cannot run. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/agent/{agentId}/draft/publish openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Phone Number - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Analytics - name: Dashboard - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/agent/{agentId}/draft/publish: post: tags: - Agent summary: Publish the draft description: >- Makes the draft the live version, numbered v1, v2, ... Fails with 409 if the draft was edited after expectedRevision, if another version was published since the draft started, or if it changes nothing; with 400 and the issues if the version cannot run. operationId: postV1AgentByAgentIdDraftPublish parameters: - in: path name: agentId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/PublishAgentDraftInput' responses: '200': description: The published version. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AgentVersionResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: Conflict '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.agentDraft.publish('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { expectedRevision: 1, }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.agent_draft.publish( agent_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", expected_revision=1, ) print(response.data) components: schemas: PublishAgentDraftInput: type: object properties: expectedRevision: type: integer minimum: 1 description: The draft revision you reviewed. summary: type: string minLength: 1 maxLength: 500 description: What changed. required: - expectedRevision AgentVersionResponse: type: object properties: id: type: string format: uuid agentId: type: string format: uuid status: type: string enum: - DRAFT - PUBLISHED - DISCARDED description: DRAFT while being edited, PUBLISHED once it has been live. versionNumber: type: - integer - 'null' description: v1, v2, ... assigned on publish; null on a draft. revision: type: integer description: >- Increases with every edit to a draft. Send it back as expectedRevision when you publish. baseVersionId: type: - string - 'null' format: uuid description: The published version a draft started from. restoredFromVersionId: type: - string - 'null' format: uuid description: Set when this version restores an older one. summary: type: - string - 'null' description: What changed, written on publish. createdByType: type: string enum: - USER - API - CONFIG - AUTOIMPROVE - INTEGRATION - SYSTEM createdById: type: - string - 'null' format: uuid publishedAt: type: - string - 'null' description: ISO 8601. publishedByType: type: - string - 'null' enum: - USER - API - CONFIG - AUTOIMPROVE - INTEGRATION - SYSTEM publishedById: type: - string - 'null' format: uuid createdAt: type: string description: ISO 8601. updatedAt: type: string description: ISO 8601. modalities: type: array items: type: string enum: - call - chat description: Whether the agent takes calls, chats, or both. language: type: - string - 'null' description: ISO 639-1, e.g. en. firstMessageMode: type: - string - 'null' enum: - SPEAK_TEXT - PLAY_AUDIO - WAIT_FOR_CALLER firstMessage: type: - string - 'null' description: What the agent says first, with firstMessageMode SPEAK_TEXT. firstMessageAudioUrl: type: - string - 'null' description: The audio a call opens with, with firstMessageMode PLAY_AUDIO. llmProvider: type: - string - 'null' enum: - OPENAI - ANTHROPIC - GOOGLE - XAI - ULTRAVOX - AWS - ELEVENLABS llmModel: type: - string - 'null' description: Any model id the provider accepts. One model serves every speaker. llmTemperature: type: - number - 'null' description: 0 to 2. llmMaxTokens: type: - integer - 'null' llmBackendModel: type: - string - 'null' description: 'OpenAI Live models only: the text model they delegate to.' llmVoice: type: - string - 'null' description: 'Speech-to-speech models only: the model''s own voice.' sttProvider: type: - string - 'null' enum: - DEEPGRAM - OPENAI_WHISPER - SPEECHMATICS - ASSEMBLYAI - ELEVENLABS sttModel: type: - string - 'null' sttKeyterms: type: array items: type: string description: Words and phrases the transcriber should listen for. sttSmartFormat: type: - boolean - 'null' sttEndpointingMs: type: - integer - 'null' sttTurnDetection: type: - string - 'null' enum: - pipeline - provider interruptionMode: type: - string - 'null' enum: - ALLOW - BLOCK vadStartSecs: type: - number - 'null' vadStopSecs: type: - number - 'null' callMaxDurationSeconds: type: - integer - 'null' callSilenceTimeoutSeconds: type: - integer - 'null' idleTimeoutSeconds: type: - integer - 'null' idleMaxCount: type: - integer - 'null' idleMessages: type: array items: type: string endDetectionPhrases: type: array items: type: string description: >- Phrases that end the call when the caller says them, matched anywhere in what they say. endDetectionReasons: type: array items: type: string description: When the agent may decide to end the call itself. endCallGoodbyeMessage: type: - string - 'null' backgroundNoise: type: - string - 'null' enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - CONSTRUCTION - CRYING_BABY - DRIVING - LIBRARY - OFFICE - THUNDERSTORM - TRAIN description: A background preset. backgroundNoiseUrl: type: - string - 'null' description: A custom background recording, instead of a preset. backgroundNoiseVolume: type: - number - 'null' description: 0 to 1. chatMaxDurationSeconds: type: - integer - 'null' chatInactivityTimeoutSeconds: type: - integer - 'null' subAgents: type: array items: $ref: '#/components/schemas/AgentVersionSubAgent' description: >- The main agent (key `main`) first, then the sub-agents it can hand the call to. issues: type: array items: $ref: '#/components/schemas/AgentVersionIssue' description: >- Why this version cannot run; empty when it can be published. Returned when reading one version. required: - id - agentId - status - versionNumber - revision - baseVersionId - restoredFromVersionId - summary - createdByType - createdById - publishedAt - publishedByType - publishedById - createdAt - updatedAt - modalities - language - firstMessageMode - firstMessage - firstMessageAudioUrl - llmProvider - llmModel - llmTemperature - llmMaxTokens - llmBackendModel - llmVoice - sttProvider - sttModel - sttKeyterms - sttSmartFormat - sttEndpointingMs - sttTurnDetection - interruptionMode - vadStartSecs - vadStopSecs - callMaxDurationSeconds - callSilenceTimeoutSeconds - idleTimeoutSeconds - idleMaxCount - idleMessages - endDetectionPhrases - endDetectionReasons - endCallGoodbyeMessage - backgroundNoise - backgroundNoiseUrl - backgroundNoiseVolume - chatMaxDurationSeconds - chatInactivityTimeoutSeconds - subAgents description: >- One version of a Roark-hosted agent's configuration. Null settings use the runtime default. ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message AgentVersionSubAgent: type: object properties: key: type: string description: '`main` for the main agent; otherwise letters, digits, `_` or `-`.' name: type: - string - 'null' description: How the agent refers to this speaker. systemPrompt: type: - string - 'null' description: The speaker's prompt. isInitial: type: boolean description: The call opens as this sub-agent instead of the main agent. ttsProvider: type: - string - 'null' enum: - CARTESIA - ELEVENLABS - OPENAI - RIME ttsModel: type: - string - 'null' ttsVoiceId: type: - string - 'null' description: Any voice id the provider accepts, including your own voices. ttsSpeed: type: - number - 'null' description: 0.5 to 2. ttsStability: type: - number - 'null' description: 0 to 1, ElevenLabs. ttsSimilarityBoost: type: - number - 'null' description: 0 to 1, ElevenLabs. tools: type: array items: $ref: '#/components/schemas/AgentVersionTool' handoffs: type: array items: $ref: '#/components/schemas/AgentVersionHandoff' required: - key - name - systemPrompt - isInitial - ttsProvider - ttsModel - ttsVoiceId - ttsSpeed - ttsStability - ttsSimilarityBoost - tools - handoffs description: >- A speaker in the conversation. On a sub-agent, null voice settings use the main agent's. AgentVersionIssue: type: object properties: field: type: string description: The setting the issue is about. message: type: string required: - field - message description: Something that stops a version from running. AgentVersionTool: type: object properties: toolDefinitionId: type: string format: uuid pinnedVersion: type: - integer - 'null' description: >- The tool version the agent runs; null runs the tool's latest declared version. required: - toolDefinitionId - pinnedVersion AgentVersionHandoff: type: object properties: to: type: string description: The key of the sub-agent that takes over; `main` for the main agent. description: type: string description: When to hand off, in the words the model is given. once: type: boolean description: At most once per call. history: type: string enum: - SHARED - NONE description: >- SHARED: the new speaker hears the conversation so far. NONE: it starts fresh. note: type: - string - 'null' description: >- Added to the new speaker's prompt at the handoff, such as a warm-transfer brief. required: - to - description - once - history - note securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.