> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Create a voice test draft

POST https://api.runtype.com/v1/agents/{id}/voice/drafts
Content-Type: application/json

Hold an unsaved agent definition for about 15 minutes so a browser voice call can run it instead of the saved agent, without saving or publishing. The body is merged onto the saved agent exactly as `PUT /agents/{id}` would merge it, and nothing is written to the agent. Runtype agents only; the merged config must have voice enabled.

Reference: https://docs.runtype.com/api-reference/runtype-api/agents/create-a-voice-test-draft

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `id` (string, required)

### Body (application/json)

This endpoint expects a CreateVoiceAgentDraftRequest.

- `config` (CreateVoiceAgentDraftRequestConfig, optional)
- `description` (string, optional)
- `name` (string, optional)

## Response

### 201

Draft created

- `draftId` (string, required) — Pass as the `agentDraftId` query parameter when opening `/ws/agents/{id}/voice` to run this draft.
- `expiresAt` (string, required) — After this time the draft can no longer start a call. A call already running keeps it.

## Errors

### 400 Bad Request Error

Invalid agent ID or draft configuration

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 404 Not Found Error

Agent not found

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 422 Unprocessable Entity Error

The agent is not a Runtype agent, or the draft has voice disabled

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 503 Service Unavailable Error

Draft storage is unavailable in this environment

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

## Types

### CreateVoiceAgentDraftRequestConfig

- `advisor` (CreateVoiceAgentDraftRequestConfigAdvisor, optional, nullable)
- `artifacts` (CreateVoiceAgentDraftRequestConfigArtifacts, optional)
- `busyMessageRouting` (CreateVoiceAgentDraftRequestConfigBusyMessageRouting, optional)
- `contextManagement` (CreateVoiceAgentDraftRequestConfigContextManagement, optional)
- `durability` (CreateVoiceAgentDraftRequestConfigDurability, optional)
- `errorHandling` (CreateVoiceAgentDraftRequestConfigErrorHandling, optional)
- `frequencyPenalty` (double, optional)
- `loggingPolicy` (enum, optional)
  - Allowed values: `default`, `on`, `off`
- `loopConfig` (CreateVoiceAgentDraftRequestConfigLoopConfig, optional)
- `maxTokens` (integer, optional, nullable)
- `memory` (CreateVoiceAgentDraftRequestConfigMemory, optional)
- `model` (string, optional)
- `piiRedaction` (enum, optional)
  - Allowed values: `default`, `off`, `redact`
- `presencePenalty` (double, optional)
- `reasoning` (CreateVoiceAgentDraftRequestConfigReasoning, optional)
- `sandbox` (CreateVoiceAgentDraftRequestConfigSandbox, optional)
- `seed` (integer, optional)
- `state` (CreateVoiceAgentDraftRequestConfigState, optional)
- `systemPrompt` (string, optional)
- `temperature` (double, optional)
- `temporal` (CreateVoiceAgentDraftRequestConfigTemporal, optional)
- `tenancyStrategy` (CreateVoiceAgentDraftRequestConfigTenancyStrategy, optional)
- `tools` (CreateVoiceAgentDraftRequestConfigTools, optional)
- `topK` (integer, optional)
- `topP` (double, optional)
- `voice` (CreateVoiceAgentDraftRequestConfigVoice, optional)

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### CreateVoiceAgentDraftRequestConfigAdvisor

- `model` (string, required)
- `systemPrompt` (string, optional)

### CreateVoiceAgentDraftRequestConfigArtifacts

- `enabled` (boolean, required)
- `types` (list of enum, required)
  - Allowed values: `markdown`, `component`

### CreateVoiceAgentDraftRequestConfigBusyMessageRouting

- `classifierModel` (string, optional)
- `mode` (enum, optional)
  - Allowed values: `enforced`, `off`

### CreateVoiceAgentDraftRequestConfigContextManagement

- `compaction` (CreateVoiceAgentDraftRequestConfigContextManagementCompaction, optional)
- `toolResults` (CreateVoiceAgentDraftRequestConfigContextManagementToolResults, optional)

### CreateVoiceAgentDraftRequestConfigDurability

- `forced` (enum, optional)
  - Allowed values: `durable`, `in_process`
- `maxBudgetMs` (integer, optional, nullable)
- `watchLeaseMs` (integer, optional, nullable)

### CreateVoiceAgentDraftRequestConfigErrorHandling

