On this page
runs.create
Admit a cloud or phone run of a publication (201; an idempotent replay returns 200)
Request
POST /api/v1/runs
- MCP:
runs_create - SDK:
client.runs.create(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.
Phone: {channel: "phone", agent_id, to, from, dynamic_variables, version?}. It dials a real number, with test: true too (test only keeps the run out of billing, webhooks and triggers): confirm the number with the user first. from must be a number imported with numbers_import; without it the agent's telephony.from is used. dynamic_variables must set every {{variable}} the flow uses (missing_dynamic_variables). Refusals: tenant_not_configured or tenant_disabled (Cumulus staff must set call capacity and open admission), trunk_not_authorized (from is not an imported number), capacity_exhausted (the concurrent call cap). Cloud: {channel: "cloud", agent_id, mode: "task" or "chat", input}; a phone agent can be chatted with in mode chat with test: true.
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/RunsCreateRequest"
}
}
}
}
}
Responses
json
{
"200": {
"description": "Admit a cloud or phone run of a publication (201; an idempotent replay returns 200)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Run"
}
}
}
},
"201": {
"description": "Admit a cloud or phone run of a publication (201; an idempotent replay returns 200)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Run"
}
}
}
},
"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": {
"RunsCreateRequest": {
"anyOf": [
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"cloud"
]
},
"agent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"mode": {
"type": "string",
"enum": [
"task",
"chat"
]
},
"input": {
"type": "object",
"additionalProperties": {}
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 512
},
"default": {}
},
"test": {
"type": "boolean",
"default": false
}
},
"required": [
"channel",
"agent_id",
"mode",
"input"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"phone"
]
},
"agent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"to": {
"type": "string",
"pattern": "^\\+[1-9][0-9]{6,14}$"
},
"from": {
"type": "string",
"pattern": "^\\+[1-9][0-9]{6,14}$"
},
"dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 4096
},
"default": {}
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 512
},
"default": {}
},
"test": {
"type": "boolean",
"default": false
}
},
"required": [
"channel",
"agent_id",
"to"
],
"additionalProperties": false
}
]
},
"Run": {
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"run_id": {
"type": "string",
"format": "uuid"
},
"agent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
},
"publication": {
"$ref": "#/components/schemas/PublicationRef"
},
"plan_schema_version": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"channel": {
"type": "string",
"enum": [
"cloud",
"phone",
"web"
]
},
"mode": {
"type": "string",
"enum": [
"task",
"chat",
"background",
"outbound",
"inbound"
]
},
"state": {
"type": "string",
"enum": [
"admitted",
"running",
"ending",
"completed",
"failed",
"cancelled",
"rejected",
"expired"
]
},
"phone_state": {
"type": "string",
"enum": [
"admitted",
"preparing",
"awaiting_sip",
"dialing",
"ringing",
"active",
"terminating",
"ended",
"rejected",
"expired",
"setup_failed"
],
"nullable": true
},
"outcome": {
"allOf": [
{
"$ref": "#/components/schemas/RunOutcome"
}
],
"nullable": true
},
"disposition": {
"type": "string",
"nullable": true
},
"trigger": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"sip"
]
},
"number_id": {
"type": "string",
"format": "uuid"
},
"call_id_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"kind",
"number_id",
"call_id_sha256"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"api"
]
},
"idempotency_key_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"kind",
"idempotency_key_sha256"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"schedule"
]
},
"trigger_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"scheduled_for": {
"type": "string",
"format": "date-time"
}
},
"required": [
"kind",
"trigger_id",
"scheduled_for"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"event"
]
},
"trigger_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"source_event_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"trigger_id",
"source_event_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"callback"
]
},
"source_run_id": {
"type": "string",
"format": "uuid"
},
"effect_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"source_run_id",
"effect_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"evaluation"
]
},
"comparison_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"comparison_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"test"
]
},
"test_run_id": {
"type": "string",
"format": "uuid"
},
"suite_id": {
"type": "string",
"format": "uuid"
},
"case_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9][a-z0-9_-]*$"
},
"trial": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"test_run_id",
"suite_id",
"case_id",
"trial"
],
"additionalProperties": false
}
]
},
"principal": {
"$ref": "#/components/schemas/PrincipalRef"
},
"attempt_count": {
"type": "integer",
"minimum": 0
},
"created_at": {
"type": "string",
"format": "date-time"
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"ended_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"to": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"nullable": true
},
"from": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"nullable": true
},
"duration_ms": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"test": {
"type": "boolean"
},
"provider_keys": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"platform"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"tenant"
]
},
"last4": {
"type": "string",
"minLength": 1,
"maxLength": 4
},
"fingerprint": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{12}$"
}
},
"required": [
"source",
"last4",
"fingerprint"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"owner_id",
"environment",
"tenant_id",
"run_id",
"agent_id",
"publication",
"plan_schema_version",
"channel",
"mode",
"state",
"phone_state",
"outcome",
"disposition",
"trigger",
"principal",
"attempt_count",
"created_at",
"started_at",
"ended_at",
"version",
"to",
"from",
"duration_ms",
"metadata",
"test"
],
"additionalProperties": false
},
"PublicationRef": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"digest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
}
},
"required": [
"agent_id",
"version",
"digest"
],
"additionalProperties": false
},
"RunOutcome": {
"type": "object",
"properties": {
"transport": {
"type": "string",
"enum": [
"completed",
"busy",
"no_answer",
"rejected",
"cancelled",
"provider_failure",
"admission_expired",
"not_applicable"
]
},
"execution": {
"type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"not_started",
"unknown"
]
},
"contact": {
"type": "string",
"enum": [
"human",
"voicemail",
"ivr",
"unknown",
"not_applicable"
]
},
"business": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"known"
]
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"unknown"
]
}
},
"required": [
"status"
],
"additionalProperties": false
}
]
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"result": {
"allOf": [
{
"$ref": "#/components/schemas/ContentRef"
}
],
"nullable": true
}
},
"required": [
"transport",
"execution",
"contact",
"business",
"reason",
"result"
],
"additionalProperties": false
},
"ContentRef": {
"type": "object",
"properties": {
"artifact_id": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"byte_size": {
"type": "integer",
"minimum": 0
},
"media_type": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"artifact_id",
"sha256",
"byte_size",
"media_type",
"expires_at"
],
"additionalProperties": false
},
"PrincipalRef": {
"anyOf": [
{
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"user"
]
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"kind",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"kind",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"system"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"owner_id",
"environment",
"kind",
"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 24925ed1Markdown source