Opkey Device Booking & Session API

openapi: 3.2.0
info:
  title: pCloudy Device Cloud Device Booking & Session API
  version: v2
  summary: Public REST API for the pCloudy real-device cloud, an Opkey product.
  description: The pCloudy REST API is the machine-readable surface of the pCloudy real-device testing cloud operated by Opkey (Smart Software Testing Solutions Inc.).
  contact:
    name: Opkey
    url: https://www.opkey.com/
  x-generated-by: API Evangelist enrichment pipeline
  x-source: https://content.pcloudy.com/apidocs/
servers:
- url: https://{cloud}.pcloudy.com
  description: pCloudy cloud instance
  variables:
    cloud:
      default: device
      enum:
      - device
      - demo
      - aus
      description: pCloudy cloud host prefix; the docs refer to this as <Cloud URL>.
security:
- accessToken: []
tags:
- name: Device Booking & Session
paths:
  /api/v2/clean-device:
    post:
      operationId: cleanDevice
      summary: Clean_Devices(V2)
      tags:
      - Device Booking & Session
      description: Cleans the reserved device by clearing residual app data and returning it toward a fresh state between tests. Used to remove leftover data, accounts, and test artifacts so each run starts from a known baseline.
      parameters:
      - name: token
        in: header
        required: true
        description: API access token (from /api/access).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - rid
              properties:
                rid:
                  type: integer
                  description: Device reservation ID (returned when the device is booked).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example:
                traceId: fhcDtmOQbLXxZEITWgVFR
                requestId: LNqenAilCL4xGihXlwtxb
                statusCode: 200
                status: success
                message: OK
        '401':
          description: Unauthorized - missing or invalid access token
      security:
      - accessToken: []
  /api/v2/release-device:
    post:
      operationId: releaseDevice
      summary: Release Device(V2)
      tags:
      - Device Booking & Session
      description: Releases the device reserved through the V2 flow, ending the session and returning the device to the shared pool. Always call it during teardown to free the device and stop session usage.
      parameters:
      - name: token
        in: header
        required: true
        description: API access token (from /api/access).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - rid
              properties:
                rid:
                  type: integer
                  description: Device reservation ID (returned when the device is booked).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example:
                traceId: nCBspvKfayCxhN8ZGugC
                requestId: plUq82anV9TLBlalAsSgr
                statusCode: 200
                status: success
                message: OK
        '401':
          description: Unauthorized - missing or invalid access token
      security:
      - accessToken: []
  /api/startdeviceservices:
    post:
      operationId: startDeviceServices
      summary: Start Device Services
      tags:
      - Device Booking & Session
      description: Starts the backend device services required for the booked session (for example streaming, logging, and automation bridges) so the device is ready for interaction. Call it after booking a device and before sending automation or interaction commands.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - None
              properties:
                None:
                  type: string
                  description: Authentication is via the Authorization header (Basic username:apiKey).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example:
                requestId: 1aa5413b-3a67-402d-84c-09bedf5491fe
                statusCode: 200
                status: success
                message: OK
                data:
                  message: Automation initiated successfully...
        '401':
          description: Unauthorized - missing or invalid access token
      security:
      - accessToken: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic with your pCloudy email as the username and your API access key as the password. Used only by GET /api/access to mint an access token.
    accessToken:
      type: apiKey
      in: header
      name: token
      description: Access token returned by GET /api/access. Newer /api/v2/* operations send it as a `token` header; several legacy /api/* operations send the same token as a `token` field in the JSON request body.
externalDocs:
  description: pCloudy API Reference
  url: https://content.pcloudy.com/apidocs/