- `onError` (enum, required)
  - Allowed values: `fail`, `continue`, `fallback`
- `fallbacks` (list of CreateVoiceAgentDraftRequestConfigErrorHandlingFallbacksItems, optional)
- `triggers` (list of CreateVoiceAgentDraftRequestConfigErrorHandlingTriggersItems, optional)

### CreateVoiceAgentDraftRequestConfigLoopConfig

- `enableReflection` (boolean, optional)
- `maxCost` (double, optional)
- `maxTurns` (integer, optional)
- `reflectionInterval` (integer, optional)
- `treatLengthCutoffAsFailure` (boolean, optional)

### CreateVoiceAgentDraftRequestConfigMemory

- `enabled` (boolean, required)
- `injectSummary` (boolean, optional)
- `pointerScope` (enum, optional)
  - Allowed values: `shared`, `alias`, `version`
- `profileTemplate` (string, optional)

### CreateVoiceAgentDraftRequestConfigReasoning

### CreateVoiceAgentDraftRequestConfigSandbox

- `enabled` (boolean, required)
- `codingAgents` (list of enum, optional) — Coding agents the Sandbox can run as typed sessions. Non-empty adds the agent_session_* tools; empty or absent adds none.
  - Allowed values: `opencode`
- `instanceType` (enum, optional) — Only standard-4 is supported on the hosted Agent Sandbox path; other sizes cannot be enabled.
  - Allowed values: `standard-1`, `standard-2`, `standard-3`, `standard-4`
- `networkAccess` (CreateVoiceAgentDraftRequestConfigSandboxNetworkAccess, optional)
- `persistence` (enum, optional) — Supported: ephemeral or conversation. Named remains parseable for stored configs but cannot be enabled.
  - Allowed values: `ephemeral`, `conversation`, `named`
- `provider` (enum, optional) — Only runtype-sandbox is currently supported. Daytona is retained for stored-config parsing but rejected at authoring/execution.
  - Allowed values: `runtype-sandbox`, `daytona`
- `secretEnv` (map from string to string, optional)
- `setupCommands` (list of string, optional)
- `sleepAfter` (enum, optional)
  - Allowed values: `5m`, `15m`, `30m`, `1h`
- `ttl` (enum, optional)
  - Allowed values: `5m`, `1h`, `24h`, `unlimited`

### CreateVoiceAgentDraftRequestConfigState

- `initial` (map from string to any, optional)
- `mergeStrategy` (enum, optional, default: merge)
  - Allowed values: `replace`, `merge`
- `predictState` (list of CreateVoiceAgentDraftRequestConfigStatePredictStateItems, optional)
- `schema` (map from string to any, optional)

### CreateVoiceAgentDraftRequestConfigTemporal

- `elapsedThresholdSeconds` (integer, optional)
- `groundNow` (boolean, optional)
- `injectElapsed` (boolean, optional)
- `timezone` (string, optional)

### CreateVoiceAgentDraftRequestConfigTenancyStrategy

- `preset` (enum, required)
  - Allowed values: `internal`, `tenant-isolated`, `end-user-isolated`
- `assuranceFloor` (CreateVoiceAgentDraftRequestConfigTenancyStrategyAssuranceFloor, optional)

### CreateVoiceAgentDraftRequestConfigTools

- `approval` (CreateVoiceAgentDraftRequestConfigToolsApproval, optional)
- `codeModeConfig` (CreateVoiceAgentDraftRequestConfigToolsCodeModeConfig, optional, nullable)
- `maxToolCalls` (integer, optional)
- `mcpServers` (list of CreateVoiceAgentDraftRequestConfigToolsMcpServersItems, optional)
- `perToolLimits` (map from string to CreateVoiceAgentDraftRequestConfigToolsPerToolLimits, optional)
- `runtimeTools` (list of CreateVoiceAgentDraftRequestConfigToolsRuntimeToolsItems, optional)
- `subagentConfig` (CreateVoiceAgentDraftRequestConfigToolsSubagentConfig, optional, nullable)
- `toolCallStrategy` (enum, optional)
  - Allowed values: `auto`, `required`, `none`
- `toolConfigs` (map from string to map from string to any, optional)
- `toolIds` (list of string, optional)
- `toolSearch` (CreateVoiceAgentDraftRequestConfigToolsToolSearch, optional, nullable)

### CreateVoiceAgentDraftRequestConfigVoice

