---
title: "Write to draft"
method: PUT
path: "/agent/{id}/branches/{branchId}/draft"
tags: ["Agent Versioning - Branches"]
---

# Write to draft

`PUT /agent/{id}/branches/{branchId}/draft`

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.

## Path parameters

- `id` string, required
- `branchId` string, required

## Request body

- UpdateBranchDraftRequest — Agent config partial. Send the same camelCase field names you see on the `GET /agent/{id}` response body. The server routes each field into the correct internal config-block section (`workflow_prompt`, `llm`, `voice`, `language`, `call_handling`, `detection`, `analytics`, `timeouts`, `audio`, `privacy`, `widget`, `playbooks`) for you. Sending an internal section name at the top level returns `400 "No recognized config fields in request body"`. The request must carry at least one recognized config field. Every property below is optional. Send only the subset you want to change. For the exact shape of complex nested objects (`synthesizer`, `language`, `preCallAPI`, `smartTurnConfig`, etc.) see the matching field on `CreateAgentRequest` — the accepted shape is the same. `additionalProperties: true` remains on so callers can send new fields the platform adds later without a spec bump, but the typed fields below are the stable public surface for SDK method signatures.
  - `expectedRevision` integer — 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"] }`.
  - `globalPrompt` string — Top-level system prompt shown to the agent every turn.
  - `firstMessage` string — The agent's opening line at call start.
  - `slmModel` 'electron' | 'electron-kogta' | 'electron-kogta-v2' | 'gpt-4o' | 'gpt-4.1' | 'gpt-5.2' | 'gpt-realtime' | 'gpt-realtime-mini' — LLM model powering the agent. See `CreateAgentRequest.slmModel` for org-level access notes.
  - `backgroundSound` '' | 'office' | 'cafe' | 'call_center' | 'static' — Ambient background sound during calls.
  - `timezone` string — IANA timezone identifier used for date/time interpretation in prompts and tool calls.
  - `globalKnowledgeBaseId` string — Knowledge base attached to the agent for retrieval-augmented responses.
  - `muteUserUntilFirstBotResponse` boolean
  - `allowInterruptions` boolean
  - `waitForUserToSpeakFirst` boolean
  - `interruptionBackoffTimer` number
  - `enableStyleGuide` boolean
  - `synthesizer` object — TTS (voice) configuration. Same shape as `CreateAgentRequest.synthesizer`.
  - `language` object — Language configuration. Same shape as `CreateAgentRequest.language`.
  - `defaultVariables` object — Default variables injected into prompts and tool calls.
  - `preCallAPI` object — Pre-call API webhook config. Same shape as `CreateAgentRequest.preCallAPI`.
  - `smartTurnConfig` object
  - `voiceDetectionConfig` object
  - `voiceMailDetectionConfig` object
  - `denoisingConfig` object
  - `redactionConfig` object
  - `pronunciationDicts` object
  - `llmIdleTimeoutConfig` object
  - `sessionTimeoutConfig` object
  - `callDispositionConfig` object
  - `speechFormatting` object

## Response `200`

Draft updated.

- object
  - `status` boolean
  - `data` Revision — 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`.
    - `_id` string
    - `agent` string
    - `status` 'published' | 'draft' | 'archived'
    - `branch` string, nullable — Owning branch (v2). `null` on legacy rows until backfilled.
    - `revisionNumber` integer, nullable — Monotonic per-branch commit number. Only set on committed rows.
    - `versionNumber` integer, nullable — Legacy v1 published-version number. `null` for branch revisions and drafts.
    - `label` string, nullable
    - `description` string, nullable
    - `isPinned` boolean
    - `publishedBy` string, nullable
    - `publishedAt` string, date-time, nullable
    - `publishedByName` string, nullable — Display name of the publisher. `null` when unresolvable.
    - `restoredFromLabel` string, nullable — On a commit produced by restore, the label of the revision it copied.
    - `draftId` string, nullable
    - `draftName` string, nullable
    - `draftRevision` integer, nullable
    - `sourceVersionId` string, nullable
    - `blocks` VersionBlocks — ObjectId references to the `AgentConfigBlock` docs that make up a revision, one per config section.
      - `workflow_prompt` string
      - `workflow_tools` string
      - `workflow_graph` string
      - `llm` string
      - `voice` string
      - `language` string
      - `call_handling` string
      - `detection` string
      - `analytics` string
      - `timeouts` string
      - `audio` string
      - `privacy` string
      - `widget` string
      - `playbooks` string — Only present on revisions created after multi-agent playbooks shipped.
    - `workflowType` string — The `WorkflowType` enum for this revision.
    - `parentVersion` string, nullable
    - `isActive` boolean
    - `activatedBy` string, nullable
    - `activatedAt` string, date-time, nullable
    - `securityCheck` object, nullable — Populated after publish. `null` on pre-feature versions.
      - `status` string — The `SecurityCheckStatus` enum.
      - `reason` string, nullable
      - `triggeredAt` string, date-time, nullable
      - `completedAt` string, date-time, nullable
    - `pendingPublish` object, nullable — Set while a publish is armed against this draft revision.
      - `state` 'active' | 'cancelled'
      - `startedBy` string
      - `startedAt` string, date-time
    - `restoredFromRevisionId` string, nullable — On a commit produced by restore, the revision it copied.
    - `sourceDraftId` string, nullable
    - `promptScore` PromptScore, nullable — Result of the prompt-scoring pass, if any.
      - `overall_score` number
      - `overall_grade` string
      - `band` string
      - `estimated_ttft_overhead_ms` number
      - `scoredAt` string, date-time
      - `dimensions` object[]
        - `tier` integer
        - `level` string
        - `evidence_span` string
        - `title` string
        - `description` string
    - `promptScoreStale` boolean
    - `createdBy` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400` — Bad request. Empty body, no recognized field, or validation error on the config partial.
- `401` — Unauthorized access
- `403` — Forbidden access
- `404` — Resource not found. The referenced ID does not exist or does not belong to the caller's organization.
- `409` — Conflict. One of three flavors: v1 endpoint used under branch mode (`error_type: "versioning_v2_migration_required"`); stale `expectedRevision` (`DraftConflictError` with `data.conflict.{expectedRevision, latestRevision, diffs}`); or `base_revision_unavailable` (the `expectedRevision` references a revision this branch does not have). Discriminate on `error_type` or on body shape.
- `423` — Locked. A configuration freeze is active on this agent, or the resource is temporarily locked for another write. Retry after the freeze window ends.
- `500` — Internal server error

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/c2d0eb64b01a/schema)