On this page
agents.import
Import a Retell agent export as a draft, never live: a new agent gets it as its first draft; an existing agent's draft is replaced and its head is unchanged. Replacing a draft with unpublished changes needs replace_draft {draft_id, expected_revision} naming it (409 reason draft_has_changes otherwise). Publish the draft with publications.publish (201; re-importing the same export onto its unedited draft returns 200)
Request
POST /api/v1/agents/import
- MCP:
agents_import - SDK:
client.agents.import(SDK path arguments usepath; MCP usesparams). - Minimum API key role: member.
- Idempotency: required_header. Send an
Idempotency-Keyheader; MCP usesidempotency_key. Reuse it after an unknown outcome.
Only Retell Conversation Flow agents import (response_engine.type conversation-flow). From the export: flow = its conversationFlow object (with conversation_flow_id and version); agent = the rest of the export, with agent.version equal to agent_version and agent_name set to the new agent's name; agent.webhook_url null unless config.webhook pins the same URL (webhook_mismatch otherwise). reference = {tenant_id: the current environment's tenant_id (environments_list), kind: "agent", id: a new lowercase agent id, or an existing agent's id to replace its draft}. config.providers: llm {provider: "openai", model: {model_id, provider, tier}} with a ready chat model from models_list; stt {provider: "elevenlabs", model: "scribe_v2_realtime"}; tts {provider: "elevenlabs", model, voiceId} from voices_list. config.recording {required: true, channels: "dual"}. config.telephony {trunkId, from} only once the trunk and number exist; omit it until then and add it later with a drafts_edit agent.telephony edit. model_bindings: call agents_import_inspect first; each model_binding_required diagnostic path (for example $.flow.model_choice, $.agent.post_call_analysis_model) maps to {model: {model_id, provider, tier}}. Retell voices, languages other than en/es and knowledge bases do not carry over (warnings, or unsupported_capability).
Input schema
json
{
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentsImportRequest"
}
}
}
}
}
Responses
json
{
"200": {
"description": "Import a Retell agent export as a draft, never live: a new agent gets it as its first draft; an existing agent's draft is replaced and its head is unchanged. Replacing a draft with unpublished changes needs replace_draft {draft_id, expected_revision} naming it (409 reason draft_has_changes otherwise). Publish the draft with publications.publish (201; re-importing the same export onto its unedited draft returns 200)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentsImportResponse201"
}
}
}
},
"201": {
"description": "Import a Retell agent export as a draft, never live: a new agent gets it as its first draft; an existing agent's draft is replaced and its head is unchanged. Replacing a draft with unpublished changes needs replace_draft {draft_id, expected_revision} naming it (409 reason draft_has_changes otherwise). Publish the draft with publications.publish (201; re-importing the same export onto its unedited draft returns 200)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentsImportResponse201"
}
}
}
},
"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
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
},
"AgentsImportResponse201": {
"type": "object",
"properties": {
"outcome": {
"type": "string",
"enum": [
"create_agent",
"open_draft",
"replace_draft",
"unchanged"
]
},
"draft": {
"$ref": "#/components/schemas/DraftsEditResponse200"
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Diagnostic"
}
}
},
"required": [
"outcome",
"draft",
"warnings"
],
"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
},
"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
See API error handling and Troubleshooting.
Related guides
Content version d4788d5aMarkdown source