---
title: "Create Run Chain"
method: POST
path: "/v1/runs/chain"
tags: ["runs"]
---

# Create Run Chain

`POST /v1/runs/chain`

Create a multi-step chain that runs on a single reserved session/machine.

- Starts a new session unless session_id is provided (then runs on existing session).
- Accepts shared_inputs/sensitive/file_inputs and per-step file_inputs.
- machine_id > pool_id when starting a new session; both ignored if session_id provided.
- Client contract: once runs are persisted, failures in downstream Temporal dispatch
  do not change the HTTP success envelope; response still contains run_ids and those
  runs are transitioned to ERROR with failure metadata for deterministic polling.

## Headers

- `Idempotency-Key` string

## Request body

- WorkflowChainCreate — Request to create and run a multi-step chain on a single reserved session/machine
  - `steps` ChainStep[], required
    - `workflow_id` string, uuid, required
    - `session_alias` string, nullable — Alias to persist this step's outputs within the session
    - `inputs` object, nullable — Step-specific inputs; values can be strings, objects, arrays, or {$ref: 'alias.outputs.path'} references
    - `sensitive_inputs` object, nullable — Step-specific sensitive inputs (supports nested objects) that override or extend shared_sensitive_inputs
  - `is_priority` boolean — Prioritize every run in this chain when assigning an eligible machine. Steps still execute in chain order.
  - `shared_inputs` object, nullable
  - `shared_sensitive_inputs` object, nullable — Shared sensitive inputs (supports nested objects) for all steps
  - `shared_file_inputs` FileInput[], nullable
    - `filename` string, required
    - `content` string, required — Base64 encoded file content
    - `target_path` string, nullable — Optional path on machine, defaults to ~/CyberdeskTransfers/
    - `cleanup_imports_after_run` boolean — Delete from machine after run completes
  - `keep_session_after_completion` boolean, nullable
  - `machine_id` string, uuid, nullable
  - `pool_ids` string[], nullable — Pool IDs to filter available machines when starting a new session. Machine must belong to ALL of these pools (intersection). Ignored when machine_id is provided.
  - `session_id` string, uuid, nullable

## Response `201`

Returns persisted run_ids for the created chain session. If Temporal dispatch fails after run persistence, this endpoint still returns 201 with run_ids; those runs are marked ERROR and include failure details in subsequent run reads.

- WorkflowChainResponse — Response for chain creation
  - `session_id` string, uuid, required
  - `run_ids` string[], required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud.md) · [All operations](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cyberdesk-hq/cyberdesk-cloud/revisions/830d2f48963d/schema)