openapi: 3.0.3
info:
  title: Sauce Labs Jobs Devices API
  description: Manage and retrieve test jobs running on Sauce Labs virtual and real device infrastructure. Supports listing jobs, fetching job assets such as logs, videos, and screenshots, updating job attributes, and stopping or deleting jobs.
  version: '1.1'
  contact:
    name: Sauce Labs Support
    url: https://support.saucelabs.com
  termsOfService: https://saucelabs.com/terms-of-service
  license:
    name: Proprietary
    url: https://saucelabs.com/terms-of-service
servers:
- url: https://api.us-west-1.saucelabs.com
  description: US West (primary)
- url: https://api.eu-central-1.saucelabs.com
  description: EU Central
security:
- basicAuth: []
tags:
- name: Devices
paths:
  /devices:
    get:
      operationId: listDevices
      summary: List Available Devices
      description: Returns the list of real devices available in the Sauce Labs cloud.
      tags:
      - Devices
      parameters:
      - name: organization_id
        in: query
        schema:
          type: string
        description: Filter devices by organization.
      - name: os
        in: query
        schema:
          type: string
          enum:
          - ANDROID
          - IOS
        description: Filter by operating system.
      responses:
        '200':
          description: List of devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
                  metaData:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /devices/status:
    get:
      operationId: getDevicesStatus
      summary: Get Device Availability Status
      description: Returns availability status for all devices in the cloud.
      tags:
      - Devices
      responses:
        '200':
          description: Device status map.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/DeviceStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DeviceDescriptor:
      type: object
      description: Hardware characteristics that identify a device model.
      properties:
        name:
          type: string
          description: Device model name (e.g., "iPhone 14").
        os:
          type: string
          enum:
          - ANDROID
          - IOS
          description: Operating system.
        osVersion:
          type: string
          description: OS version string.
        cpuType:
          type: string
          description: CPU architecture.
        cpuCores:
          type: integer
          description: Number of CPU cores.
        ramSize:
          type: integer
          description: RAM size in MB.
        screenSize:
          type: string
          description: Screen dimensions (e.g., "6.1 inches").
        resolutionWidth:
          type: integer
        resolutionHeight:
          type: integer
        formFactor:
          type: string
          enum:
          - PHONE
          - TABLET
    DeviceStatus:
      type: object
      description: Current availability state for a device.
      properties:
        deviceId:
          type: string
        status:
          type: string
          enum:
          - AVAILABLE
          - IN_USE
          - OFFLINE
          - MAINTENANCE
        sessionId:
          type: string
          nullable: true
          description: Current session ID if in use.
    Device:
      type: object
      description: A real physical device available in the Sauce Labs cloud.
      properties:
        descriptor:
          $ref: '#/components/schemas/DeviceDescriptor'
        isPrivateDevice:
          type: boolean
          description: Whether the device is exclusively available to your organization.
        state:
          type: string
          enum:
          - AVAILABLE
          - IN_USE
          - OFFLINE
          - MAINTENANCE
          description: Current state of the device.
        inUseBy:
          type: string
          nullable: true
          description: Username currently using the device, if in use.
    PaginationMeta:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        totalRecords:
          type: integer
    ErrorBody:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: Authentication credentials missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your Sauce Labs username and access key as the HTTP Basic Authentication credentials.
externalDocs:
  description: Sauce Labs Jobs API Documentation
  url: https://docs.saucelabs.com/dev/api/jobs/