openapi: 3.0.3
info:
  title: Sauce Labs Jobs Devices Sessions 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: Sessions
paths:
  /sessions:
    get:
      operationId: listSessions
      summary: List Active Sessions
      description: Returns all active real device sessions for the authenticated user.
      tags:
      - Sessions
      responses:
        '200':
          description: List of active sessions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  entities:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
                  metaData:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSession
      summary: Create a Device Session
      description: Allocates a real device and creates a new session. The device can be specified by ID or by descriptor criteria.
      tags:
      - Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreation'
      responses:
        '200':
          description: Session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sessions/{sessionId}:
    get:
      operationId: getSession
      summary: Get Session Details
      description: Returns full details for a specific real device session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: closeSession
      summary: Close a Session
      description: Terminates a real device session and releases the device.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session closed successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sessions/{sessionId}/device/executeShellCommand:
    post:
      operationId: executeShellCommand
      summary: Execute Shell Command on Device
      description: Runs a shell command on the device attached to the session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                command:
                  type: string
                  description: Shell command to execute.
      responses:
        '200':
          description: Command executed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sessions/{sessionId}/device/installApp:
    post:
      operationId: installApp
      summary: Install App on Device
      description: Installs an application on the device in the current session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - appUrl
              properties:
                appUrl:
                  type: string
                  format: uri
                  description: URL or storage reference to the app to install.
      responses:
        '200':
          description: App installed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sessions/{sessionId}/device/uninstallApp:
    delete:
      operationId: uninstallApp
      summary: Uninstall App from Device
      description: Removes an app from the device in the current session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - bundleId
              properties:
                bundleId:
                  type: string
                  description: Bundle identifier of the app to remove.
      responses:
        '200':
          description: App uninstalled.
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
    Session:
      type: object
      description: A real device session on Sauce Labs.
      properties:
        id:
          type: string
          description: Unique session ID.
        state:
          type: string
          enum:
          - CREATED
          - BOOTING
          - RUNNING
          - CLOSING
          - CLOSED
          - TIMED_OUT
          - ERROR
          description: Current lifecycle state of the session.
        expiresAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the session expires.
        retainUntil:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 timestamp until the session is retained.
        device:
          $ref: '#/components/schemas/Device'
        appium:
          $ref: '#/components/schemas/AppiumSession'
        links:
          type: object
          description: HATEOAS links for session actions.
          additionalProperties:
            type: string
    AppiumSession:
      type: object
      description: Appium-specific session metadata.
      properties:
        sessionId:
          type: string
        serverUrl:
          type: string
          format: uri
    SessionCreation:
      type: object
      description: Request body for creating a new real device session.
      required:
      - deviceDescriptorName
      properties:
        deviceDescriptorName:
          type: string
          description: Device model name to allocate.
        osVersion:
          type: string
          description: Minimum OS version required.
        privateDevicesOnly:
          type: boolean
          default: false
          description: Only allocate private devices.
        tunnelId:
          type: string
          nullable: true
          description: Sauce Connect tunnel ID for private network access.
    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:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    Unauthorized:
      description: Authentication credentials missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    BadRequest:
      description: Invalid request parameters.
      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/