Mabl Mobile Training Session API

openapi: 3.2.0
info:
  title: mabl Mobile Training Session API
  description: APIs for interacting with mabl services
  version: 0.599.3.1792436330
  x-readme-id: 62c896636916ce01d2ff4f5a
servers:
- url: /
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: MobileTrainingSession
paths:
  /mobile/training/sessions:
    get:
      tags:
      - MobileTrainingSession
      summary: Query mobile training sessions
      operationId: queryMobileTrainingSessions
      parameters:
      - name: workspace_id
        in: query
        description: ID of the workspace for which to query mobile training sessions
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: status
        in: query
        description: Optional status to query by
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        description: The limit to use for pagination
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
      - name: cursor
        in: query
        description: The cursor to use for pagination
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: The mobile training session query result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileTrainingSessionQueryResult'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::MobileTrainingSession
    post:
      tags:
      - MobileTrainingSession
      summary: Launches a new mobile training session
      operationId: createMobileTrainingSession
      requestBody:
        description: The mobile training session to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileTrainingSessionPrototype'
        required: true
      responses:
        '201':
          description: The mobile training session that was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileTrainingSession'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Run::MobileTrainingSession
  /cron/mobile/training/sessions/cleanup:
    get:
      tags:
      - MobileTrainingSession
      summary: Clean up all terminated sessions
      operationId: cleanupMobileTrainingSessions
      responses:
        '204':
          description: Cleanup successful
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Delete::MobileTrainingSession
  /mobile/training/session/{id}:
    get:
      tags:
      - MobileTrainingSession
      description: Used to retrieve a specific mobile training session
      operationId: getMobileTrainingSession
      parameters:
      - name: id
        in: path
        description: The ID of the mobile training session to retrieve
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: The mobile training session with the given ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileTrainingSession'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::MobileTrainingSession
      summary: Get mobile training session
      x-summary-source: derived
    delete:
      tags:
      - MobileTrainingSession
      description: Used to remove a specific mobile training session. If not in terminated status, terminates it first with session_closed termination reason.
      operationId: removeMobileTrainingSession
      parameters:
      - name: id
        in: path
        description: The ID of the mobile training session to remove
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: Mobile training session removed
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Delete::MobileTrainingSession
      summary: Remove mobile training session
      x-summary-source: derived
    patch:
      tags:
      - MobileTrainingSession
      description: Used to update a mobile training session
      operationId: updateMobileTrainingSession
      parameters:
      - name: id
        in: path
        description: The ID of the mobile training session to retrieve
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: If-Match
        in: header
        description: If-Match header according to http/1.1 spec section 14.24
        required: false
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        description: The mobile training session to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileTrainingSessionUpdate'
        required: true
      responses:
        '200':
          description: The updated mobile training session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileTrainingSession'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Edit::MobileTrainingSession
      summary: Update mobile training session
      x-summary-source: derived
  /mobile/training/session/{id}/backend:
    get:
      tags:
      - MobileTrainingSession
      description: Used by the training proxy to find the backend address for connection routing for this session
      operationId: getMobileTrainingSessionBackend
      parameters:
      - name: id
        in: path
        description: The ID of the mobile training session
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: The backend address is returned in the X-Mabl-Backend header
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        '410':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::MobileTrainingSession
      summary: Get mobile training session backend
      x-summary-source: derived
  /mobile/training/session/{id}/extend:
    post:
      tags:
      - MobileTrainingSession
      description: Used to extend the expiration time on an existing mobile training session
      operationId: extendMobileTrainingSession
      parameters:
      - name: id
        in: path
        description: The ID of the mobile training session to extend
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: The mobile training session that was extended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileTrainingSessionExtensionResult'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Run::MobileTrainingSession
      summary: Extend mobile training session
      x-summary-source: derived
  /mobile/training/session/{id}/terminate:
    post:
      tags:
      - MobileTrainingSession
      description: Used to trigger the termination of an existing mobile training session
      operationId: terminateMobileTrainingSession
      parameters:
      - name: id
        in: path
        description: The ID of the mobile training session to terminate
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        description: The mobile training session termination details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileTrainingSessionTermination'
        required: true
      responses:
        '200':
          description: The mobile training session that was terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileTrainingSession'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Edit::MobileTrainingSession
      summary: Terminate mobile training session
      x-summary-source: derived
