Source: https://docs.cumuluslabs.io/reference/agents.import_inspect Content version: dc31840a # agents.import_inspect Compile a Retell export and say what agents.import would do (new agent, new or replaced draft, unpublished changes it would discard) without importing it ## Request {#request} `POST /api/v1/agents/import/inspect` - MCP: `agents_import_inspect` - SDK: `client.agents.import_inspect` (SDK path arguments use `path`; MCP uses `params`). - Minimum API key role: **member**. - Idempotency: **none**. Takes the same body as agents_import, without idempotency_key, and writes nothing. Call it first: its model_binding_required diagnostics name the model_bindings paths agents_import needs, and it reports every other diagnostic the import would. ## Input schema {#input-schema} ```json { "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsImportRequest" } } } } } ``` ## Responses {#responses} ```json { "200": { "description": "Compile a Retell export and say what agents.import would do (new agent, new or replaced draft, unpublished changes it would discard) without importing it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsImportInspectResponse200" } } } }, "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": { "AgentsImportRequest": { "type": "object", "properties": { "reference": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "tenant_id", "kind", "id" ], "additionalProperties": false }, "agent_version": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "flow": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "agent": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "config": { "type": "object", "properties": { "providers": { "type": "object", "properties": { "stt": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 256 }, "model": { "type": "string", "minLength": 1, "maxLength": 256 }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "version" ], "additionalProperties": false }, "endpoint": { "type": "string", "format": "uri" }, "voiceId": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "provider", "model" ], "additionalProperties": false }, "llm": { "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 }, "provider": { "type": "string", "enum": [ "openai", "simulated_openai", "self_hosted", "simulated_self_hosted" ] }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "model", "provider" ], "additionalProperties": false }, "tts": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 256 }, "model": { "type": "string", "minLength": 1, "maxLength": 256 }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "id", "version" ], "additionalProperties": false }, "endpoint": { "type": "string", "format": "uri" }, "voiceId": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "provider", "model" ], "additionalProperties": false } }, "required": [ "stt", "llm", "tts" ], "additionalProperties": false }, "telephony": { "type": "object", "properties": { "trunkId": { "type": "string", "minLength": 1, "maxLength": 256 }, "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$" } }, "required": [ "trunkId" ], "additionalProperties": false }, "recording": { "type": "object", "properties": { "required": { "type": "boolean" }, "channels": { "type": "string", "enum": [ "dual" ] } }, "required": [ "required", "channels" ], "additionalProperties": false }, "webhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secretRef": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "url", "secretRef" ], "additionalProperties": false } }, "required": [ "providers", "recording" ], "additionalProperties": false }, "model_bindings": { "type": "object", "additionalProperties": { "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 } }, "replace_draft": { "type": "object", "properties": { "draft_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 2147483647 } }, "required": [ "draft_id", "expected_revision" ], "additionalProperties": false } }, "required": [ "reference", "agent_version", "flow", "agent", "config", "model_bindings" ], "additionalProperties": false }, "JsonValue": { "nullable": true, "description": "Any JSON value: null, boolean, number, string, array or object." }, "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 }, "AgentsImportInspectResponse200": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "digest": { "allOf": [ { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" } ], "nullable": true }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" } }, "target": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "create_agent", "open_draft", "replace_draft", "unchanged" ] }, "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 }, "name": { "type": "string", "nullable": true }, "head_version": { "allOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 } ], "nullable": true }, "draft": { "type": "object", "properties": { "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 }, "unpublished_changes": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "draft_id", "revision", "base_version", "published_revision", "unpublished_changes", "updated_at" ], "additionalProperties": false, "nullable": true } }, "required": [ "outcome", "agent", "name", "head_version", "draft" ], "additionalProperties": false } }, "required": [ "ok", "version", "digest", "diagnostics", "target" ], "additionalProperties": false }, "Diagnostic": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 128 }, "path": { "type": "string", "maxLength": 1024 }, "message": { "type": "string", "maxLength": 4096 }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "fixes": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticFix" }, "maxItems": 8 } }, "required": [ "code", "path", "message", "severity" ], "additionalProperties": false }, "DiagnosticFix": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 256 }, "edits": { "type": "array", "items": { "$ref": "#/components/schemas/DraftEdit" }, "minItems": 1, "maxItems": 100 } }, "required": [ "id", "label", "edits" ], "additionalProperties": false }, "DraftEdit": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent.name" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent.settings" ] }, "values": { "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 }, "clear": { "type": "array", "items": { "type": "string", "enum": [ "voiceId", "voiceModel", "voiceSpeed", "voiceTemperature", "volume", "language", "responsiveness", "interruptionSensitivity", "enableBackchannel", "backchannelFrequency", "backchannelWords", "reminderTriggerMs", "reminderMaxCount", "maxCallDurationMs", "endCallAfterSilenceMs", "ringDurationMs", "beginMessageDelayMs", "normalizeForSpeech", "openerWaitsForCallee", "voicemail", "ambientSound", "ambientSoundVolume", "boostedKeywords", "pronunciationDictionary", "denoisingMode", "sttMode", "allowUserDtmf", "allowDtmfInterruption", "userDtmfOptions", "dataStorageSetting", "optInSignedUrl", "piiConfig", "handbookConfig", "ivr", "screener", "postCallAnalysisModel", "compliance" ] } } }, "required": [ "type", "values", "clear" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent.analysis" ] }, "fields": { "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 } } }, "required": [ "type", "fields" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent.provider" ] }, "role": { "type": "string", "enum": [ "stt", "llm", "tts" ] }, "changes": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 256 }, "model": { "type": "string", "minLength": 1, "maxLength": 256 }, "voiceId": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "endpoint": { "type": "string", "format": "uri", "nullable": true }, "credential": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "version" ], "additionalProperties": false } ], "nullable": true } }, "additionalProperties": false }, { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/ModelIdentity" }, "credential": { "allOf": [ { "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 } ], "nullable": true }, "provider": { "type": "string", "enum": [ "openai", "simulated_openai", "self_hosted", "simulated_self_hosted" ] }, "endpoint": { "type": "string", "format": "uri", "nullable": true } }, "additionalProperties": false } ] } }, "required": [ "type", "role", "changes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent.telephony" ] }, "value": { "type": "object", "properties": { "trunkId": { "type": "string", "minLength": 1, "maxLength": 256 }, "from": { "type": "string", "pattern": "^\\+[1-9][0-9]{6,14}$" } }, "required": [ "trunkId" ], "additionalProperties": false } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent.recording" ] }, "value": { "type": "object", "properties": { "required": { "type": "boolean" }, "channels": { "type": "string", "enum": [ "dual" ] } }, "required": [ "required", "channels" ], "additionalProperties": false } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "flow.prompt" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "node.name" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "name": { "type": "string", "nullable": true } }, "required": [ "type", "component_id", "node_id", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "node.instruction" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "instruction": { "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false } ], "nullable": true } }, "required": [ "type", "component_id", "node_id", "instruction" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "node.transitions" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "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 } } }, "required": [ "type", "component_id", "node_id", "edges" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "node.configure" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "changes": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "instruction": { "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false } ], "nullable": true }, "startSpeaker": { "type": "string", "enum": [ "agent", "user" ], "nullable": true }, "interruptionSensitivity": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true }, "voiceSpeed": { "type": "number", "minimum": 0.5, "maximum": 2, "nullable": true }, "languageLocked": { "type": "boolean", "nullable": true }, "globalNodeSetting": { "type": "object", "properties": { "condition": { "type": "string" }, "coolDown": { "type": "number", "minimum": 0 } }, "required": [ "condition" ], "additionalProperties": false, "nullable": true }, "toolId": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "waitForResult": { "type": "boolean", "nullable": true }, "speakDuringExecution": { "type": "boolean", "nullable": true }, "executionMessage": { "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "prompt", "static_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false } ], "nullable": true }, "transfer": { "type": "object", "properties": { "destination": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "predefined" ] }, "number": { "type": "string", "maxLength": 256 } }, "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, "nullable": true }, "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 }, "nullable": true }, "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, "nullable": true }, "componentId": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true } }, "additionalProperties": false } }, "required": [ "type", "component_id", "node_id", "changes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "node.create" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node": { "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", "maxLength": 256 } }, "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 } }, "required": [ "type", "component_id", "node" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "node.remove" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node_id": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "component_id", "node_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "flow.configure" ] }, "changes": { "type": "object", "properties": { "startNodeId": { "type": "string", "minLength": 1, "maxLength": 256 }, "startSpeaker": { "type": "string", "enum": [ "agent", "user" ] }, "globalPrompt": { "type": "string" }, "defaultDynamicVariables": { "type": "object", "additionalProperties": { "type": "string" } }, "modelChoice": { "allOf": [ { "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 } ], "nullable": true }, "toolCallStrictMode": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "type", "changes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "component.create" ] }, "component": { "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", "maxLength": 256 } }, "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 }, "minItems": 1 }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "parameters": { "type": "object", "additionalProperties": {} }, "responseVariables": { "type": "object", "additionalProperties": { "type": "string" } }, "timeoutMs": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "argsAtRoot": { "type": "boolean" }, "parameterType": { "type": "string", "enum": [ "json" ] }, "speakAfterExecution": { "type": "boolean" }, "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "version" ], "additionalProperties": false } }, "required": [ "name", "description", "url", "method", "parameters", "responseVariables", "timeoutMs", "argsAtRoot", "parameterType", "id" ], "additionalProperties": false } }, "flexMode": { "type": "boolean" } }, "required": [ "id", "startNodeId", "nodes", "tools" ], "additionalProperties": false } }, "required": [ "type", "component" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "component.start" ] }, "component_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "start_node_id": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "component_id", "start_node_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "component.remove" ] }, "component_id": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "component_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer.credential" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "node_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "credential": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "keep" ] } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "replace" ] }, "reference": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "version" ], "additionalProperties": false } }, "required": [ "action", "reference" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "remove" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "clear_inline": { "type": "boolean" } }, "required": [ "type", "component_id", "node_id", "credential", "clear_inline" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "channels.set" ] }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "cloud", "phone" ] }, "minItems": 1, "maxItems": 2 } }, "required": [ "type", "channels" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "languages.set" ] }, "languages": { "type": "array", "items": { "type": "string", "enum": [ "en", "es" ] }, "minItems": 1, "maxItems": 2 } }, "required": [ "type", "languages" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "trigger.put" ] }, "trigger": { "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 } ] } }, "required": [ "type", "trigger" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "trigger.remove" ] }, "trigger_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "trigger_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "action.put" ] }, "action": { "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 }, "response_variables": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Flow variables set from the action's 2xx JSON response, name to path ($.account.balance). Omitted keeps the current ones; {} removes them." } }, "required": [ "type", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "action.remove" ] }, "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notification.put" ] }, "notification": { "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 } }, "required": [ "type", "notification" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notification.remove" ] }, "notification_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "notification_id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "knowledge.set" ] }, "document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 200, "nullable": true } }, "required": [ "type", "document_ids" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cloud.io.set" ] }, "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 } }, "required": [ "type", "cloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "layout.set" ] }, "component_id": { "allOf": [ { "type": "string", "minLength": 1, "maxLength": 256 } ], "nullable": true }, "nodes": { "type": "object", "additionalProperties": { "allOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 } }, "required": [ "x", "y" ], "additionalProperties": false } ], "nullable": true } }, "start": { "allOf": [ { "type": "object", "properties": { "x": { "type": "number", "minimum": -10000000, "maximum": 10000000 }, "y": { "type": "number", "minimum": -10000000, "maximum": 10000000 } }, "required": [ "x", "y" ], "additionalProperties": false } ], "nullable": true }, "viewport": { "allOf": [ { "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 } ], "nullable": true } }, "required": [ "type", "component_id" ], "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} - [Using the API](https://docs.cumuluslabs.io/api) - [Agents](https://docs.cumuluslabs.io/agents) - [Build and test recipes](https://docs.cumuluslabs.io/recipes)