Write to draft

PUT

https://api.smallest.ai/atoms/v1/agent/:id/branches/:branchId/draft

PUT

/atoms/v1/agent/:id/branches/:branchId/draft

1 import requests
2 
3 url = "https://api.smallest.ai/atoms/v1/agent/id/branches/branchId/draft"
4 
5 payload = {}
6 headers = {
7     "Authorization": "Bearer <token>",
8     "Content-Type": "application/json"
9 }
10 
11 response = requests.put(url, json=payload, headers=headers)
12 
13 print(response.json())

1 {
2   "status": true,
3   "data": {
4     "_id": "string",
5     "agent": "string",
6     "status": "published",
7     "branch": "string",
8     "revisionNumber": 1,
9     "versionNumber": 1,
10     "label": "string",
11     "description": "string",
12     "isPinned": true,
13     "publishedBy": "string",
14     "publishedAt": "2024-01-15T09:30:00Z",
15     "publishedByName": "string",
16     "restoredFromLabel": "string",
17     "draftId": "string",
18     "draftName": "string",
19     "draftRevision": 1,
20     "sourceVersionId": "string",
21     "blocks": {
22       "workflow_prompt": "string",
23       "workflow_tools": "string",
24       "workflow_graph": "string",
25       "llm": "string",
26       "voice": "string",
27       "language": "string",
28       "call_handling": "string",
29       "detection": "string",
30       "analytics": "string",
31       "timeouts": "string",
32       "audio": "string",
33       "privacy": "string",
34       "widget": "string",
35       "playbooks": "string"
36     },
37     "workflowType": "string",
38     "parentVersion": "string",
39     "isActive": true,
40     "activatedBy": "string",
41     "activatedAt": "2024-01-15T09:30:00Z",
42     "securityCheck": {
43       "status": "string",
44       "reason": "string",
45       "triggeredAt": "2024-01-15T09:30:00Z",
46       "completedAt": "2024-01-15T09:30:00Z"
47     },
48     "pendingPublish": {
49       "state": "active",
50       "startedBy": "string",
51       "startedAt": "2024-01-15T09:30:00Z"
52     },
53     "restoredFromRevisionId": "string",
54     "sourceDraftId": "string",
55     "promptScore": {
56       "overall_score": 1.1,
57       "overall_grade": "string",
58       "band": "string",
59       "estimated_ttft_overhead_ms": 1.1,
60       "scoredAt": "2024-01-15T09:30:00Z",
61       "dimensions": [
62         {
63           "tier": 1,
64           "level": "string",
65           "evidence_span": "string",
66           "title": "string",
67           "description": "string"
68         }
69       ]
70     },
71     "promptScoreStale": true,
72     "createdBy": "string",
73     "createdAt": "2024-01-15T09:30:00Z",
74     "updatedAt": "2024-01-15T09:30:00Z"
75   }
76 }

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.

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.

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. 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.

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