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": "64b8f9a2c3d4e56789ab0123",
5     "agent": "64b8f9a2c3d4e56789ab0456",
6     "status": "draft",
7     "branch": "feature-voice-improvements",
8     "revisionNumber": 5,
9     "versionNumber": 12,
10     "label": "Voice Update v5",
11     "description": "Improved voice detection and synthesis parameters.",
12     "isPinned": false,
13     "publishedBy": "user_987654321",
14     "publishedAt": "2024-01-15T09:30:00Z",
15     "publishedByName": "Jane Doe",
16     "restoredFromLabel": "Voice Update v4",
17     "draftId": "draft_123456789",
18     "draftName": "Voice Improvements Draft",
19     "draftRevision": 3,
20     "sourceVersionId": "64b8f9a2c3d4e56789ab0111",
21     "blocks": {
22       "workflow_prompt": "64b8f9a2c3d4e56789ab0201",
23       "workflow_tools": "64b8f9a2c3d4e56789ab0202",
24       "workflow_graph": "64b8f9a2c3d4e56789ab0203",
25       "llm": "64b8f9a2c3d4e56789ab0204",
26       "voice": "64b8f9a2c3d4e56789ab0205",
27       "language": "64b8f9a2c3d4e56789ab0206",
28       "call_handling": "64b8f9a2c3d4e56789ab0207",
29       "detection": "64b8f9a2c3d4e56789ab0208",
30       "analytics": "64b8f9a2c3d4e56789ab0209",
31       "timeouts": "64b8f9a2c3d4e56789ab0210",
32       "audio": "64b8f9a2c3d4e56789ab0211",
33       "privacy": "64b8f9a2c3d4e56789ab0212",
34       "widget": "64b8f9a2c3d4e56789ab0213",
35       "playbooks": "64b8f9a2c3d4e56789ab0214"
36     },
37     "workflowType": "voice_assistant",
38     "parentVersion": "64b8f9a2c3d4e56789ab0100",
39     "isActive": true,
40     "activatedBy": "user_987654321",
41     "activatedAt": "2024-01-15T09:30:00Z",
42     "securityCheck": {
43       "status": "passed",
44       "reason": "All security checks passed successfully.",
45       "triggeredAt": "2024-01-14T08:00:00Z",
46       "completedAt": "2024-01-14T08:30:00Z"
47     },
48     "pendingPublish": {
49       "state": "active",
50       "startedBy": "user_987654321",
51       "startedAt": "2024-01-15T08:45:00Z"
52     },
53     "restoredFromRevisionId": "64b8f9a2c3d4e56789ab010f",
54     "sourceDraftId": "draft_123456788",
55     "promptScore": {
56       "overall_score": 92.5,
57       "overall_grade": "A",
58       "band": "high",
59       "estimated_ttft_overhead_ms": 120.5,
60       "scoredAt": "2024-01-15T09:00:00Z",
61       "dimensions": [
62         {
63           "tier": 1,
64           "level": "advanced",
65           "evidence_span": "Prompt includes detailed context and fallback instructions.",
66           "title": "Contextual Relevance",
67           "description": "The prompt effectively guides the agent with relevant context."
68         }
69       ]
70     },
71     "promptScoreStale": false,
72     "createdBy": "user_987654321",
73     "createdAt": "2024-01-10T12:00: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.

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.

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.

timezonestringOptional

IANA timezone identifier used for date/time interpretation in prompts and tool calls.

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.

statusboolean

dataobject

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