Run a workflow

Runs a workflow. Returns immediately with the run queued.

POST /workflows/{workflow_id}/run

Run a workflow

cURL

curl --request POST \
  --url https://api.deck.co/v2/workflows/{workflow_id}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "steps": [
    {
      "name": "check_price",
      "credential_id": "<string>",
      "source_id": "<string>",
      "input": {}
    }
  ],
  "interactions_suppressed": true
}
'

201

{
  "id": "wrun_AbC123xYz456",
  "object": "<string>",
  "workflow_id": "wflo_AbC123xYz456",
  "status": "queued",
  "result": "<string>",
  "runtime_ms": 123,
  "session_id": "<string>",
  "trigger_id": "<string>",
  "steps": [
    {
      "name": "<string>",
      "type": "task",
      "status": "<string>",
      "output": "<unknown>",
      "task_runs": [
        {
          "task_run_id": "trun_AbC123xYz456",
          "status": "<string>",
          "result": "<string>",
          "created_at": "2026-06-18T00:00:00Z",
          "runtime_ms": 123,
          "errors": [
            {
              "type": "<string>",
              "code": "<string>",
              "message": "<string>",
              "field": "<string>"
            }
          ],
          "item": "<unknown>",
          "input": "<unknown>",
          "storage": [
            {
              "id": "stor_AbC123xYz456",
              "object": "<string>",
              "file_name": "<string>",
              "file_type": "<string>",
              "file_size": 123,
              "purpose": "attachment",
              "created_at": "2026-08-24T12:00:00Z",
              "url": "<string>",
              "extraction": "<unknown>"
            }
          ],
          "artifacts": {
            "screenshots": [
              {
                "file_name": "<string>",
                "file_type": "<string>",
                "file_size": 123,
                "created_at": "2026-08-24T12:00:00Z",
                "url": "<string>",
                "reasoning": "<string>"
              }
            ]
          }
        }
      ]
    }
  ],
  "errors": [
    {
      "type": "<string>",
      "code": "<string>",
      "message": "<string>",
      "field": "<string>",
      "step": "<string>"
    }
  ],
  "created_at": "2026-06-18T00:00:00Z",
  "updated_at": "2026-06-18T00:00:00Z",
  "request_id": "<string>",
  "interactions_suppressed": true
}

Authorizations

Authorization · string · header · required

Secret key (sk_live_...)

Headers

Idempotency-Key · string

Optional key that makes the request idempotent. Retrying with the same key returns the original response instead of repeating the operation; keys expire after 24 hours. Any string up to 256 characters. See Idempotency.

Maximum string length: 256

Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

workflow_id · string · required

Unique identifier for the workflow (prefixed with wflo_).

Pattern: ^wflo_

Example:

"wflo_AbC123xYz456"

Body

application/jsontext/jsonapplication/*+json

Request body for running a workflow. The body may be empty.

steps · null | object[]

Per-step overrides. Steps you don't list run exactly as defined.

Show child attributes

interactions_suppressed · boolean

When true, no step of the run sends an interaction (MFA code, security question) to your user. An interaction that needs a person fails the run with interaction_suppressed, and the credential stays valid. Defaults to false.

Response

201

text/plain

Created

Workflow run object.

id · string · required

Unique identifier for the workflow run, prefixed with wrun_.

Pattern: ^wrun_

Example:

"wrun_AbC123xYz456"

object · string · required

Always workflow_run.

workflow_id · string · required

The workflow that was run.

Pattern: ^wflo_

Example:

"wflo_AbC123xYz456"

status · enum<string> · required

Lifecycle state. paused means the current step is waiting on external input; the step's own status carries the reason.

Available options: queued, running, paused, completed, failed, canceling, canceled

result · null | string · required

Outcome once terminal: success only when every task run succeeded, failure if any failed, unknown otherwise. null while running and for a canceled run.

runtime_ms · null | integer<int64> · required

Milliseconds from the first step's start until the run reached a terminal status, excluding time spent queued. null until terminal.

session_id · null | string · required

The session every step of this run executes in. Prefixed with sess_. Assigned when the run is created through the API, or when a trigger-created run is admitted, so null while such a run is queued.

trigger_id · null | string · required

The trigger that created this run. Prefixed with trg_. null for runs created through the API.

steps · object[] · required

Per-step state, in definition order.

Show child attributes

errors · null | object[] · required

Error objects, each naming its step, when the run failed. null otherwise.

Show child attributes

created_at · string<date-time> · required

Example:

"2026-06-18T00:00:00Z"

updated_at · string<date-time> · required

Example:

"2026-06-18T00:00:00Z"

request_id · string

Unique identifier for the API request. Include this when contacting support.

interactions_suppressed · boolean

true when the run was created with interactions_suppressed. Omitted otherwise.