> ## Documentation Index > Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Run 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. ## OpenAPI ````yaml /openapi.json post /v1/runs/chain openapi: 3.1.0 info: title: Cyberdesk Cloud description: >- The Cyberdesk API provides programmatic access to all platform features, enabling you to automate desktop tasks at scale. version: 1.0.0 servers: - url: https://api.cyberdesk.io description: Production server - url: https://cyberdesk-api-dev.fly.dev description: Development server security: [] paths: /v1/runs/chain: post: tags: - runs summary: Create Run Chain description: >- 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. operationId: create_run_chain_v1_runs_chain_post parameters: - name: Idempotency-Key in: header required: false description: >- Unique key for idempotent requests. If provided, the server ensures the request is processed at most once. Retries with the same key return the original response. SDKs auto-generate this for write requests. schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkflowChainCreate' required: true responses: '201': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/WorkflowChainResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: WorkflowChainCreate: properties: steps: items: $ref: '#/components/schemas/ChainStep' type: array minItems: 1 title: Steps shared_inputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Shared Inputs shared_sensitive_inputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Shared Sensitive Inputs description: Shared sensitive inputs (supports nested objects) for all steps shared_file_inputs: anyOf: - items: $ref: '#/components/schemas/FileInput' type: array - type: 'null' title: Shared File Inputs keep_session_after_completion: anyOf: - type: boolean - type: 'null' title: Keep Session After Completion default: false machine_id: anyOf: - type: string format: uuid - type: 'null' title: Machine Id pool_ids: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Pool Ids description: >- 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: anyOf: - type: string format: uuid - type: 'null' title: Session Id type: object required: - steps title: WorkflowChainCreate description: >- Request to create and run a multi-step chain on a single reserved session/machine WorkflowChainResponse: properties: session_id: type: string format: uuid title: Session Id run_ids: items: type: string format: uuid type: array title: Run Ids type: object required: - session_id - run_ids title: WorkflowChainResponse description: Response for chain creation HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ChainStep: properties: workflow_id: type: string format: uuid title: Workflow Id session_alias: anyOf: - type: string - type: 'null' title: Session Alias description: Alias to persist this step's outputs within the session inputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Inputs description: >- Step-specific inputs; values can be strings, objects, arrays, or {$ref: 'alias.outputs.path'} references sensitive_inputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Sensitive Inputs description: >- Step-specific sensitive inputs (supports nested objects) that override or extend shared_sensitive_inputs type: object required: - workflow_id title: ChainStep description: One step within a chain FileInput: properties: filename: type: string title: Filename content: type: string title: Content description: Base64 encoded file content target_path: anyOf: - type: string - type: 'null' title: Target Path description: Optional path on machine, defaults to ~/CyberdeskTransfers/ cleanup_imports_after_run: type: boolean title: Cleanup Imports After Run description: Delete from machine after run completes default: false type: object required: - filename - content title: FileInput description: File input for run creation ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object additionalProperties: true title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````