> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagescreen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a specific step

> Starts the named step. The step must be the next pending step in order.
If the step name does not match the expected next step, the run is
ended out of order and failed.




## OpenAPI

````yaml /openapi/private/specs/services/workflow.yml get /workflow/run/{run_id}/start_step/{step_name}
openapi: 3.1.0
info:
  title: Workflow Service API
  description: >
    Manages workflow runs and step-by-step state machine execution. Workflows

    are used to orchestrate multi-step processes like sage culture generation.


    ## Authentication

    All endpoints require authentication via API key:

    - **API Key**: Pass the key in the `X-Auth` header (service-to-service
    calls)


    ## Workflow Model

    - **Workflow Steps** (templates) define the step sequence for a workflow
    `type`

    - **Runs** are instances of a workflow type, tracking state and progress

    - **Run Steps** are materialized copies of template steps for each run


    ## State Machine

    ### Run States

    - `queued` -- created but not yet started

    - `running` -- actively progressing through steps

    - `finished` -- all steps completed successfully

    - `failed` -- a step failed or was executed out of order

    - `canceled` -- manually cancelled


    ### Step States

    - `pending` -- waiting to start

    - `running` -- actively executing

    - `finished` -- completed successfully

    - `failed` -- execution failed


    ## Business Rules

    - Steps must be executed in order; out-of-order transitions fail the entire
    run

    - A run cannot be transitioned if already finished, failed, or cancelled

    - Only one step can be running at a time

    - Cancelling a run fails all pending/running steps

    - The response `meta` object includes `steps`, `current_step`, `next_step`,
      `previous_step`, `first_step`, and `last_step` navigation aids
  version: 1.0.0
  contact:
    name: Platform Team
servers:
  - url: '{protocol}://{host}:{port}'
    description: Workflow Service
    variables:
      protocol:
        default: https
        enum:
          - http
          - https
      host:
        default: localhost
      port:
        default: '5000'
security: []
tags:
  - name: Workflow
    description: Workflow run management and step transitions
  - name: Service
    description: Health checks and initialization
paths:
  /workflow/run/{run_id}/start_step/{step_name}:
    get:
      tags:
        - Workflow
      summary: Start a specific step
      description: |
        Starts the named step. The step must be the next pending step in order.
        If the step name does not match the expected next step, the run is
        ended out of order and failed.
      operationId: startRunStep
      parameters:
        - $ref: '#/components/parameters/RunId'
        - name: step_name
          in: path
          required: true
          description: Name of the step to start
          schema:
            type: string
          example: reading_context
        - $ref: '#/components/parameters/RequiredPermission_valid'
      responses:
        '200':
          description: Step started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunWithMeta'
        '400':
          description: Invalid state or out-of-order step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                runEnded:
                  summary: Run already ended
                  value:
                    error: Run ended
                currentStepAlreadyStarted:
                  summary: A step is already running
                  value:
                    error: Current step already started
                stepOutOfOrder:
                  summary: Step is out of order
                  value:
                    error: 'Run Failed: Step cultural_training is out of order'
                runNotSet:
                  summary: Run not set
                  value:
                    error: Run not set
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Run not found
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKeyAuth: []
components:
  parameters:
    RunId:
      name: run_id
      in: path
      required: true
      description: UUID of the workflow run
      schema:
        type: string
        format: uuid
      example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
    RequiredPermission_valid:
      name: X-Permission-Info
      in: header
      required: false
      description: >-
        **Required API key permission: `valid`** (informational only -- enforced
        server-side)
      schema:
        type: string
  schemas:
    WorkflowRunWithMeta:
      allOf:
        - $ref: '#/components/schemas/WorkflowRun'
        - type: object
          properties:
            meta:
              type: object
              description: Navigation metadata for the run
              properties:
                steps:
                  type: array
                  items:
                    $ref: '#/components/schemas/WorkflowRunStep'
                  description: All steps in the run
                current_step:
                  $ref: '#/components/schemas/WorkflowRunStep'
                next_step:
                  $ref: '#/components/schemas/WorkflowRunStep'
                previous_step:
                  $ref: '#/components/schemas/WorkflowRunStep'
                first_step:
                  $ref: '#/components/schemas/WorkflowRunStep'
                last_step:
                  $ref: '#/components/schemas/WorkflowRunStep'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
    WorkflowRun:
      type: object
      description: Workflow run record (from WorkflowRunModel.to_dict())
      properties:
        id:
          type: string
          format: uuid
          description: Run UUID
        type:
          type: string
          description: Workflow type (e.g., `sage`, `sage-nc`)
        state:
          $ref: '#/components/schemas/RunStateEnum'
        percent:
          type: integer
          minimum: 0
          maximum: 100
          description: Progress percentage
        current_step:
          type:
            - string
            - 'null'
          description: ID of the currently running step (null when ended)
        started_at:
          type: string
          format: date-time
          description: When the run was created
        ended_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the run ended (null if still running)
        duration_ms:
          type:
            - integer
            - 'null'
          description: Total run duration in milliseconds
        number_of_steps:
          type: integer
          description: Total number of steps in this run
        result:
          type:
            - object
            - 'null'
          description: Run result data
        errors:
          type:
            - object
            - 'null'
          description: 'Error details (e.g., `{"message": "Run canceled"}`)'
    WorkflowRunStep:
      type: object
      description: Materialized step for a run (from WorkflowRunStepModel.to_dict())
      properties:
        id:
          type: string
          format: uuid
          description: Step UUID
        run_id:
          type: string
          format: uuid
          description: Parent run UUID
        name:
          type: string
          description: Step name (e.g., `creating_sage`, `reading_context`)
        step_order:
          type: integer
          description: Position in sequence (0-indexed)
        state:
          $ref: '#/components/schemas/StepStateEnum'
        timing_avg_ms:
          type:
            - integer
            - 'null'
          description: Average expected duration (from template)
        timing_min_ms:
          type:
            - integer
            - 'null'
          description: Minimum expected duration
        timing_max_ms:
          type:
            - integer
            - 'null'
          description: Maximum expected duration
        label:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Display labels for the step
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the step started
        ended_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the step ended
        duration_ms:
          type:
            - integer
            - 'null'
          description: Actual duration in milliseconds
        number_of_steps:
          type: integer
          description: Total steps in the parent run
        current_duration:
          type: number
          description: Elapsed time in ms (only present when state is `running`)
    RunStateEnum:
      type: string
      enum:
        - queued
        - running
        - finished
        - failed
        - canceled
      description: |
        Current state of the workflow run:
        - `queued` -- created but not yet started
        - `running` -- actively executing steps
        - `finished` -- all steps completed successfully
        - `failed` -- a step failed or out-of-order transition
        - `canceled` -- manually cancelled
    StepStateEnum:
      type: string
      enum:
        - pending
        - running
        - finished
        - failed
      description: |
        Current state of a workflow step:
        - `pending` -- waiting to start
        - `running` -- actively executing
        - `finished` -- completed successfully
        - `failed` -- execution failed
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            noApiKey:
              summary: Missing API key
              value:
                error: Unauthorized - API key required
            invalidApiKey:
              summary: Invalid API key
              value:
                error: Unauthorized - Invalid API key
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Internal server error
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Auth
      description: Service-to-service API key

````