- `directTools` (CreateVoiceAgentDraftRequestConfigVoiceDirectTools, optional)
- `disclosure` (boolean, optional)
- `elevenLabs` (CreateVoiceAgentDraftRequestConfigVoiceElevenLabs, optional)
- `enabled` (boolean, optional)
- `endpointing` (CreateVoiceAgentDraftRequestConfigVoiceEndpointing, optional)
- `greeting` (string, optional)
- `interruptionMode` (enum, optional)
  - Allowed values: `none`, `cancel`, `barge-in`
- `language` (string, optional)
- `provider` (string, optional)
- `speech` (CreateVoiceAgentDraftRequestConfigVoiceSpeech, optional)

### CreateVoiceAgentDraftRequestConfigContextManagementCompaction

- `enabled` (boolean, optional)
- `instructions` (string, optional)
- `model` (string, optional)
- `retainRecentTokens` (integer, optional)
- `strategy` (enum, optional)
  - Allowed values: `auto`, `provider_native`, `summary`
- `thresholdRatio` (double, optional)
- `thresholdTokens` (integer, optional)

### CreateVoiceAgentDraftRequestConfigContextManagementToolResults

- `pruneHotWindowTokens` (integer, optional)
- `pruneMode` (enum, optional)
  - Allowed values: `mask`, `off`
- `inlineThresholdChars` (integer, optional, deprecated) — Deprecated and ignored. Tool results are never spilled.

### CreateVoiceAgentDraftRequestConfigErrorHandlingFallbacksItems

### CreateVoiceAgentDraftRequestConfigErrorHandlingTriggersItems

- `type` (enum, required)
  - Allowed values: `error`, `empty-output`

### CreateVoiceAgentDraftRequestConfigReasoning1

- `enabled` (boolean, required)
- `budgetTokens` (integer, optional)
- `effort` (string, optional)
- `includeThoughts` (boolean, optional)
- `reasoningEffort` (enum, optional)
  - Allowed values: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
- `reasoningSummary` (enum, optional)
  - Allowed values: `auto`, `detailed`
- `thinkingBudget` (integer, optional)
- `thinkingLevel` (string, optional)

### CreateVoiceAgentDraftRequestConfigSandboxNetworkAccess

### CreateVoiceAgentDraftRequestConfigStatePredictStateItems

- `stateKey` (string, required)
- `tool` (string, required)
- `toolArgument` (string, required)

### CreateVoiceAgentDraftRequestConfigTenancyStrategyAssuranceFloor

- `endUser` (enum, optional)
  - Allowed values: `asserted`, `verified`
- `tenant` (enum, optional)
  - Allowed values: `asserted`, `verified`

### CreateVoiceAgentDraftRequestConfigToolsApproval

- `require` (CreateVoiceAgentDraftRequestConfigToolsApprovalRequire, required)
- `approver` (enum, optional)
  - Allowed values: `owner`, `end-user`
- `choices` (CreateVoiceAgentDraftRequestConfigToolsApprovalChoices, optional)
- `requestReason` (boolean, optional)
- `timeout` (double, optional)

### CreateVoiceAgentDraftRequestConfigToolsCodeModeConfig

- `toolPool` (list of string, required)
- `description` (string, optional)
- `timeoutMs` (integer, optional)

### CreateVoiceAgentDraftRequestConfigToolsMcpServersItems

- `id` (string, required)
- `url` (string, required)
- `allowedTools` (list of string, optional)
- `auth` (CreateVoiceAgentDraftRequestConfigToolsMcpServersItemsAuth, optional)
- `enabled` (boolean, optional)
- `identityAudiences` (list of string, optional)
- `name` (string, optional)
- `timeout` (double, optional)
- `transport` (enum, optional)
  - Allowed values: `streamable_http`, `rest`

### CreateVoiceAgentDraftRequestConfigToolsPerToolLimits

- `maxCalls` (double, optional)
- `required` (boolean, optional)

### CreateVoiceAgentDraftRequestConfigToolsRuntimeToolsItems

- `config` (map from string to any, required)
- `description` (string, required)
- `name` (string, required)
- `parametersSchema` (map from string to any, required)
- `toolType` (enum, required)
  - Allowed values: `flow`, `custom`, `external`, `local`, `advisor`, `subagent`, `search`
- `hiddenParameterNames` (list of string, optional)
- `idempotent` (boolean, optional)

