openapi: 3.0.3
info:
  title: Kobiton REST API
  description: >-
    The Kobiton REST API programmatically operates the Kobiton mobile device
    cloud and app testing platform. It exposes the real device cloud (list and
    filter available iOS/Android devices), test sessions and their captured
    commands, the app repository (upload and manage app builds), data-driven
    testing data sets, scriptless (no-code) test runs via revisit plans, and
    organization member administration. Scripted automation runs against the
    separate Appium/WebDriver hub at https://api.kobiton.com/wd/hub and is not
    modeled here. All REST requests authenticate with HTTP Basic auth using a
    Kobiton username (or email) as the user and an API key as the password;
    the pair is base64-encoded in the Authorization header.

    Endpoints for Devices, Apps, Data Sets, Scriptless Automation (revisit
    plans), and Organization are grounded in Kobiton's published API docs and
    official samples. Session sub-resources (get session, get session commands)
    are grounded in Kobiton's get-session-data sample. Request and response
    schemas below are modeled from the documentation and sample payloads and
    should be reconciled against the live api.kobiton.com/docs reference; a
    newer v2 API also exists at https://api.kobiton.com/v2.
  version: '1.0'
  contact:
    name: Kobiton
    url: https://kobiton.com
servers:
  - url: https://api.kobiton.com/v1
    description: Kobiton REST API v1
security:
  - basicAuth: []
tags:
  - name: Devices
    description: Real devices available in the Kobiton device cloud.
  - name: Sessions
    description: Test-run sessions and their captured commands.
  - name: Scriptless Automation
    description: No-code test runs driven by revisit plans.
  - name: Apps
    description: The app repository of builds under test.
  - name: Data Sets
    description: Data-driven testing input sets.
  - name: Organization
    description: Organization member administration.
