--- title: "Publish the draft" method: POST path: "/v1/agent/{agentId}/draft/publish" tags: ["Agent"] --- # Publish the draft `POST /v1/agent/{agentId}/draft/publish` ## Request - Base URL: `https://api.roark.ai` - URL: `https://api.roark.ai/v1/agent/{agentId}/draft/publish` - Auth: HTTP bearer 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. ## Path parameters - `agentId` string, uuid, required ## Request body - PublishAgentDraftInput - `expectedRevision` integer, required: The draft revision you reviewed. - `summary` string: What changed. ## Response `200` The published version. - object - `data` AgentVersionResponse, required: One version of a Roark-hosted agent's configuration. Null settings use the runtime default. - `id` string, uuid, required - `agentId` string, uuid, required - `status` 'DRAFT' | 'PUBLISHED' | 'DISCARDED', required: DRAFT while being edited, PUBLISHED once it has been live. - `versionNumber` integer, nullable, required: v1, v2, ... assigned on publish; null on a draft. - `revision` integer, required: Increases with every edit to a draft. Send it back as expectedRevision when you publish. - `baseVersionId` string, uuid, nullable, required: The published version a draft started from. - `rolledBackFromVersionId` string, uuid, nullable, required: Set when this version rolls the agent back to an older one. - `summary` string, nullable, required: What changed, written on publish. - `createdByType` 'USER' | 'API' | 'CONFIG' | 'AUTOIMPROVE' | 'INTEGRATION' | 'SYSTEM', required - `createdById` string, uuid, nullable, required - `publishedAt` string, nullable, required: ISO 8601. - `publishedByType` 'USER' | 'API' | 'CONFIG' | 'AUTOIMPROVE' | 'INTEGRATION' | 'SYSTEM', nullable, required - `publishedById` string, uuid, nullable, required - `createdAt` string, required: ISO 8601. - `updatedAt` string, required: ISO 8601. - `modalities` string[], required: Whether the agent takes calls, chats, or both. - `language` string, nullable, required: ISO 639-1, e.g. en. - `firstMessageMode` 'SPEAK_TEXT' | 'PLAY_AUDIO' | 'WAIT_FOR_CALLER', nullable, required - `firstMessage` string, nullable, required: What the agent says first, with firstMessageMode SPEAK_TEXT. - `firstMessageAudioUrl` string, nullable, required: The audio a call opens with, with firstMessageMode PLAY_AUDIO. - `interruptionMode` 'ALLOW' | 'BLOCK', nullable, required - `vadStartSecs` number, nullable, required - `vadStopSecs` number, nullable, required - `callMaxDurationSeconds` integer, nullable, required - `callSilenceTimeoutSeconds` integer, nullable, required - `idleTimeoutSeconds` integer, nullable, required - `idleMaxCount` integer, nullable, required - `idleMessages` string[], required - `endDetectionPhrases` string[], required: Phrases that end the call when the caller says them, matched anywhere in what they say. - `endDetectionReasons` string[], required: When the agent may decide to end the call itself. - `endCallGoodbyeMessage` string, nullable, required - `backgroundNoise` 'NONE' | 'AIRPORT' | 'CHILDREN_PLAYING' | 'CITY' | 'COFFEE_SHOP' | 'CONSTRUCTION' | 'CRYING_BABY' | 'DRIVING' | 'LIBRARY' | 'OFFICE' | 'THUNDERSTORM' | 'TRAIN', nullable, required: A background preset. - `backgroundNoiseUrl` string, nullable, required: A custom background recording, instead of a preset. - `backgroundNoiseVolume` number, nullable, required: 0 to 1. - `chatMaxDurationSeconds` integer, nullable, required - `chatInactivityTimeoutSeconds` integer, nullable, required - `subAgents` AgentVersionSubAgent[], required: The main agent (key `main`) first, then the sub-agents it can hand the call to. - `key` string, required: `main` for the main agent; otherwise letters, digits, `_` or `-`. - `name` string, nullable, required: How the agent refers to this speaker. - `systemPrompt` string, nullable, required: The speaker's prompt. - `isInitial` boolean, required: The call opens as this sub-agent instead of the main agent. - `modelConfigs` AgentModelConfig[], required: Up to three, in the order a call tries them. Empty on a sub-agent: it runs on the main agent's. The main agent needs one. - union: A model setup a speaker runs on. The call moves to the next config once this one has nothing left to try. A field of the other type is refused. - AgentCascadeModelConfig: A transcriber, a text model and a voice. A component that fails during a call moves to its next entry; the others stay. - `type` 'CASCADE', required - `stt` AgentSttConfig[], required: One to three transcribers, in the order a call tries them. - … - `llm` AgentLlmConfig[], required: One to three text models, in the order a call tries them. - … - `tts` AgentTtsConfig[], required: One to three voices, in the order a call tries them. - … - AgentSpeechToSpeechModelConfig: One model that hears the caller and speaks with its own voice. - `type` 'SPEECH_TO_SPEECH', required - `speechToSpeech` AgentSpeechToSpeechConfig, required: A model that hears the caller and speaks with its own voice. Null settings use the default. - … - `tools` AgentVersionTool[], required - `toolDefinitionId` string, uuid, required - `pinnedVersion` integer, nullable, required: The tool version the agent runs; null runs the tool's latest declared version. - `handoffs` AgentVersionHandoff[], required - `to` string, required: The key of the sub-agent that takes over; `main` for the main agent. - `description` string, required: When to hand off, in the words the model is given. - `once` boolean, required: At most once per call. - `history` 'SHARED' | 'NONE', required: SHARED: the new speaker hears the conversation so far. NONE: it starts fresh. - `note` string, nullable, required: Added to the new speaker's prompt at the handoff, such as a warm-transfer brief. - `issues` AgentVersionIssue[]: Why this version cannot run; empty when it can be published. Returned when reading one version. - `field` string, required: The setting the issue is about. - `message` string, required ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `500`: Internal Server Error ## Changes > 188 revisions in range; 1 not diffed. - **2026-10-30** `eb601d4577cd`: 18 breaking, 1 info - removed the required property `data/llmBackendModel` from the response with the `200` status - removed the required property `data/llmMaxTokens` from the response with the `200` status - removed the required property `data/llmModel` from the response with the `200` status - removed the required property `data/llmProvider` from the response with the `200` status - …15 more - **2026-10-29** `57a93528ce77`: 1 breaking, 1 info - removed the required property `data/restoredFromVersionId` from the response with the `200` status - added the required property `data/rolledBackFromVersionId` to the response with the `200` status - **2026-10-28** `d82d66648ffd`: 1 info - endpoint added [Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/agent/:agentId/draft/publish/post.md) --- [API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)