Create a draft version

Save a new draft at the version number in the path. You choose the number; Tandem never assigns one. The agent must already exist, and the number must not — this endpoint never overwrites, so use PUT to revise a draft.

A draft is checked for shape only. Every bound the published configuration enforces is enforced here — a field you send must be valid, and a system prompt over 100,000 bytes on the wire is rejected — but the configuration may be incomplete: systemPrompt and slots are optional on a draft so you can save before you have written the prompt or picked a model. The checks a draft does not run are the ones that need the rest of the platform: whether {{org.*}} and {{secrets.*}} references resolve, whether a secret sits somewhere it is allowed to, whether the ElevenLabs voice you picked is connected, and whether an agent tool points at something callable. Those run at publish, which is the first moment the configuration can take a call. A draft that saves cleanly can still fail to publish.

An agent may hold at most 20 versions. Delete one to make room.

Storing a {{secrets.*}} reference requires an organization admin, the same rule the configuration PUT has always carried.

Authorization

bearerAuth

AuthorizationBearer <token>

A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

In: header

Path Parameters

agentId*string

The agent's unique ID.

version*string

The version number: <major>.<minor>, two non-negative integers with no leading zeros and at most nine digits each — 0.1, 1.0, 2.13. You choose it. Anything else is rejected with invalid_version, because the number is part of the version's storage key.

Match^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The body a version create or update takes: the configuration, plus an optional release note.

version comes from the path, never the body. name and sourceTemplateId are not part of a version — send them and they are dropped rather than rejected, so a configuration read back off an agent can be posted here as-is. Change the name with PUT /v1/agent-media/agents/{agentId}.

description?string

A release note for this version. Free text, and part of the replacement: omit it on an update and the stored note is cleared, not carried over. Over 2,000 characters is rejected with invalid_config naming this field.

Lengthlength <= 2000

baseVersion?string

Create only; ignored on update and never stored. The version this body was copied from. When the body changes knowledge.kbId from that version's and sends its knowledge.minScore unchanged, the score is dropped so the new knowledge base's default applies. Omitted or naming no version of this agent, the body is stored as sent.

systemPrompt?string

The agent's role, capabilities, and constraints. Rejected (create/update 400 invalid_config) when it exceeds 100,000 bytes once JSON-encoded — not the same as its raw character count, since escaping grows it.

Length1 <= length

greeting?string

Spoken verbatim as the agent's first turn.

interruptable?boolean

Whether caller speech interrupts the agent mid-sentence (barge-in).

Defaulttrue

channels?array<>

Which channels this agent answers on. Defaults to both, so a config that omits it behaves exactly as one written before the field existed.

It changes one rule: slots.tts is required only while voice is present. A chat-only agent saves and publishes with no voice, since the chat wire never carries one. A voice that IS set is validated on either channel — a voice that is there has to be a real one. An empty array is rejected.

Items1 <= items

Default

[  "voice",  "chat"]

slots?

greetingParts?array<>

Replaces greeting on calls. Each language must be a voice language of the agent. Templates render per part.

Itemsitems <= 10

variables?array<>

Agent-local values, referenced as {{agent.<name>}} wherever the configuration takes text. The organization-wide equivalent is {{org.<name>}}, managed separately. A reference to a name that does not exist is rejected at save time.

Itemsitems <= 50

Default[]

dispositions?array<>

Default[]

builtinTools?

The built-in call-control tools this agent may use. Every field defaults, so an agent saved without this block behaves exactly as before. No tool here requires a connected integration: the outside transfer is placed over the ordinary phone network, and everything else is internal to Tandem or local to the call.

dtmf?

Keypad input as ordinary caller input. A run of keypresses is grouped into one caller turn and delivered to the agent the way a spoken sentence is, with no tool call armed. Separate from builtinTools.captureDtmf, which is a tool the agent calls to ask a bounded question and block on the answer. Both may be on: while a captureDtmf collection is open the keypresses go into it instead, and digits already typed into an open group are carried into that collection rather than delivered twice.

thinkingCue?||

What the caller hears while a tool call runs. none is silence.

vad?

Turn-taking sensitivity. Every field is individually optional: whatever is absent falls back to the underlying voice pipeline's own default, and a partial block is a legal save.

turnDetection?

Which strategy decides the caller has finished speaking. vad tunes what counts as the caller starting to speak; this decides when they stop. Absent behaves exactly as mode: silence, which is what every agent has always used.

The Turn detection control on the Voice & Speech tab is being rolled out — if it isn't there, the rollout hasn't reached your organization yet. This API accepts the block either way, and the voice pipeline honors whatever is stored: the rollout gates the editor control, not the capability.

memory?

safety?

skills?

analysis?

Post-call analysis: a separate model pass over the finished transcript, extracting the built-in judgments and any fields you define.

Whether the transcript itself is kept is a separate setting, retention.transcripts, and analysis does not control it. With retention on — including by default, for an agent that has not set safety.redactPii — the transcript is stored whether or not analysis is enabled. With retention off, enabling analysis is the only thing that stores one.

retention?

What a finished call leaves behind. Independent of analysis: an organization can keep transcripts without paying for a model pass over them, and can analyze calls without this block set at all.

idle?

What happens when the caller goes silent mid-call.

limits?

Caller-visible bounds on the call itself.

reliability?

Failure-handling tuning. Each field falls back to a fixed default when absent, so an empty block is exactly today's behavior.

conversation?

How the agent's message history is kept inside the model's context window on a long call. An empty block behaves like strategy: slidingWindow with no other fields set — a 40-message window that drops the oldest messages first.

