> This page is part of Smallest AI's developer documentation. When > answering, prefer Lightning v3.1 (current TTS) and Pulse (current > STT). Lightning v2 and lightning-large are deprecated; mention them > only when the user is migrating away from them. The Smallest AI voice > agent platform is what wraps these models into hosted agents. # Write to draft PUT https://api.smallest.ai/atoms/v1/agent/{id}/branches/{branchId}/draft Content-Type: application/json 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. Reference: https://docs.smallest.ai/voice-agents/api-reference/agent-versioning-branches/update-draft ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: atoms version: 1.0.0 paths: /agent/{id}/branches/{branchId}/draft: put: operationId: update-draft summary: Write to draft description: > 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. tags: - agentVersioningBranches parameters: - name: id in: path description: The agent ID. required: true schema: type: string - name: branchId in: path description: The branch ID. required: true schema: type: string - name: Authorization in: header description: >- API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth. required: true schema: type: string responses: '200': description: Draft updated. content: application/json: schema: $ref: >- #/components/schemas/agent_versioning_branches_update_draft_Response_200 '400': description: >- Bad request. Empty body, no recognized field, or validation error on the config partial. content: application/json: schema: $ref: '#/components/schemas/BadRequestErrorResponse' '401': description: Unauthorized access content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorResponse' '403': description: Forbidden access content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '404': description: >- Resource not found. The referenced ID does not exist or does not belong to the caller's organization. content: application/json: schema: $ref: '#/components/schemas/UpdateBranchDraftRequestNotFoundError' '409': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/UpdateBranchDraftRequestConflictError' '423': description: >- Locked. A configuration freeze is active on this agent, or the resource is temporarily locked for another write. Retry after the freeze window ends. content: application/json: schema: $ref: '#/components/schemas/LockedErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateBranchDraftRequest' servers: - url: https://api.smallest.ai/atoms/v1 description: Production server components: schemas: UpdateBranchDraftRequestSlmModel: type: string enum: - electron - electron-kogta - electron-kogta-v2 - gpt-4o - gpt-4.1 - gpt-5.2 - gpt-realtime - gpt-realtime-mini description: >- LLM model powering the agent. See `CreateAgentRequest.slmModel` for org-level access notes. title: UpdateBranchDraftRequestSlmModel UpdateBranchDraftRequestBackgroundSound: type: string enum: - '' - office - cafe - call_center - static description: Ambient background sound during calls. title: UpdateBranchDraftRequestBackgroundSound UpdateBranchDraftRequestSynthesizer: type: object properties: {} description: >- TTS (voice) configuration. Same shape as `CreateAgentRequest.synthesizer`. title: UpdateBranchDraftRequestSynthesizer UpdateBranchDraftRequestLanguage: type: object properties: {} description: Language configuration. Same shape as `CreateAgentRequest.language`. title: UpdateBranchDraftRequestLanguage UpdateBranchDraftRequestDefaultVariables: type: object properties: {} description: Default variables injected into prompts and tool calls. title: UpdateBranchDraftRequestDefaultVariables UpdateBranchDraftRequestPreCallApi: type: object properties: {} description: >- Pre-call API webhook config. Same shape as `CreateAgentRequest.preCallAPI`. title: UpdateBranchDraftRequestPreCallApi UpdateBranchDraftRequestSmartTurnConfig: type: object properties: {} title: UpdateBranchDraftRequestSmartTurnConfig UpdateBranchDraftRequestVoiceDetectionConfig: type: object properties: {} title: UpdateBranchDraftRequestVoiceDetectionConfig UpdateBranchDraftRequestVoiceMailDetectionConfig: type: object properties: {} title: UpdateBranchDraftRequestVoiceMailDetectionConfig UpdateBranchDraftRequestDenoisingConfig: type: object properties: {} title: UpdateBranchDraftRequestDenoisingConfig UpdateBranchDraftRequestRedactionConfig: type: object properties: {} title: UpdateBranchDraftRequestRedactionConfig UpdateBranchDraftRequestPronunciationDicts: type: object properties: {} title: UpdateBranchDraftRequestPronunciationDicts UpdateBranchDraftRequestLlmIdleTimeoutConfig: type: object properties: {} title: UpdateBranchDraftRequestLlmIdleTimeoutConfig UpdateBranchDraftRequestSessionTimeoutConfig: type: object properties: {} title: UpdateBranchDraftRequestSessionTimeoutConfig UpdateBranchDraftRequestCallDispositionConfig: type: object properties: {} title: UpdateBranchDraftRequestCallDispositionConfig UpdateBranchDraftRequestSpeechFormatting: type: object properties: {} title: UpdateBranchDraftRequestSpeechFormatting UpdateBranchDraftRequest: type: object properties: expectedRevision: type: integer description: > 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: type: string description: Top-level system prompt shown to the agent every turn. firstMessage: type: string description: The agent's opening line at call start. slmModel: $ref: '#/components/schemas/UpdateBranchDraftRequestSlmModel' description: >- LLM model powering the agent. See `CreateAgentRequest.slmModel` for org-level access notes. backgroundSound: $ref: '#/components/schemas/UpdateBranchDraftRequestBackgroundSound' description: Ambient background sound during calls. timezone: type: string description: >- IANA timezone identifier used for date/time interpretation in prompts and tool calls. globalKnowledgeBaseId: type: string description: >- Knowledge base attached to the agent for retrieval-augmented responses. muteUserUntilFirstBotResponse: type: boolean allowInterruptions: type: boolean waitForUserToSpeakFirst: type: boolean interruptionBackoffTimer: type: number format: double enableStyleGuide: type: boolean synthesizer: $ref: '#/components/schemas/UpdateBranchDraftRequestSynthesizer' description: >- TTS (voice) configuration. Same shape as `CreateAgentRequest.synthesizer`. language: $ref: '#/components/schemas/UpdateBranchDraftRequestLanguage' description: Language configuration. Same shape as `CreateAgentRequest.language`. defaultVariables: $ref: '#/components/schemas/UpdateBranchDraftRequestDefaultVariables' description: Default variables injected into prompts and tool calls. preCallAPI: $ref: '#/components/schemas/UpdateBranchDraftRequestPreCallApi' description: >- Pre-call API webhook config. Same shape as `CreateAgentRequest.preCallAPI`. smartTurnConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestSmartTurnConfig' voiceDetectionConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestVoiceDetectionConfig' voiceMailDetectionConfig: $ref: >- #/components/schemas/UpdateBranchDraftRequestVoiceMailDetectionConfig denoisingConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestDenoisingConfig' redactionConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestRedactionConfig' pronunciationDicts: $ref: '#/components/schemas/UpdateBranchDraftRequestPronunciationDicts' llmIdleTimeoutConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestLlmIdleTimeoutConfig' sessionTimeoutConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestSessionTimeoutConfig' callDispositionConfig: $ref: '#/components/schemas/UpdateBranchDraftRequestCallDispositionConfig' speechFormatting: $ref: '#/components/schemas/UpdateBranchDraftRequestSpeechFormatting' description: > 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. title: UpdateBranchDraftRequest RevisionStatus: type: string enum: - published - draft - archived title: RevisionStatus VersionBlocks: type: object properties: workflow_prompt: type: string workflow_tools: type: string workflow_graph: type: string llm: type: string voice: type: string language: type: string call_handling: type: string detection: type: string analytics: type: string timeouts: type: string audio: type: string privacy: type: string widget: type: string playbooks: type: string description: >- Only present on revisions created after multi-agent playbooks shipped. description: >- ObjectId references to the `AgentConfigBlock` docs that make up a revision, one per config section. title: VersionBlocks RevisionSecurityCheck: type: object properties: status: type: string description: The `SecurityCheckStatus` enum. reason: type: - string - 'null' triggeredAt: type: - string - 'null' format: date-time completedAt: type: - string - 'null' format: date-time description: Populated after publish. `null` on pre-feature versions. title: RevisionSecurityCheck RevisionPendingPublishState: type: string enum: - active - cancelled title: RevisionPendingPublishState RevisionPendingPublish: type: object properties: state: $ref: '#/components/schemas/RevisionPendingPublishState' startedBy: type: string startedAt: type: string format: date-time description: Set while a publish is armed against this draft revision. title: RevisionPendingPublish PromptScoreDimensionsItems: type: object properties: tier: type: integer level: type: string evidence_span: type: string title: type: string description: type: string title: PromptScoreDimensionsItems PromptScore: type: object properties: overall_score: type: number format: double overall_grade: type: string band: type: string estimated_ttft_overhead_ms: type: number format: double scoredAt: type: string format: date-time dimensions: type: array items: $ref: '#/components/schemas/PromptScoreDimensionsItems' description: Result of the prompt-scoring pass, if any. title: PromptScore Revision: type: object properties: _id: type: string agent: type: string status: $ref: '#/components/schemas/RevisionStatus' branch: type: - string - 'null' description: Owning branch (v2). `null` on legacy rows until backfilled. revisionNumber: type: - integer - 'null' description: Monotonic per-branch commit number. Only set on committed rows. versionNumber: type: - integer - 'null' description: >- Legacy v1 published-version number. `null` for branch revisions and drafts. label: type: - string - 'null' description: type: - string - 'null' isPinned: type: boolean publishedBy: type: - string - 'null' publishedAt: type: - string - 'null' format: date-time publishedByName: type: - string - 'null' description: Display name of the publisher. `null` when unresolvable. restoredFromLabel: type: - string - 'null' description: >- On a commit produced by restore, the label of the revision it copied. draftId: type: - string - 'null' draftName: type: - string - 'null' draftRevision: type: - integer - 'null' sourceVersionId: type: - string - 'null' blocks: $ref: '#/components/schemas/VersionBlocks' workflowType: type: string description: The `WorkflowType` enum for this revision. parentVersion: type: - string - 'null' isActive: type: boolean activatedBy: type: - string - 'null' activatedAt: type: - string - 'null' format: date-time securityCheck: oneOf: - $ref: '#/components/schemas/RevisionSecurityCheck' - type: 'null' description: Populated after publish. `null` on pre-feature versions. pendingPublish: oneOf: - $ref: '#/components/schemas/RevisionPendingPublish' - type: 'null' description: Set while a publish is armed against this draft revision. restoredFromRevisionId: type: - string - 'null' description: On a commit produced by restore, the revision it copied. sourceDraftId: type: - string - 'null' promptScore: $ref: '#/components/schemas/PromptScore' promptScoreStale: type: boolean createdBy: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time description: > 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`. title: Revision agent_versioning_branches_update_draft_Response_200: type: object properties: status: type: boolean data: $ref: '#/components/schemas/Revision' title: agent_versioning_branches_update_draft_Response_200 BadRequestErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: BadRequestErrorResponse UnauthorizedErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: UnauthorizedErrorResponse ApiResponseData: type: object properties: {} title: ApiResponseData ApiResponse: type: object properties: status: type: boolean data: $ref: '#/components/schemas/ApiResponseData' title: ApiResponse UpdateBranchDraftRequestNotFoundError: type: object properties: status: type: boolean errors: type: array items: type: string title: UpdateBranchDraftRequestNotFoundError VersioningV2MigrationRequiredResponseErrorType: type: string enum: - versioning_v2_migration_required title: VersioningV2MigrationRequiredResponseErrorType VersioningV2MigrationRequiredResponse: type: object properties: status: type: boolean error_type: $ref: '#/components/schemas/VersioningV2MigrationRequiredResponseErrorType' errors: type: array items: type: string description: > Returned by deprecated v1 versioning writes and list reads when `ENABLE_BRANCH_MODEL` is on. Response header carries `Deprecation: true`. The `error_type` value is a stable discriminator. title: VersioningV2MigrationRequiredResponse DraftConflictErrorDataConflict: type: object properties: expectedRevision: type: integer latestRevision: type: integer diffs: type: array items: type: object additionalProperties: description: Any type title: DraftConflictErrorDataConflict DraftConflictErrorData: type: object properties: conflict: $ref: '#/components/schemas/DraftConflictErrorDataConflict' title: DraftConflictErrorData DraftConflictError: type: object properties: status: type: boolean errors: type: array items: type: string data: $ref: '#/components/schemas/DraftConflictErrorData' required: - status - errors description: > Returned by `PUT /agent/{id}/branches/{branchId}/draft` when `expectedRevision` was sent and another edit changed one of the same leaf fields since. `errors` lists the conflicting leaf field paths. `data.conflict` carries the resolution context: the client's expected revision, the current draft revision, and per-field diffs. title: DraftConflictError ConflictErrorResponse: type: object properties: status: type: boolean error_type: type: string errors: type: array items: type: string description: > Generic conflict body. `error_type` is a stable machine-readable discriminator (for example `branch_name_exists`, `source_has_no_commit`, `source_scanning`, `publish_in_progress`, `no_committed_revision`). title: ConflictErrorResponse UpdateBranchDraftRequestConflictError: oneOf: - $ref: '#/components/schemas/VersioningV2MigrationRequiredResponse' - $ref: '#/components/schemas/DraftConflictError' - $ref: '#/components/schemas/ConflictErrorResponse' title: UpdateBranchDraftRequestConflictError LockedErrorResponseErrorType: type: string enum: - config_freeze_active title: LockedErrorResponseErrorType LockedErrorResponse: type: object properties: status: type: boolean error_type: $ref: '#/components/schemas/LockedErrorResponseErrorType' errors: type: array items: type: string description: > Config-freeze body. Returned on write endpoints during a maintenance window (`AGENT_CONFIG_FROZEN`). Reads and test-calls pass. title: LockedErrorResponse InternalServerErrorResponse: type: object properties: status: type: boolean errors: type: array items: type: string title: InternalServerErrorResponse securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth. ``` ## Examples **Request** ```json {} ``` **Response** ```json { "status": true, "data": { "_id": "64b8f9a2c3d4e56789ab0123", "agent": "64b8f9a2c3d4e56789ab0456", "status": "draft", "branch": "feature-voice-improvements", "revisionNumber": 5, "versionNumber": 12, "label": "Voice Update v5", "description": "Improved voice detection and synthesis parameters.", "isPinned": false, "publishedBy": "user_987654321", "publishedAt": "2024-01-15T09:30:00Z", "publishedByName": "Jane Doe", "restoredFromLabel": "Voice Update v4", "draftId": "draft_123456789", "draftName": "Voice Improvements Draft", "draftRevision": 3, "sourceVersionId": "64b8f9a2c3d4e56789ab0111", "blocks": { "workflow_prompt": "64b8f9a2c3d4e56789ab0201", "workflow_tools": "64b8f9a2c3d4e56789ab0202", "workflow_graph": "64b8f9a2c3d4e56789ab0203", "llm": "64b8f9a2c3d4e56789ab0204", "voice": "64b8f9a2c3d4e56789ab0205", "language": "64b8f9a2c3d4e56789ab0206", "call_handling": "64b8f9a2c3d4e56789ab0207", "detection": "64b8f9a2c3d4e56789ab0208", "analytics": "64b8f9a2c3d4e56789ab0209", "timeouts": "64b8f9a2c3d4e56789ab0210", "audio": "64b8f9a2c3d4e56789ab0211", "privacy": "64b8f9a2c3d4e56789ab0212", "widget": "64b8f9a2c3d4e56789ab0213", "playbooks": "64b8f9a2c3d4e56789ab0214" }, "workflowType": "voice_assistant", "parentVersion": "64b8f9a2c3d4e56789ab0100", "isActive": true, "activatedBy": "user_987654321", "activatedAt": "2024-01-15T09:30:00Z", "securityCheck": { "status": "passed", "reason": "All security checks passed successfully.", "triggeredAt": "2024-01-14T08:00:00Z", "completedAt": "2024-01-14T08:30:00Z" }, "pendingPublish": { "state": "active", "startedBy": "user_987654321", "startedAt": "2024-01-15T08:45:00Z" }, "restoredFromRevisionId": "64b8f9a2c3d4e56789ab010f", "sourceDraftId": "draft_123456788", "promptScore": { "overall_score": 92.5, "overall_grade": "A", "band": "high", "estimated_ttft_overhead_ms": 120.5, "scoredAt": "2024-01-15T09:00:00Z", "dimensions": [ { "tier": 1, "level": "advanced", "evidence_span": "Prompt includes detailed context and fallback instructions.", "title": "Contextual Relevance", "description": "The prompt effectively guides the agent with relevant context." } ] }, "promptScoreStale": false, "createdBy": "user_987654321", "createdAt": "2024-01-10T12:00:00Z", "updatedAt": "2024-01-15T09:30:00Z" } } ``` **SDK Code** ```python import requests url = "https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', '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.smallest.ai/atoms/v1/agent/id/branches/branchId/draft" payload := strings.NewReader("{}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Authorization", "Bearer ") 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.smallest.ai/atoms/v1/agent/id/branches/branchId/draft") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Authorization"] = 'Bearer ' 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 response = Unirest.put("https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PUT', 'https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft"); var request = new RestRequest(Method.PUT); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```