openapi: 3.1.0
info:
  title: Relay App Automation Runs API
  description: The Relay.app API enables programmatic interaction with the Relay workflow automation platform. Developers can trigger workflow runs via webhooks, make custom HTTP requests to external systems, and manage automation through scheduled and event-based triggers. The API supports JSON payloads, custom response codes, and deduplication for webhook-triggered workflows.
  version: 1.0.0
  contact:
    url: https://docs.relay.app/
  license:
    name: Proprietary
    url: https://www.relay.app/terms
servers:
- url: https://api.relay.app/v1
  description: Relay App API
security:
- ApiKeyAuth: []
tags:
- name: Runs
  description: Operations for managing and inspecting workflow run instances
paths:
  /workflows/{workflowId}/runs:
    get:
      operationId: listWorkflowRuns
      summary: List Workflow Runs
      description: Retrieves a list of run instances for a specific workflow.
      tags:
      - Runs
      parameters:
      - name: workflowId
        in: path
        required: true
        description: The unique identifier of the workflow.
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filter runs by status.
        schema:
          type: string
          enum:
          - running
          - completed
          - failed
          - paused
          - cancelled
      - name: limit
        in: query
        required: false
        description: Number of results to return.
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: List of workflow runs returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunList'
  /runs/{runId}:
    get:
      operationId: getWorkflowRun
      summary: Get Workflow Run
      description: Retrieves the details and status of a specific workflow run.
      tags:
      - Runs
      parameters:
      - name: runId
        in: path
        required: true
        description: The unique identifier of the workflow run.
        schema:
          type: string
      responses:
        '200':
          description: Workflow run retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '404':
          description: Run not found.
  /runs/{runId}/cancel:
    post:
      operationId: cancelWorkflowRun
      summary: Cancel Workflow Run
      description: Cancels a currently running or paused workflow run.
      tags:
      - Runs
      parameters:
      - name: runId
        in: path
        required: true
        description: The unique identifier of the workflow run.
        schema:
          type: string
      responses:
        '200':
          description: Workflow run cancelled successfully.
        '400':
          description: Run cannot be cancelled in its current state.
        '404':
          description: Run not found.
  /runs/{runId}/approve:
    post:
      operationId: approveWorkflowRunStep
      summary: Approve Workflow Run Step
      description: Approves a paused workflow run step that is waiting for human-in-the-loop approval before proceeding to the next step.
      tags:
      - Runs
      parameters:
      - name: runId
        in: path
        required: true
        description: The unique identifier of the workflow run.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: Optional comment to include with the approval.
                inputs:
                  type: object
                  additionalProperties: true
                  description: Optional input data to provide for the next workflow step.
      responses:
        '200':
          description: Workflow run step approved successfully.
        '400':
          description: Run is not waiting for approval.
        '404':
          description: Run not found.
components:
  schemas:
    WorkflowRun:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the workflow run.
        workflowId:
          type: string
          description: The ID of the workflow being run.
        status:
          type: string
          enum:
          - running
          - completed
          - failed
          - paused
          - cancelled
          description: Current status of the workflow run.
        startedAt:
          type: string
          format: date-time
          description: Date and time the run was started.
        completedAt:
          type: string
          format: date-time
          description: Date and time the run was completed.
        error:
          type: string
          description: Error message if the run failed.
        inputData:
          type: object
          additionalProperties: true
          description: Input data provided when the run was triggered.
    WorkflowRunList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRun'
        totalCount:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Relay-API-Key
      description: API key for authenticating requests to the Relay App API.