SOFY Scheduled Runs API

openapi: 3.1.0
info:
  title: SOFY Public Applications Scheduled Runs API
  version: 2026-07
  description: 'The SOFY Public API lets you drive the SOFY AI testing platform from CI/CD and automation systems: upload application builds, trigger scheduled test runs, poll their status, list test-run groups, and abort runs. Captured faithfully from the public SOFY documentation at docs.sofy.ai; SOFY does not publish a machine-readable OpenAPI document, so this specification was authored from the documented endpoints, headers, parameters, and example responses. All operations authenticate with an API access key passed in the `x-sofy-auth-key` header, generated under Account Settings > API Key.'
  contact:
    name: SOFY Support
    url: https://sofy.ai/contact-us/
  x-apievangelist-provenance:
    method: searched
    source:
    - https://docs.sofy.ai/schedule-runs/triggering-scheduled-runs-with-apis
    - https://docs.sofy.ai/schedule-runs/scheduled-run-status-endpoints-migration
    - https://docs.sofy.ai/schedule-runs/fetch-schedule-test-run-group-ids-endpoint-migration
    - https://docs.sofy.ai/schedule-runs/abort-scheduled-runs-using-c-url-commands-1
    - https://docs.sofy.ai/upload-applications/upload-application-endpoints-migration-and-route-errors
    - https://docs.sofy.ai/account-setting/generating-api-access-keys
servers:
- url: https://public.sofy.ai
  description: SOFY public API gateway
security:
- sofyAuthKey: []
tags:
- name: Scheduled Runs
  description: Trigger, monitor, and abort scheduled test runs.
paths:
  /scheduler-microservice/scheduled-runs/{scheduledGUID}/execute:
    post:
      operationId: triggerScheduledRun
      tags:
      - Scheduled Runs
      summary: Trigger a scheduled run
      description: Queue a previously configured scheduled run for execution against the given build and devices. No request body is required; all parameters are passed via the URL.
      parameters:
      - name: scheduledGUID
        in: path
        required: true
        description: The scheduled run identifier from your configuration.
        schema:
          type: string
      - name: appHash
        in: query
        required: true
        description: The application hash value returned by uploadApplication.
        schema:
          type: string
      - name: deviceSerials
        in: query
        required: true
        description: Comma-separated list of device identifiers to run against.
        schema:
          type: string
      responses:
        '200':
          description: Test runs are scheduled and in queue.
          content:
            application/json:
              schema:
                type: object
                properties:
                  testGroupsRunId:
                    type: string
                  message:
                    type: string
              example:
                testGroupsRunId: '123456'
                message: Test runs are scheduled and in queue.
  /scheduler-microservice/scheduled-runs/{scheduledRunGuid}/status/{testRunGroupId}:
    get:
      operationId: getScheduledRunStatus
      tags:
      - Scheduled Runs
      summary: Get scheduled run status
      description: Retrieve the execution status for a specific test run group within a scheduled run.
      parameters:
      - name: scheduledRunGuid
        in: path
        required: true
        schema:
          type: string
      - name: testRunGroupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status of the scheduled run.
          content:
            application/json:
              schema:
                type: object
                properties:
                  scheduledRunName:
                    type: string
                  testRunGroupId:
                    type: string
                  scenarioName:
                    type: string
                  scheduledAt:
                    type: string
                    format: date-time
                  build:
                    type: string
                  device:
                    type: string
                  status:
                    type: string
                    description: 'Execution status. One of: Not Executed, Incomplete, Passed, Failed, Stopped, Running.'
  /scheduler-microservice/scheduled-runs/{scheduledRunGuid}/test-run-groups:
    get:
      operationId: fetchTestRunGroupIds
      tags:
      - Scheduled Runs
      summary: Fetch test run group IDs
      description: List the test run groups for a scheduled run.
      parameters:
      - name: scheduledRunGuid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Test run groups for the scheduled run.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    testRunGroupId:
                      type: string
                    executedAt:
                      type: string
                      format: date-time
                    status:
                      type: string
                      description: 'One of: Queued, Running, Complete, Complete with errors.'
                    message:
                      type: string
  /scheduler-microservice/public/test-run/abort/{scheduledRunGuid}:
    put:
      operationId: abortScheduledRun
      tags:
      - Scheduled Runs
      summary: Abort a scheduled run
      description: Abort an active scheduled run. If testRunGroupId is omitted, all active executions under the scheduled run are aborted.
      parameters:
      - name: scheduledRunGuid
        in: path
        required: true
        schema:
          type: string
      - name: testRunGroupId
        in: query
        required: false
        description: Specific test run group to abort; omit to abort all active executions.
        schema:
          type: string
      responses:
        '200':
          description: Scheduled run aborted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Scheduled run 0CF78E5E-05CE-4971-A954-0E3789140DFD aborted by user 5ACD1A78-18FF-4213-B5F5-671C4B2F2B9D successfully.
components:
  securitySchemes:
    sofyAuthKey:
      type: apiKey
      in: header
      name: x-sofy-auth-key
      description: API access key generated under Account Settings > API Key. Required on every request.