paths:
  /devices:
    get:
      operationId: listDevices
      tags:
        - Devices
      summary: List available devices
      description: >-
        Returns all devices the current user can access - public cloud,
        favorites, and private/local devices - with device metadata. Supports
        filtering to locate a device to book for a test run.
      parameters:
        - name: isOnline
          in: query
          schema:
            type: boolean
          description: Whether the device is currently online.
        - name: isBooked
          in: query
          schema:
            type: boolean
          description: Whether the device is currently booked.
        - name: platformName
          in: query
          schema:
            type: string
            enum: [Android, iOS]
          description: The device platform.
        - name: platformVersion
          in: query
          schema:
            type: string
          description: The platform / OS version of the device.
        - name: deviceName
          in: query
          schema:
            type: string
          description: The device name; accepts an exact name or a comma-separated list of names.
        - name: appiumDisabled
          in: query
          schema:
            type: boolean
          description: Filter by whether the device can run Appium automation tests.
        - name: groupId
          in: query
          schema:
            type: integer
          description: For organization users, restrict to devices in a device group.
      responses:
        '200':
          description: The devices accessible to the current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sessions/{sessionId}:
    get:
      operationId: getSession
      tags:
        - Sessions
      summary: Get a session
      description: >-
        Retrieves a test-run session by its Kobiton session ID, including
        device, app, state, and timing metadata. Grounded in the
        get-session-data sample.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: The session record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Session not found.
  /sessions/{sessionId}/commands:
    get:
      operationId: getSessionCommands
      tags:
        - Sessions
      summary: Get session commands
      description: >-
        Returns the paginated list of commands (the step-by-step Appium /
        WebDriver actions) captured during a session. Grounded in the
        get-session-data sample, which shows currentPage / totalPages
        pagination.
      parameters:
        - $ref: '#/components/parameters/SessionId'
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: The page of commands to retrieve.
      responses:
        '200':
          description: A page of session commands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCommandsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /revisitPlans/start:
    post:
      operationId: startScriptlessAutomation
      tags:
        - Scriptless Automation
      summary: Start a scriptless automation run
      description: >-
        Starts a scriptless (no-code) automated test run by replaying one or
        more baseline exploration sessions across a target device bundle.
        Grounded in the scriptless-automation use-rest-api docs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevisitPlanStartRequest'
      responses:
        '200':
          description: The scriptless run was accepted / started.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/uploadUrl:
    post:
      operationId: createAppUploadUrl
      tags:
        - Apps
      summary: Generate a pre-signed app upload URL
      description: >-
        Returns a pre-signed S3 URL to which the app binary is uploaded with an
        HTTP PUT before the app or version is created.
      responses:
        '200':
          description: A pre-signed upload URL and app path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppUploadUrl'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps:
    get:
      operationId: listApps
      tags:
        - Apps
      summary: List applications
      description: Lists the applications in the app repository.
      responses:
        '200':
          description: A list of applications.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApp
      tags:
        - Apps
      summary: Create an application or version
      description: >-
        Registers a new application or a new version of an existing application
        from a previously uploaded binary.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppRequest'
      responses:
        '200':
          description: The created application or version.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteApps
      tags:
        - Apps
      summary: Delete multiple applications
      description: Deletes multiple applications by ID.
      responses:
        '204':
          description: The applications were deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/{appId}:
    get:
      operationId: getApp
      tags:
        - Apps
      summary: Get an application
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The application details.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteApp
      tags:
        - Apps
      summary: Delete an application
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '204':
          description: The application was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/{appId}/private:
    put:
      operationId: makeAppPrivate
      tags:
        - Apps
      summary: Make an application private
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The application visibility was updated to private.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/{appId}/public:
    put:
      operationId: makeAppPublic
      tags:
        - Apps
      summary: Make an application public
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The application visibility was updated to public.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/{appId}/team/assign:
    post:
      operationId: assignAppToTeams
      tags:
        - Apps
      summary: Assign an application to teams
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The application was assigned to the specified teams.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /app/versions/{versionId}:
    get:
      operationId: getAppVersion
      tags:
        - Apps
      summary: Get an application version
      parameters:
        - $ref: '#/components/parameters/VersionId'
      responses:
        '200':
          description: The application version details.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteAppVersion
      tags:
        - Apps
      summary: Delete an application version
      parameters:
        - $ref: '#/components/parameters/VersionId'
      responses:
        '204':
          description: The version was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /app/versions/{versionId}/tag/{name}:
    post:
      operationId: addAppVersionTag
      tags:
        - Apps
      summary: Assign a tag to an app version
      parameters:
        - $ref: '#/components/parameters/VersionId'
        - $ref: '#/components/parameters/TagName'
      responses:
        '200':
          description: The tag was assigned to the version.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: removeAppVersionTag
      tags:
        - Apps
      summary: Remove a tag from an app version
      parameters:
        - $ref: '#/components/parameters/VersionId'
        - $ref: '#/components/parameters/TagName'
      responses:
        '204':
          description: The tag was removed from the version.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data-sets:
    get:
      operationId: listDataSets
      tags:
        - Data Sets
      summary: List data sets in a session
      description: Returns the data-driven testing data sets in the specified session.
      responses:
        '200':
          description: The data sets in the session.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data-sets/by-command:
    post:
      operationId: createDataSetByCommand
      tags:
        - Data Sets
      summary: Create a data set by command ID
      responses:
        '200':
          description: The created data set.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data-sets/by-element:
    post:
      operationId: createDataSetByElement
      tags:
        - Data Sets
      summary: Create a data set by element property
      responses:
        '200':
          description: The created data set.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data-sets/{dataSetId}/actions/by-command:
    put:
      operationId: updateDataSetByCommand
      tags:
        - Data Sets
      summary: Update a data set by command ID
      parameters:
        - $ref: '#/components/parameters/DataSetId'
      responses:
        '200':
          description: The data set was updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data-sets/{dataSetId}/actions/by-element:
    put:
      operationId: updateDataSetByElement
      tags:
        - Data Sets
      summary: Update a data set by element property
      parameters:
        - $ref: '#/components/parameters/DataSetId'
      responses:
        '200':
          description: The data set was updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /organizations/member:
    post:
      operationId: createOrganizationMember
      tags:
        - Organization
      summary: Create an organization member
      responses:
        '200':
          description: The member was created.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /organizations/activate/member:
    put:
      operationId: activateOrganizationMember
      tags:
        - Organization
      summary: Activate an organization member
      responses:
        '200':
          description: The member was activated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /organizations/deactivate/member:
    put:
      operationId: deactivateOrganizationMember
      tags:
        - Organization
      summary: Deactivate an organization member
      responses:
        '200':
          description: The member was deactivated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /organizations/members/role:
    put:
      operationId: assignOrganizationMemberRole
      tags:
        - Organization
      summary: Assign a role to an organization member
      responses:
        '200':
          description: The role was assigned.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. Use your Kobiton username (or email) as the
        username and your Kobiton API key as the password. Create and manage API
        keys in the Kobiton portal under API Keys settings.
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      schema:
        type: integer
      description: The Kobiton session ID.
    AppId:
      name: appId
      in: path
      required: true
      schema:
        type: integer
      description: The application ID.
    VersionId:
      name: versionId
      in: path
      required: true
      schema:
        type: integer
      description: The application version ID.
    TagName:
      name: name
      in: path
      required: true
      schema:
        type: string
      description: The tag name.
    DataSetId:
      name: dataSetId
      in: path
      required: true
      schema:
        type: integer
      description: The data set ID.
  responses:
    Unauthorized:
      description: Authentication failed or was not provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  schemas:
    DeviceList:
      type: object
      description: >-
        Devices grouped by source. Modeled from the get-devices-info sample;
        reconcile exact property names against the live response.
      properties:
        privateDevices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        favoriteDevices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        cloudDevices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
    Device:
      type: object
      properties:
        id:
          type: integer
        deviceName:
          type: string
        platformName:
          type: string
          enum: [Android, iOS]
        platformVersion:
          type: string
        isOnline:
          type: boolean
        isBooked:
          type: boolean
        udid:
          type: string
    Session:
      type: object
      description: A test-run session. Modeled; reconcile against the live get-session response.
      properties:
        id:
          type: integer
        state:
          type: string
        deviceName:
          type: string
        platformName:
          type: string
        platformVersion:
          type: string
        appName:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    SessionCommandsPage:
      type: object
      description: A paginated page of session commands, as shown in the get-session-data sample.
      properties:
        currentPage:
          type: integer
        totalPages:
          type: integer
        commands:
          type: array
          items:
            type: object
            additionalProperties: true
    RevisitPlanStartRequest:
      type: object
      description: Grounded in the scriptless-automation use-rest-api docs.
      properties:
        exploringSessionIds:
          type: array
          items:
            type: integer
          description: The baseline exploration session IDs to replay.
        deviceBundleId:
          type: integer
          description: The target device bundle to run the scriptless test on.
      required:
        - exploringSessionIds
        - deviceBundleId
    AppUploadUrl:
      type: object
      properties:
        appPath:
          type: string
        url:
          type: string
          format: uri
    CreateAppRequest:
      type: object
      properties:
        filename:
          type: string
        appPath:
          type: string