components:
  schemas:
    MobileTrainingSessionPrototype:
      required:
      - mobile_app_file_id
      - workspace_id
      type: object
      description: Request to create a new mobile training session
      allOf:
      - $ref: '#/components/schemas/MobileTrainingSessionPrototypeProperties'
      x-implements-interface:
      - HasWorkspaceId
    MobileTrainingSessionInstance:
      required:
      - display_name
      - id
      type: object
      properties:
        display_name:
          type: string
          description: Friendly name for the instance that is hosting this training session
        id:
          type: string
          description: Globally unique ID for the instance that is hosting this training session (e.g. GCE VM instance number as "gce-<number>", GKE pod ID "gke-<number>", EC2 instance ID as "ec2-<ID>")
        ipAddress:
          type: string
          description: IP address of the instance that is hosting this training session
        mobileTrainingServerPort:
          maximum: 65535
          minimum: 1
          type: integer
          description: Port on the instance where the mobile training server for this session is listening
          format: int32
        provenance:
          type: string
          description: Indicates where this instance came from
          enum:
          - hot_pool
          - on_demand
        zone:
          type: string
          description: Zone where the instance that is hosting this training session is running
    MobileDeviceConfiguration:
      required:
      - device_manufacturer
      - device_name
      - os_version
      - platform
      - screen_dimensions
      type: object
      properties:
        created_by_id:
          type: string
          description: The ID of the user who created this configuration
        created_time:
          type: integer
          description: The time at which this configuration was created
          format: int64
        cloud_training_hot_pool_support:
          type: boolean
          description: Device is included in the cloud training hot pool
        cloud_runner_hot_pool_support:
          type: boolean
          description: Device is included in the cloud runner hot pool
          default: false
        cloud_training_support:
          type: boolean
          description: Device supports cloud training
        id:
          maxLength: 50
          type: string
          description: The unique ID for this configuration entity
        last_updated_by_id:
          type: string
          description: The ID of the user who last updated this configuration
        last_updated_time:
          type: integer
          description: The time at which this configuration was last updated
          format: int64
        platform:
          $ref: '#/components/schemas/MobilePlatformEnum'
        device_manufacturer:
          type: string
          description: Device manufacturer (Apple, Google, Samsung)
        device_name:
          type: string
          description: Device display name (iPhone 14, Pixel 7 Pro)
        device_id:
          type: string
          description: Vendor unique device id (pixel_7_pro)
        screen_dimensions:
          $ref: '#/components/schemas/DeviceScreenDimensions'
        os_version:
          type: string
          description: OS version (16.6.1, Oreo, 12.0)
        retired:
          type: boolean
          description: The configuration is no longer supported for new runs. Retired configurations are still returned so that plans and tests already referencing them can be displayed, but they cannot be selected or executed.
          default: false
        android_configuration:
          $ref: '#/components/schemas/AndroidDeviceConfiguration'
      description: Represents a mobile device configuration (model, OS version) for executing mobile tests
      x-implements-interface:
      - HasId
      - HasCreatedActivity
    MobileTrainingSessionUpdateProperties:
      type: object
      properties:
        execution_runner_id:
          type: string
          description: The ID of the associated ExecutionRunner, if any
        instance:
          $ref: '#/components/schemas/MobileTrainingSessionInstance'
        status:
          $ref: '#/components/schemas/MobileTrainingSessionStatus'
    MobileTrainingSession:
      required:
      - created_by_id
      - created_time
      - id
      - is_active
      - last_updated_by_id
      - last_updated_time
      - mobile_app_file_id
      - mobile_device_configuration
      - session_key
      - status
      - workspace_id
      type: object
      description: State related to a mobile cloud training session
      allOf:
      - $ref: '#/components/schemas/MobileTrainingSessionPrototypeProperties'
      - $ref: '#/components/schemas/MobileTrainingSessionTerminationProperties'
      - $ref: '#/components/schemas/MobileTrainingSessionUpdateProperties'
      - type: object
        properties:
          connect_url:
            type: string
            description: URL clients should use to make connections to this mobile cloud training session
            readOnly: true
          created_by_id:
            type: string
            description: The ID of the client/user who created this mobile training session
            readOnly: true
          created_time:
            type: integer
            description: Time at which the mobile training session was created
            format: int64
            readOnly: true
          deleted_by_id:
            type: string
            description: The ID of the client/user who deleted this mobile training session
            readOnly: true
          deleted_time:
            type: integer
            description: Time at which this mobile training session was deleted
            format: int64
            readOnly: true
          expiration_time:
            type: integer
            description: Time at which this mobile training session will expire
            format: int64
            readOnly: true
          id:
            type: string
            description: The mobile training session id
            readOnly: true
          is_active:
            type: boolean
            description: Whether or not the session is currently active (status != terminated).
            readOnly: true
          is_initializing:
            type: boolean
            description: Whether or not the session is currently initializing (status != (READY || TERMINATED))
            readOnly: true
          last_extended_time:
            type: integer
            description: Time at which the mobile training session was last extended
            format: int64
            readOnly: true
          last_updated_by_id:
            type: string
            description: The ID of the client/user who last updated this mobile training session
            readOnly: true
          last_updated_time:
            type: integer
            description: Time at which the mobile training session was last updated
            format: int64
            readOnly: true
          session_end_time:
            type: integer
            description: Time at which the mobile training session entered terminated status
            format: int64
            readOnly: true
          session_key:
            type: string
            description: Secret key used to authenticate connections to the cloud training session server
            readOnly: true
          session_start_time:
            type: integer
            description: Time at which the mobile training session entered ready status
            format: int64
            readOnly: true
          terminated_by_id:
            type: string
            description: The ID of the client/user who terminated this mobile training session
            readOnly: true
      x-implements-interface:
      - ActivityTrackingBaseEntity
      - HasDeletedActivity
      - HasWorkspaceId
    MobileTrainingSessionStatus:
      type: string
      description: Represents the current status of a mobile training session
      enum:
      - queued
      - scheduling
      - provisioning
      - initializing
      - ready
      - terminated
    GuardrailApprovalKind:
      type: string
      description: Who decides a guardrail approval. SELF is decided by the person the agent acts for; WORKSPACE, for an agent acting for an API key, by a workspace owner or editor.
      enum:
      - SELF
      - WORKSPACE
    MobileTrainingSessionQueryResult:
      type: object
      properties:
        mobile_training_sessions:
          type: array
          description: All mobile training sessions that matched the query
          readOnly: true
          items:
            $ref: '#/components/schemas/MobileTrainingSession'
        cursor:
          type: string
          description: Cursor used for pagination
          readOnly: true
    AndroidDeviceConfiguration:
      type: object
      properties:
        api_level:
          type: string
          description: Version of API this device is running (34, 33).
        abi:
          type: string
          description: Application boundary interface identifies combination of CPU and instruction set (x86, x86_64)
      description: Android specific options
    GuardrailApprovalRef:
      type: object
      properties:
        id:
          type: string
          description: The approval's id.
        state:
          description: Where the approval stands.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalState'
        kind:
          description: Who decides the approval.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalKind'
        request_expires_time:
          type: integer
          description: When the approval expires if nobody decides it, in epoch milliseconds.
          format: int64
        url:
          type: string
          description: The mabl app page where a person reviews the approval.
      description: 'An approval a guardrail policy asks for. While it is PENDING, stop: give the person the url, tell them the request is waiting for approval, and do not repeat the request or poll in a loop. Once a person tells you it is APPROVED, repeat the identical request with the header X-Mabl-Approval set to id. DENIED means a person said no, so do not work around it.'
    ErrorResponseGeneric:
      type: object
      properties:
        id:
          type: string
          x-mabl-scope: public
        code:
          maximum: 599
          minimum: 100
          type: integer
          format: int32
          x-mabl-scope: public
        message:
          type: string
          x-mabl-scope: public
        error_code:
          type: string
          description: Machine-readable reason for the error, present only when the API names one. Values are guardrail_blocked (a guardrail policy refused an agent request), approval_required (a guardrail policy requires a person to approve the request first).
        guardrail:
          description: The guardrail policy that refused the request; present only when error_code is guardrail_blocked or approval_required.
          allOf:
          - $ref: '#/components/schemas/GuardrailRefusal'
    MobilePlatformEnum:
      type: string
      description: The mobile platform associated with this object
      enum:
      - android
      - ios
      x-mabl-scope: public
    DeviceScreenDimensions:
      required:
      - height
      - width
      type: object
      properties:
        height:
          type: integer
          description: Height (pixels)
          format: int32
          x-mabl-scope: public
        width:
          type: integer
          description: Width (pixels)
          format: int32
          x-mabl-scope: public
    MobileTrainingSessionExtensionResult:
      type: object
      properties:
        can_extend_again:
          type: boolean
          description: Flag indicating whether or not the session can be extended a subsequent time
          readOnly: true
        extended:
          type: boolean
          description: Flag to indicate whether or not the session was allowed to be extended
          readOnly: true
        rejection_reason:
          type: string
          readOnly: true
          enum:
          - expired
          - max_session_length_exceeded
          - too_early
        session:
          $ref: '#/components/schemas/MobileTrainingSession'
    MobileTrainingSessionTerminationProperties:
      type: object
      properties:
        status_cause:
          type: string
        termination_reason:
          $ref: '#/components/schemas/MobileTrainingSessionTerminationReason'
    GuardrailRefusal:
      type: object
      properties:
        id:
          type: string
          description: The id of the guardrail policy that decided the refusal.
        reason:
          type: string
          description: Why the policy refuses the request, written for the person the agent acts for.
        decision_id:
          type: string
          description: The id of this decision in the guardrail decision log.
        action:
          type: string
          description: The action the request was evaluated as, written Verb::Resource (for example Delete::Test), as declared by the operation's x-mabl-action extension.
        policy_source:
          type: string
          description: 'Who set the deciding policy: workspace for a rule the workspace''s owners wrote, account for a rule set for the workspace''s account, mabl_agent_type for the agent type''s ceiling, and mabl_default for mabl''s own defaults.'
        approval:
          description: The approval for this request; present when error_code is approval_required and the approval could be recorded. Without it the request cannot be approved.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalRef'
      description: The guardrail policy that refused an agent request.
    GuardrailApprovalState:
      type: string
      description: Where a guardrail approval stands. PENDING awaits a decision and expires undecided after 24 hours; APPROVED lets the agent repeat the request, as often as it does, for 20 minutes; DENIED refuses the same request for 20 minutes after the decision, after which asking again opens a new approval; CANCELLED means a person withdrew it while pending or revoked it while approved. EXPIRED and CANCELLED are final.
      enum:
      - PENDING
      - APPROVED
      - DENIED
      - EXPIRED
      - CANCELLED
    MobileTrainingSessionTermination:
      required:
      - termination_reason
      type: object
      description: Request to terminate a mobile training session
      allOf:
      - $ref: '#/components/schemas/MobileTrainingSessionTerminationProperties'
    MobileTrainingSessionPrototypeProperties:
      type: object
      properties:
        mobile_app_file_id:
          type: string
          description: id of the mobile app file to install
        mobile_device_configuration:
          $ref: '#/components/schemas/MobileDeviceConfiguration'
        mobile_device_configuration_id:
          type: string
          description: The id of the mobile device configuration to use for the training session.  If specified, overrides the mobile_device_configuration.
        target_runtime_version:
          type: string
          description: Custom image ID to use for the training session
        workspace_id:
          type: string
          description: The id of the workspace for the mobile training session
        requires_gpu:
          type: boolean
          description: true if the mobile training requires a GPU to run
    MobileTrainingSessionTerminationReason:
      type: string
      description: The reason why a mobile training session was terminated
      enum:
      - insufficient_quota
      - scheduling_timeout
      - session_closed
      - session_expired
      - startup_failed
      - startup_timeout
      - no_gpus_available
    MobileTrainingSessionUpdate:
      required:
      - status
      type: object
      description: Update to apply to the mobile training session
      allOf:
      - $ref: '#/components/schemas/MobileTrainingSessionUpdateProperties'
  responses:
    ErrorResponse400:
      description: Invalid or missing parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse403:
      description: User not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse:
      description: Unknown error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse401:
      description: User not authenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse404:
      description: Entity not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: apiKey
      name: Authorization
      in: header