--- title: "Get an agent's draft" method: GET path: "/v1/agent/{agentId}/draft" tags: ["Agent"] --- # Get an agent's draft `GET /v1/agent/{agentId}/draft` ## Request - Base URL: `https://api.roark.ai` - URL: `https://api.roark.ai/v1/agent/{agentId}/draft` - Auth: HTTP bearer The agent's open draft, with the issues that would stop it from being published. ## Path parameters - `agentId` string, uuid, required ## Response `200` The draft. - 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 - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `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/get.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)