Skip to navigation
Voice Agents APIAgent Versioning - Branches

Write to draft

View as Markdown

Upsert the open draft on this branch. If no draft is open, one is created automatically. The request body is an agent config partial in the same camelCase shape as GET /agent/{id} (globalPrompt, firstMessage, synthesizer, language, voiceDetectionConfig, smartTurnConfig, …) and must contain at least one recognized field; the server merges it into the existing draft and returns the resulting draft as a revision-shaped snapshot.

Send native JSON types, not stringified values. Arrays (language.supported: ["en"]), booleans (language.switching.isEnabled: false), and objects (timezone: {"label": "(GMT+5:30) Asia/Kolkata", "offset": 330}) must be sent as real JSON. Passing "[\"en\"]", "false", or "Asia/Kolkata" instead is refused with a Zod-style error naming the offending path and the received type (e.g. Invalid config: language.supported: Expected array, received string). This is the single most common integration bug on this endpoint.

Post-call-analytics limits. When the payload includes postCallAnalyticsConfig.dispositionMetrics, two aggregate limits are enforced with 400 errors:

  • Combined prompt length. The total of every dispositionMetricPrompt across all metrics must be ≤ 50,000 characters. Error: The combined disposition metric prompts can be at most 50000 characters.
  • Enum-choice cap. Each dispositionMetricType: ENUM metric may have at most 20 choices. Error: Each enum metric can have at most 20 choices. Ones already over the limit can stay as they are, but can't grow any further. Remove the extra choices to save.

Both limits are grandfathered: an agent already over either limit can still save as long as the change does not make it worse (the combined prompt length does not grow, and no over-limit enum grows or gains new choices). No cap on the number of metrics or on a single prompt’s length.

Publish the draft with POST /agent/{id}/branches/{branchId}/draft/publish to make the changes live. The draft PUT alone does not affect running calls.

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Path parameters

idstringRequiredformat: "^[a-f\d]{24}$"
The agent ID.
branchIdstringRequiredformat: "^[a-f\d]{24}$"
The branch ID.

Request

This endpoint expects an object.
expectedRevisionintegerOptional>=0

Optimistic-concurrency control. The draftRevision the client's edit was based on. When present, the server runs a field-level conflict check and rejects with 409 DraftConflictError if the same field was changed by another edit since. Omit for last-write-wins semantics (which is also how a client force-overwrites after a 409). Referencing a non-existent base revision returns 409 { errors: ["base_revision_unavailable"] }.

globalPromptstringOptional

Top-level system prompt shown to the agent every turn.

firstMessagestringOptional
The agent's opening line at call start.
slmModelenumOptional

LLM model powering the agent. See CreateAgentRequest.slmModel for org-level access notes.

backgroundSoundenumOptional
Ambient background sound during calls.
Allowed values:
timezoneobjectOptional

Agent timezone applied to date/time interpretation in prompts, tool calls, and analytics bucketing. Object with a label (IANA-style label) and an offset (UTC offset in minutes). Sending a bare string is refused with Invalid config: timezone: Expected object, received string.

globalKnowledgeBaseIdstringOptional

Knowledge base attached to the agent for retrieval-augmented responses.

muteUserUntilFirstBotResponsebooleanOptional
allowInterruptionsbooleanOptional
waitForUserToSpeakFirstbooleanOptional
interruptionBackoffTimerdoubleOptional
enableStyleGuidebooleanOptional
synthesizerobjectOptional

TTS (voice) configuration. Same shape as CreateAgentRequest.synthesizer.

languageobjectOptional

Language configuration. Same shape as CreateAgentRequest.language.

defaultVariablesobjectOptional
Default variables injected into prompts and tool calls.
preCallAPIobjectOptional

Pre-call API webhook config. Same shape as CreateAgentRequest.preCallAPI.

smartTurnConfigobjectOptional
voiceDetectionConfigobjectOptional
voiceMailDetectionConfigobjectOptional
denoisingConfigobjectOptional
redactionConfigobjectOptional
pronunciationDictsobjectOptional
llmIdleTimeoutConfigobjectOptional
sessionTimeoutConfigobjectOptional
callDispositionConfigobjectOptional
speechFormattingobjectOptional

Response

Draft updated.
statusbooleanOptional
dataobjectOptional

An AgentVersion document. Represents either a committed revision (status: published, with branch + revisionNumber) or an in-progress draft revision (status: draft, with draftId + draftRevision). Fields that do not apply to a given row are null.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
423
Locked Error
500
Internal Server Error