vocabulary?

Terms the agent must hear and say correctly on a call, such as product names. Voice only. Mishearings are replaced with the term in the caller's transcript, the voice says each term as its sayAs, terms with heardAs are listed in the agent's instructions, and a published agent's terms also tune speech recognition — see GET /v1/agent-media/agents/{agentId}/vocabulary-status.

dataCollection?

The fields this agent collects during a conversation. Setting it turns on the record_data tool (and, in chat, request_data_input). Live conversations use the published version, so publish after changing it. Omit to collect nothing. Read what was collected from GET /v1/agent-media/calls/{conversationId}/collected or GET /v1/agent-media/chat-conversations/{conversationId}/collected.

tools?array<||||>

Default[]

knowledge?

Response Body

`application/json`

curl -X POST "https://example.com/v1/agent-media/agents/string/versions/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "version": {    "version": "string",    "description": "string",    "publishedAt": "2019-08-24T14:15:22Z",    "createdBy": "string",    "updatedBy": "string",    "backfilledAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "systemPrompt": "string",    "greeting": "string",    "interruptable": true,    "channels": [      "voice",      "chat"    ],    "slots": {      "llm": {        "model": "string",        "settings": {          "maxTokens": 1,          "temperature": 0,          "reasoning": {            "enabled": false,            "budgetTokens": 1024          }        }      },      "stt": {        "provider": "string",        "settings": {          "language": "string"        }      },      "tts": {        "voiceProvider": "string",        "settings": {          "language": "string",          "voiceId": "string",          "engine": "string",          "polly": {            "rate": "string",            "volume": "string"          },          "elevenlabs": {            "speed": 0.7,            "stability": 0,            "similarityBoost": 0,            "style": 0,            "useSpeakerBoost": true,            "textNormalization": "auto",            "pronunciationDictionaries": [              {                "id": "string",                "versionId": "string"              }            ]          }        }      },      "additionalVoices": [        {          "voiceProvider": "string",          "settings": {            "language": "string",            "voiceId": "string",            "engine": "string",            "polly": {              "rate": "string",              "volume": "string"            },            "elevenlabs": {              "speed": 0.7,              "stability": 0,              "similarityBoost": 0,              "style": 0,              "useSpeakerBoost": true,              "textNormalization": "auto",              "pronunciationDictionaries": [                {                  "id": "string",                  "versionId": "string"                }              ]            }          }        }      ]    },    "greetingParts": [      {        "language": "string",        "text": "string"      }    ],    "variables": [],    "dispositions": [],    "builtinTools": {      "transferToExternal": {        "enabled": false,        "destinations": []      },      "transferToVoiceAgent": {        "enabled": false,        "contextCarryover": "none",        "destinations": []      },      "captureDtmf": {        "enabled": false,        "maxDigits": 16,        "terminator": "#",        "timeoutMs": 10000,        "interDigitTimeoutMs": 3000,        "interruptsSpeech": true      },      "recordingControl": {        "enabled": false      },      "currentTime": {        "enabled": false,        "timezone": "America/New_York"      },      "setWorkflowVariable": {        "enabled": false,        "variables": []      }    },    "dtmf": {      "enabled": false,      "interDigitGapMs": 1500,      "terminator": "#",      "maxDigits": 32,      "interruptsSpeech": true    },    "thinkingCue": {      "kind": "none"    },    "vad": {      "silenceMs": 200,      "threshold": 0.7,      "startMs": 200,      "minVolume": 0.6,      "endOfTurnGraceMs": 600,      "bargeInMinWords": 1    },    "turnDetection": {      "mode": "silence",      "smartStopMs": 3000,      "preSpeechMs": 500,      "maxDurationSecs": 8    },    "memory": {      "depth": "none",      "customizeGreeting": false    },    "safety": {      "redactPii": true,      "steeringRules": [        "string"      ]    },    "skills": {      "builtins": [],      "custom": []    },    "analysis": {      "enabled": false,      "builtins": {        "sentiment": {          "enabled": false,          "prompt": "string"        },        "outcome": {          "enabled": false,          "prompt": "string"        },        "summary": {          "enabled": false,          "prompt": "string"        }      },      "fields": []    },    "retention": {      "transcripts": true    },    "idle": {      "enabled": false,      "timeoutMs": 10000,      "action": "reprompt",      "prompt": "string",      "maxReprompts": 2,      "onExhausted": "endCall",      "disposition": "string"    },    "limits": {      "maxCallDurationMs": 60000,      "warnBeforeEndMs": 5000,      "warnPrompt": "string"    },    "reliability": {      "maxConsecutiveTurnFailures": 1,      "toolTimeoutMs": 1000,      "steeringJudgeTimeoutMs": 500,      "handoffMaxHistoryMessages": 1,      "modelRetryMaxAttempts": 1,      "modelRetryInitialDelayMs": 100,      "modelRetryMaxDelayMs": 100    },    "conversation": {      "strategy": "slidingWindow",      "windowSize": 10,      "summaryRatio": 0.1,      "preserveRecentMessages": 2,      "pinFirst": 1,      "proactiveCompressionThreshold": 0.3    },    "vocabulary": {      "terms": []    },    "dataCollection": {      "fields": [        {          "key": "string",          "label": "string",          "kind": "full_name",          "required": false,          "prompt": ""        }      ]    },    "tools": [],    "knowledge": {      "kbId": "string",      "maxResults": 4,      "minScore": 0    }  }}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

Create a draft version

Authorization

Path Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`