Source: https://docs.cumuluslabs.io/reference/drafts.get Content version: 0f7ce706 # drafts.get Read the open draft ## Request {#request} `GET /api/v1/agents/{agent_id}/draft` - MCP: `drafts_get` - SDK: `client.drafts.get` (SDK path arguments use `path`; MCP uses `params`). - Minimum API key role: **viewer**. - Idempotency: **none**. Use the request schema below. Read IDs from earlier operation results. ## Input schema {#input-schema} ```json { "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } } ], "requestBody": null } ``` ## Responses {#responses} ```json { "200": { "description": "Read the open draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftsGetResponse200" } } } }, "4XX": { "description": "Typed error (ApiError)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "5XX": { "description": "Typed error (ApiError)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } ``` ## Referenced schemas {#schemas} ```json { "components": { "schemas": { "DraftsGetResponse200": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/DraftsEditResponse200" }, "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "cloud", "phone" ] }, "minItems": 1 }, "languages": { "type": "array", "items": { "type": "string", "enum": [ "en", "es" ] }, "minItems": 1 }, "flow": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 2 ] }, "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "startNodeId": { "type": "string", "minLength": 1, "maxLength": 256 }, "startSpeaker": { "type": "string", "enum": [ "agent", "user" ] }, "globalPrompt": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "kind": { "type": "string", "enum": [ "conversation", "end", "branch", "transfer_call", "function", "extract_dynamic_variables", "component" ] }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "destinationNodeId": { "type": "string", "minLength": 1, "maxLength": 256 }, "slot": { "type": "string", "enum": [ "edges", "else_edge", "skip_response_edge", "always_edge", "edge", "success_edge" ] }, "condition": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "always" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt" ] }, "prompt": { "type": "string" } }, "required": [ "type", "prompt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "equation" ] }, "operator": { "type": "string", "enum": [ "&&", "||" ] }, "equations": { "type": "array", "items": { "type": "object", "properties": { "left": { "type": "string" }, "operator": { "type": "string", "enum": [ "==", "!=", ">", "<", ">=", "<=", "contains", "is_set", "is_not_set" ] }, "right": { "type": "string" } }, "required": [ "left", "operator", "right" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "type", "operator", "equations" ], "additionalProperties": false } ] }, "compliance": { "type": "object", "properties": { "sets": { "type": "array", "items": { "type": "string", "enum": [ "rpc_confirmed" ] }, "minItems": 1 } }, "required": [ "sets" ], "additionalProperties": false } }, "required": [ "slot", "condition" ], "additionalProperties": false } }, "name": { "type": "string" }, "instruction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "startSpeaker": { "type": "string", "enum": [ "agent", "user" ] }, "interruptionSensitivity": { "type": "number", "minimum": 0, "maximum": 1 }, "voiceSpeed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "languageLocked": { "type": "boolean" }, "globalNodeSetting": { "type": "object", "properties": { "condition": { "type": "string" }, "coolDown": { "type": "number", "minimum": 0 } }, "required": [ "condition" ], "additionalProperties": false }, "toolId": { "type": "string", "minLength": 1, "maxLength": 256 }, "waitForResult": { "type": "boolean" }, "speakDuringExecution": { "type": "boolean" }, "executionMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "transfer": { "type": "object", "properties": { "destination": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "predefined" ] }, "number": { "type": "string" } }, "required": [ "type", "number" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inferred" ] }, "prompt": { "type": "string" } }, "required": [ "type", "prompt" ], "additionalProperties": false } ] }, "option": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cold_transfer", "warm_transfer" ] }, "showTransfereeAsCaller": { "type": "boolean" }, "optOutHumanDetection": { "type": "boolean" }, "enableBridgeAudioCue": { "type": "boolean" }, "onHoldMusic": { "type": "string" }, "agentDetectionTimeoutMs": { "type": "integer", "minimum": 0 }, "agentDetectionPrompt": { "type": "string" }, "transferMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "privateHandoffMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "coldTransferMode": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "ignoreE164Validation": { "type": "boolean" } }, "required": [ "destination", "option", "ignoreE164Validation" ], "additionalProperties": false }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 256 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "enum" ] }, "description": { "type": "string" }, "choices": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "type", "description" ], "additionalProperties": false } }, "modelChoice": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/ModelIdentity" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 }, "provider": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "version", "provider" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cascading" ] }, "highPriority": { "type": "boolean" }, "reasoningEffort": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "model", "type", "highPriority" ], "additionalProperties": false }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "kind", "edges" ], "additionalProperties": false } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "responseVariables": { "type": "object", "additionalProperties": { "type": "string" } }, "speakAfterExecution": { "type": "boolean" } }, "required": [ "id", "type", "name", "description", "method", "responseVariables" ], "additionalProperties": false } }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "startNodeId": { "type": "string", "minLength": 1, "maxLength": 256 }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "kind": { "type": "string", "enum": [ "conversation", "end", "branch", "transfer_call", "function", "extract_dynamic_variables", "component" ] }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "destinationNodeId": { "type": "string", "minLength": 1, "maxLength": 256 }, "slot": { "type": "string", "enum": [ "edges", "else_edge", "skip_response_edge", "always_edge", "edge", "success_edge" ] }, "condition": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "always" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt" ] }, "prompt": { "type": "string" } }, "required": [ "type", "prompt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "equation" ] }, "operator": { "type": "string", "enum": [ "&&", "||" ] }, "equations": { "type": "array", "items": { "type": "object", "properties": { "left": { "type": "string" }, "operator": { "type": "string", "enum": [ "==", "!=", ">", "<", ">=", "<=", "contains", "is_set", "is_not_set" ] }, "right": { "type": "string" } }, "required": [ "left", "operator", "right" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "type", "operator", "equations" ], "additionalProperties": false } ] }, "compliance": { "type": "object", "properties": { "sets": { "type": "array", "items": { "type": "string", "enum": [ "rpc_confirmed" ] }, "minItems": 1 } }, "required": [ "sets" ], "additionalProperties": false } }, "required": [ "slot", "condition" ], "additionalProperties": false } }, "name": { "type": "string" }, "instruction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "startSpeaker": { "type": "string", "enum": [ "agent", "user" ] }, "interruptionSensitivity": { "type": "number", "minimum": 0, "maximum": 1 }, "voiceSpeed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "languageLocked": { "type": "boolean" }, "globalNodeSetting": { "type": "object", "properties": { "condition": { "type": "string" }, "coolDown": { "type": "number", "minimum": 0 } }, "required": [ "condition" ], "additionalProperties": false }, "toolId": { "type": "string", "minLength": 1, "maxLength": 256 }, "waitForResult": { "type": "boolean" }, "speakDuringExecution": { "type": "boolean" }, "executionMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "transfer": { "type": "object", "properties": { "destination": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "predefined" ] }, "number": { "type": "string" } }, "required": [ "type", "number" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inferred" ] }, "prompt": { "type": "string" } }, "required": [ "type", "prompt" ], "additionalProperties": false } ] }, "option": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cold_transfer", "warm_transfer" ] }, "showTransfereeAsCaller": { "type": "boolean" }, "optOutHumanDetection": { "type": "boolean" }, "enableBridgeAudioCue": { "type": "boolean" }, "onHoldMusic": { "type": "string" }, "agentDetectionTimeoutMs": { "type": "integer", "minimum": 0 }, "agentDetectionPrompt": { "type": "string" }, "transferMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "privateHandoffMessage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "coldTransferMode": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "ignoreE164Validation": { "type": "boolean" } }, "required": [ "destination", "option", "ignoreE164Validation" ], "additionalProperties": false }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 256 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "enum" ] }, "description": { "type": "string" }, "choices": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "type", "description" ], "additionalProperties": false } }, "modelChoice": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/ModelIdentity" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 }, "provider": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "version", "provider" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cascading" ] }, "highPriority": { "type": "boolean" }, "reasoningEffort": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "model", "type", "highPriority" ], "additionalProperties": false }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "kind", "edges" ], "additionalProperties": false } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "responseVariables": { "type": "object", "additionalProperties": { "type": "string" } }, "speakAfterExecution": { "type": "boolean" } }, "required": [ "id", "type", "name", "description", "method", "responseVariables" ], "additionalProperties": false } }, "flexMode": { "type": "boolean" } }, "required": [ "id", "startNodeId", "nodes", "tools" ], "additionalProperties": false } }, "defaultDynamicVariables": { "type": "object", "additionalProperties": { "type": "string" } }, "modelChoice": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/ModelIdentity" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 }, "provider": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "version", "provider" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cascading" ] }, "highPriority": { "type": "boolean" }, "reasoningEffort": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "model", "type", "highPriority" ], "additionalProperties": false }, "toolCallStrictMode": { "type": "boolean" } }, "required": [ "schemaVersion", "id", "version", "startNodeId", "startSpeaker", "globalPrompt", "nodes", "tools", "components", "defaultDynamicVariables", "toolCallStrictMode" ], "additionalProperties": false }, "settings": { "type": "object", "properties": { "voiceId": { "type": "string", "minLength": 1, "maxLength": 256 }, "voiceModel": { "type": "string", "minLength": 1, "maxLength": 256 }, "voiceSpeed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "voiceTemperature": { "type": "number", "minimum": 0, "maximum": 2 }, "volume": { "type": "number", "minimum": 0, "maximum": 2 }, "language": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 1 } ] }, "responsiveness": { "type": "number", "minimum": 0, "maximum": 1 }, "interruptionSensitivity": { "type": "number", "minimum": 0, "maximum": 1 }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number", "minimum": 0, "maximum": 1 }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "reminderTriggerMs": { "type": "integer", "minimum": 0, "maximum": 3600000 }, "reminderMaxCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxCallDurationMs": { "type": "integer", "minimum": 1000, "maximum": 86400000 }, "endCallAfterSilenceMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "ringDurationMs": { "type": "integer", "minimum": 1000, "maximum": 300000 }, "beginMessageDelayMs": { "type": "integer", "minimum": 0, "maximum": 60000 }, "normalizeForSpeech": { "type": "boolean" }, "openerWaitsForCallee": { "type": "boolean" }, "voicemail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "detectionTimeoutMs": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "action": { "type": "string", "enum": [ "hangup", "leave_message" ] }, "message": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false } }, "required": [ "enabled" ], "additionalProperties": false }, "ambientSound": { "type": "string" }, "ambientSoundVolume": { "type": "number", "minimum": 0, "maximum": 2 }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string", "minLength": 1, "maxLength": 256 }, "alphabet": { "type": "string", "enum": [ "ipa", "cmu" ] }, "phoneme": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "word", "alphabet", "phoneme" ], "additionalProperties": false } }, "denoisingMode": { "type": "string" }, "sttMode": { "type": "string" }, "allowUserDtmf": { "type": "boolean" }, "allowDtmfInterruption": { "type": "boolean" }, "userDtmfOptions": { "type": "object", "properties": { "digitLimit": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "nullable": true }, "terminationKey": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#" ], "nullable": true }, "timeoutMs": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "additionalProperties": false, "nullable": true }, "dataStorageSetting": { "type": "string", "enum": [ "everything", "everything_except_pii", "basic_attributes_only" ] }, "optInSignedUrl": { "type": "boolean" }, "piiConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "post_call" ] }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "person_name", "address", "email", "phone_number", "ssn", "passport", "driver_license", "credit_card", "bank_account", "password", "pin", "medical_id", "date_of_birth", "customer_account_number" ] } } }, "required": [ "mode", "categories" ], "additionalProperties": false }, "handbookConfig": { "type": "object", "properties": { "defaultPersonality": { "type": "boolean" }, "conversationalPersonality": { "type": "boolean" }, "naturalFillerWords": { "type": "boolean" }, "highEmpathy": { "type": "boolean" }, "echoVerification": { "type": "boolean" }, "natoPhoneticAlphabet": { "type": "boolean" }, "speechNormalization": { "type": "boolean" }, "smartMatching": { "type": "boolean" }, "aiDisclosure": { "type": "boolean" }, "scopeBoundaries": { "type": "boolean" } }, "additionalProperties": false }, "ivr": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "enum": [ false ] } }, "required": [ "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "enabled": { "type": "boolean", "enum": [ true ] }, "action": { "type": "string", "enum": [ "hangup" ] }, "detectionWindowMs": { "type": "number", "enum": [ 180000 ] }, "detectionPrompt": { "type": "string", "nullable": true } }, "required": [ "enabled", "action", "detectionWindowMs" ], "additionalProperties": false } ] }, "screener": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "hangup" ] } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "wait" ] }, "waitMs": { "type": "integer", "minimum": 5000, "maximum": 120000 } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "play_line" ] }, "waitMs": { "type": "integer", "minimum": 5000, "maximum": 120000 }, "line": { "type": "object", "properties": { "en": { "type": "string", "minLength": 1, "maxLength": 500 }, "es": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } }, "required": [ "action", "line" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "treat_as_human" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "postCallAnalysisModel": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/ModelIdentity" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 }, "provider": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "version", "provider" ], "additionalProperties": false } }, "required": [ "model" ], "additionalProperties": false }, "compliance": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "fdcpa" ] } }, "additionalProperties": false } }, "additionalProperties": false }, "analysis": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 256 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "enum" ] }, "description": { "type": "string" }, "choices": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "type", "description" ], "additionalProperties": false } }, "providers": { "type": "object", "properties": { "llm": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "simulated_openai", "self_hosted", "simulated_self_hosted" ] }, "model": { "$ref": "#/components/schemas/ModelIdentity" } }, "required": [ "provider", "model" ], "additionalProperties": false }, "stt": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false, "nullable": true }, "tts": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "voiceId": { "type": "string" } }, "required": [ "provider", "model" ], "additionalProperties": false, "nullable": true } }, "required": [ "llm", "stt", "tts" ], "additionalProperties": false }, "telephony": { "allOf": [ { "type": "object", "properties": { "trunkId": { "type": "string", "minLength": 1, "maxLength": 256 }, "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$" } }, "required": [ "trunkId" ], "additionalProperties": false } ], "nullable": true }, "recording": { "type": "object", "properties": { "required": { "type": "boolean" }, "channels": { "type": "string", "enum": [ "dual" ] } }, "required": [ "required", "channels" ], "additionalProperties": false, "nullable": true }, "cloud": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string", "enum": [ "task", "chat", "background" ] }, "minItems": 1 }, "input_schema": { "type": "object", "additionalProperties": {} }, "output_schema": { "type": "object", "additionalProperties": {} }, "max_turns": { "type": "integer", "minimum": 1, "maximum": 200 }, "idle_timeout_ms": { "type": "integer", "minimum": 10000, "maximum": 86400000 }, "deadline_ms": { "type": "integer", "minimum": 1000, "maximum": 3600000 } }, "required": [ "modes", "input_schema", "output_schema", "max_turns", "idle_timeout_ms", "deadline_ms" ], "additionalProperties": false, "nullable": true }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "description": { "type": "string", "minLength": 1, "maxLength": 1024 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "cloud", "phone" ] }, "minItems": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "default": {} }, "auth": { "anyOf": [ { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "none" ] } }, "required": [ "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "bearer", "basic" ] }, "secret_ref": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "version" ], "additionalProperties": false } }, "required": [ "scheme", "secret_ref" ], "additionalProperties": false }, { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "header" ] }, "header_name": { "type": "string", "minLength": 1, "maxLength": 128 }, "secret_ref": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "version" ], "additionalProperties": false } }, "required": [ "scheme", "header_name", "secret_ref" ], "additionalProperties": false } ] }, "input_schema": { "type": "object", "additionalProperties": {} }, "output_schema": { "type": "object", "additionalProperties": {} }, "idempotency": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "effect_key" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "template" ] }, "header": { "type": "string", "default": "Idempotency-Key" }, "template": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "mode", "template" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none_read_only" ] } }, "required": [ "mode" ], "additionalProperties": false } ] }, "timeout_ms": { "type": "integer", "minimum": 500, "maximum": 120000 }, "on_uncertain": { "type": "string", "enum": [ "failure_edge", "uncertain_edge" ], "default": "failure_edge" } }, "required": [ "name", "description", "channels", "method", "url", "auth", "input_schema", "output_schema", "idempotency", "timeout_ms" ], "additionalProperties": false } }, "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "url": { "type": "string", "format": "uri" }, "secret_ref": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "version" ], "additionalProperties": false }, "format": { "type": "string", "enum": [ "semantic.v1" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "run.admitted", "run.ended", "recording.updated", "analysis.updated" ] }, "minItems": 1 } }, "required": [ "id", "url", "secret_ref", "format", "events" ], "additionalProperties": false } }, "knowledge": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "document_ids" ], "additionalProperties": false, "nullable": true }, "triggers": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "schedule" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "cron": { "type": "string", "pattern": "^(\\S+\\s+){4}\\S+$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "kind", "id", "cron", "timezone", "input" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "event_type": { "type": "string", "enum": [ "run.ended", "analysis.updated" ] }, "source": { "type": "object", "properties": { "agent_id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" }, "channel": { "type": "string", "enum": [ "cloud", "phone", "web" ] }, "dispositions": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 32 } }, "additionalProperties": false }, "input_mapping": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\/[A-Za-z0-9_/-]*$" } } }, "required": [ "kind", "id", "event_type", "source", "input_mapping" ], "additionalProperties": false } ] } }, "layout": { "$ref": "#/components/schemas/AgentLayout" } }, "required": [ "state", "name", "channels", "languages", "flow", "settings", "analysis", "providers", "telephony", "recording", "cloud", "actions", "notifications", "knowledge", "triggers", "layout" ], "additionalProperties": false }, "DraftsEditResponse200": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$" } }, "required": [ "tenant_id", "kind", "id" ], "additionalProperties": false }, "draft_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 2147483647 }, "base_version": { "allOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 } ], "nullable": true }, "published_revision": { "allOf": [ { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 2147483647 } ], "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "agent", "draft_id", "revision", "base_version", "published_revision", "updated_at" ], "additionalProperties": false }, "ModelIdentity": { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "pattern": "\\S" }, "provider": { "type": "string", "minLength": 1, "pattern": "\\S" }, "tier": { "type": "string", "enum": [ "frontier", "cumulus-served", "customer-gpu" ] } }, "required": [ "model_id", "provider", "tier" ], "additionalProperties": false }, "AgentLayout": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "nodes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 } }, "required": [ "x", "y" ], "additionalProperties": false } }, "start": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 } }, "required": [ "x", "y" ], "additionalProperties": false }, "viewport": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "zoom": { "type": "number", "minimum": 0.01, "maximum": 100 } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false } }, "required": [ "nodes" ], "additionalProperties": false }, "components": { "type": "object", "additionalProperties": { "type": "object", "properties": { "nodes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 } }, "required": [ "x", "y" ], "additionalProperties": false } }, "start": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 } }, "required": [ "x", "y" ], "additionalProperties": false }, "viewport": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "zoom": { "type": "number", "minimum": 0.01, "maximum": 100 } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false } }, "required": [ "nodes" ], "additionalProperties": false } } }, "required": [ "flow", "components" ], "additionalProperties": false }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthenticated", "forbidden", "not_found", "conflict", "invalid_request", "idempotency_conflict", "policy_denied", "capability_unavailable", "provider_unavailable", "knowledge_unavailable", "publication_invalid", "run_not_active", "rate_limited", "outcome_unknown", "internal" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "outcome": { "type": "string", "enum": [ "none", "unknown" ] }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "code", "message", "retryable", "outcome" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } ``` ## Errors and recovery {#errors} See [API error handling](https://docs.cumuluslabs.io/api#errors) and [Troubleshooting](https://docs.cumuluslabs.io/troubleshooting). ## Related guides {#related-guides} - [Agents](https://docs.cumuluslabs.io/agents) - [Build and test recipes](https://docs.cumuluslabs.io/recipes)