### CreateVoiceAgentDraftRequestConfigToolsSubagentConfig

- `toolPool` (list of string, required)
- `allowNesting` (boolean, optional)
- `defaultExecutionMode` (enum, optional)
  - Allowed values: `attached`, `detached`
- `defaultMaxTurns` (integer, optional)
- `defaultModel` (string, optional)
- `defaultNotify` (enum, optional)
  - Allowed values: `none`, `narrate`, `react`
- `defaultTimeoutMs` (integer, optional)
- `detachedMaxBudgetMs` (integer, optional)
- `detachedNoProgressBudgetMs` (integer, optional)
- `executionModes` (list of enum, optional)
  - Allowed values: `attached`, `detached`
- `maxSpawnsPerRun` (integer, optional)
- `maxTurnsLimit` (integer, optional)

### CreateVoiceAgentDraftRequestConfigToolsToolSearch

- `alwaysLoaded` (list of string, optional)
- `enabled` (boolean, optional)
- `threshold` (double, optional)

### CreateVoiceAgentDraftRequestConfigVoiceDirectTools

- `enabled` (boolean, optional)
- `model` (string, optional)

### CreateVoiceAgentDraftRequestConfigVoiceElevenLabs

- `modelId` (string, optional)
- `similarity` (double, optional)
- `stability` (double, optional)
- `voiceId` (string, optional)

### CreateVoiceAgentDraftRequestConfigVoiceEndpointing

- `strategy` (enum, required)
  - Allowed values: `provider_vad`, `server_vad`, `client_commit`, `manual`
- `silenceMs` (integer, optional)

### CreateVoiceAgentDraftRequestConfigVoiceSpeech

- `mode` (enum, required)
  - Allowed values: `pipeline`, `speech_to_speech`, `provider_managed`
- `synthesizer` (CreateVoiceAgentDraftRequestConfigVoiceSpeechSynthesizer, required)
- `transcriber` (CreateVoiceAgentDraftRequestConfigVoiceSpeechTranscriber, required)

### CreateVoiceAgentDraftRequestConfigErrorHandlingFallbacksItems0

- `type` (enum, required)
  - Allowed values: `retry`
- `delay` (integer, optional)

### CreateVoiceAgentDraftRequestConfigErrorHandlingFallbacksItems1

- `model` (string, required)
- `type` (enum, required)
  - Allowed values: `model`
- `delay` (integer, optional)
- `maxTokens` (integer, optional)
- `temperature` (double, optional)

### CreateVoiceAgentDraftRequestConfigErrorHandlingFallbacksItems2

- `message` (string, required)
- `type` (enum, required)
  - Allowed values: `message`
- `delay` (integer, optional)

### CreateVoiceAgentDraftRequestConfigSandboxNetworkAccess1

- `allow` (list of string, optional)
- `profile` (enum, optional)
  - Allowed values: `none`, `essentials`, `open`

### CreateVoiceAgentDraftRequestConfigToolsApprovalRequire

### CreateVoiceAgentDraftRequestConfigToolsApprovalChoices

- `alwaysAllow` (boolean, optional)
- `alwaysDeny` (boolean, optional)

### CreateVoiceAgentDraftRequestConfigToolsMcpServersItemsAuth

- `type` (enum, required)
  - Allowed values: `api_key`, `bearer`, `basic`, `custom_header`, `headers`, `none`
- `headerName` (string, optional)
- `headers` (map from string to string, optional)
- `password` (string, optional)
- `token` (string, optional)
- `username` (string, optional)

### CreateVoiceAgentDraftRequestConfigVoiceSpeechSynthesizer

- `provider` (string, required)
- `model` (string, optional)
- `settings` (CreateVoiceAgentDraftRequestConfigVoiceSpeechSynthesizerSettings, optional)
- `voiceId` (string, optional)

### CreateVoiceAgentDraftRequestConfigVoiceSpeechTranscriber

- `provider` (string, required)
- `model` (string, optional)

### CreateVoiceAgentDraftRequestConfigVoiceSpeechSynthesizerSettings

- `similarity` (double, optional)
- `stability` (double, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "draftId": "string",
  "expiresAt": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/agents/id/voice/drafts"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/agents/id/voice/drafts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/id/voice/drafts"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/id/voice/drafts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.runtype.com/v1/agents/id/voice/drafts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/agents/id/voice/drafts', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/id/voice/drafts");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/id/voice/drafts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```