Esper Device API

openapi: 3.2.0
info:
  description: '# Introduction

    Esper APIs are a set of REST-based APIs that help you programmatically control and monitor Android-based Dedicated Devices running the Esper agent using Esper Manage.'
  version: 1.0.0
  title: ESPER API REFERENCE Device API
  termsOfService: https://esper.io/terms-of-service
  contact:
    email: developer@esper.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://foo-api.esper.cloud/api
tags:
- name: Device
  description: APIs for device management
  externalDocs:
    description: Find out more about device management
    url: https://docs.esper.io/home/console.html#devices
paths:
  /enterprise/{enterprise_id}/device/:
    get:
      summary: Fetch all devices in an enterprise
      description: Returns a list of devices
      operationId: getAllDevices
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        schema:
          type: string
          format: uuid
      - name: name
        in: query
        description: Filter by device name
        required: false
        schema:
          type: string
      - name: group
        in: query
        description: Filter by group id
        required: false
        schema:
          type: string
          format: uuid
      - name: imei
        in: query
        description: filter by imei
        required: false
        schema:
          type: string
      - name: serial
        in: query
        description: filter by serial number
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: filter by device state
        required: false
        schema:
          type: integer
      - name: brand
        in: query
        description: filter by brand
        required: false
        schema:
          type: string
      - name: is_gms
        in: query
        description: filter for gms devices
        required: false
        schema:
          type: boolean
      - name: search
        in: query
        description: A search term. Search by device name, imei or mac address
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: A partial text search for device tags
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int64
                  next:
                    type: string
                    format: url
                  previous:
                    type: string
                    format: url
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
      security:
      - apiKey: []
      tags:
      - Device
  /enterprise/{enterprise_id}/device/{device_id}/:
    get:
      summary: Fetch device details by ID
      description: Returns details of a device
      operationId: getDeviceById
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        schema:
          type: string
          format: uuid
      - name: device_id
        in: path
        description: ID of the device
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '400':
          description: Bad request
      security:
      - apiKey: []
      tags:
      - Device
  /enterprise/{enterprise_id}/device/{device_id}/app/:
    parameters:
    - name: enterprise_id
      description: A UUID string identifying this enterprise.
      in: path
      required: true
      schema:
        type: string
    - name: device_id
      description: A UUID string identifying device.
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getDeviceApps
      summary: List all device apps
      description: Returns DeviceApp list
      parameters:
      - name: package_name
        in: query
        description: Filter by Package name
        required: false
        schema:
          type: string
      - name: whitelisted
        in: query
        description: Whitelist filter
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: A search term. Search by app_name.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: url
                  previous:
                    type:
                    - string
                    - 'null'
                    format: url
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceApp'
      security:
      - apiKey: []
      tags:
      - Device
  /enterprise/{enterprise_id}/device/{device_id}/app/{app_id}/:
    parameters:
    - name: app_id
      in: path
      description: A UUID string identifying this device app.
      required: true
      schema:
        type: string
        format: uuid
    - name: enterprise_id
      description: A UUID string identifying this device.
      in: path
      required: true
      schema:
        type: string
    - name: device_id
      description: A UUID string identifying this enteprise.
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getDeviceAppById
      summary: Get device app details
      description: Returns DeviceApp instance
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceApp'
      security:
      - apiKey: []
      tags:
      - Device
  /enterprise/{enterprise_id}/device/{device_id}/install/:
    parameters:
    - name: enterprise_id
      description: A UUID string identifying this enterprise.
      in: path
      required: true
      schema:
        type: string
    - name: device_id
      description: A UUID string identifying device.
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getAppInstalls
      summary: List installed apps
      description: Returns AppInstall list
      parameters:
      - name: device
        in: query
        description: filter by device id
        required: false
        schema:
          type: string
      - name: package_name
        in: query
        description: filter by package name
        required: false
        schema:
          type: string
      - name: application_name
        in: query
        description: filter by application name
        required: false
        schema:
          type: string
      - name: install_state
        in: query
        description: filter by install state
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: url
                  previous:
                    type:
                    - string
                    - 'null'
                    format: url
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppInstall'
      security:
      - apiKey: []
      tags:
      - Device
  /enterprise/{enterprise_id}/device/{device_id}/status/:
    parameters:
    - name: enterprise_id
      description: A UUID string identifying this enterprise.
      in: path
      required: true
      schema:
        type: string
    - name: device_id
      description: A UUID string identifying device.
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getDeviceEvent
      summary: Get latest device event
      description: Returns DeviceStatus instance
      parameters:
      - name: latest_event
        in: query
        description: Flag to get latest event
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: url
                  previous:
                    type:
                    - string
                    - 'null'
                    format: url
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceStatus'
      security:
      - apiKey: []
      tags:
      - Device
components:
  schemas:
    Device:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: url
        device_name:
          type: string
        alias_name:
          type: string
          description: Device friendly name
        policy_name:
          type: string
        status:
          type: integer
          format: int32
          description: Current status of device
        state:
          type: integer
          format: int32
          description: Current state of device
        current_command:
          type: string
          format: uuid
          description: Current command associated with device
        suid:
          type: string
          description: Device generated unique id
        fcm_id:
          type: string
        enterprise:
          type: string
          format: url
        policy:
          type: string
          format: url
        user:
          type: string
          format: url
        groups:
          type: array
          items:
            type: string
            format: url
        tags:
          type: array
          items:
            type: string
        api_level:
          type: integer
          format: int32
        template_name:
          type: string
        mqtt_id:
          type: string
        softwareInfo:
          type: object
        hardwareInfo:
          type: object
        displays:
          type: object
        networkInfo:
          type: object
        memoryInfo:
          type: object
        audioConstraints:
          type: object
        provisioned_on:
          type: string
          format: date-time
        created_on:
          type: string
          format: date-time
        updated_on:
          type: string
          format: date-time
        emm_device:
          $ref: '#/components/schemas/EmmDevice'
        is_gms:
          type: boolean
          default: true
        is_active:
          type: boolean
          default: true
    AppInstallVersion:
      title: Version
      type: object
      properties:
        app_version_id:
          title: App version id
          type: string
          format: uuid
        version_code:
          title: Version code
          type: string
        build_number:
          title: Build number
          type: string
        hash_string:
          title: Hash string
          type: string
    AppInstallApplication:
      title: Application
      type: object
      properties:
        application_name:
          title: Application name
          type: string
        package_name:
          title: Package name
          type: string
        version:
          $ref: '#/components/schemas/AppInstallVersion'
        is_enabled:
          title: Is enabled
          type: boolean
    DeviceApp:
      required:
      - app_name
      - package_name
      - device
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/DeviceAppPermission'
        app_name:
          title: App name
          type: string
          minLength: 1
        package_name:
          title: Package name
          type: string
          maxLength: 255
          minLength: 1
        whitelisted:
          title: Whitelisted
          type: boolean
        is_data_clearable:
          title: Data clearable
          type: boolean
        is_uninstallable:
          title: Uninstallable
          type: boolean
        product_id:
          title: Product id
          type:
          - string
          - 'null'
          maxLength: 255
          minLength: 1
        version_code:
          title: Version code
          type:
          - string
          - 'null'
          maxLength: 128
          minLength: 1
        version_name:
          title: Version name
          type:
          - string
          - 'null'
          maxLength: 128
          minLength: 1
        created_on:
          title: Created on
          type: string
          format: date-time
          readOnly: true
        updated_on:
          title: Updated on
          type: string
          format: date-time
          readOnly: true
        is_active:
          title: Is active
          type: boolean
        device:
          title: Device
          type: string
          format: uuid
    AppInstall:
      required:
      - application
      - install_state
      - enterprise
      - device
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        application:
          $ref: '#/components/schemas/AppInstallApplication'
        install_state:
          $ref: '#/components/schemas/AppInstallStateEnum'
        reason_details:
          title: Reason details
          type:
          - string
          - 'null'
          minLength: 1
        created_on:
          title: Created on
          type: string
          format: date-time
          readOnly: true
        updated_on:
          title: Updated on
          type: string
          format: date-time
          readOnly: true
        is_active:
          title: Is active
          type: boolean
        enterprise:
          title: Enterprise
          type: string
          format: url
        device:
          title: Device
          type: string
          format: url
    DeviceStatus:
      required:
      - data
      - device
      - enterprise
      type: object
      properties:
        id:
          title: ID
          type: integer
          readOnly: true
        data:
          title: Data
          type: string
        created_on:
          title: Created on
          type: string
          format: date-time
          readOnly: true
        device:
          title: Device
          type: string
          format: url
        enterprise:
          title: Enterprise
          type: string
          format: url
    AppInstallStateEnum:
      title: Install state
      type: string
      description: 'Device App Install State


        ``` * NOT_INSTALLED = "Not Installed"

        * INSTALL_IN_PROGRESS = "Installation In-Progress"

        * UNINSTALL_IN_PROGRESS = "Uninstallation In-Progress"

        * INSTALL_SUCCESS = "Install Success"

        * INSTALL_FAILED = "Install Failed"

        * UNINSTALL_SUCCESS = "Uninstall Success"

        * UNINSTALL_FAILED = "Uninstall Failed"

        ```

        '
      enum:
      - NOT_INSTALLED
      - INSTALL_IN_PROGRESS
      - UNINSTALL_IN_PROGRESS
      - INSTALL_SUCCESS
      - INSTALL_FAILED
      - UNINSTALL_SUCCESS
      - UNINSTALL_FAILED
    DeviceAppPermission:
      required:
      - permission
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        permission:
          title: Permission
          type: string
          maxLength: 255
          minLength: 1
        grant_state:
          title: Grant state
          type: string
          description: '* PERMISSION_GRANT_STATE_DEFAULT = 0

            * PERMISSION_GRANT_STATE_DENIED = 1

            * PERMISSION_GRANT_STATE_GRANTED = 2


            For state details check [Android docs](https://developer.android.com/reference/android/app/admin/DevicePolicyManager#PERMISSION_GRANT_STATE_DEFAULT)

            '
          enum:
          - PERMISSION_GRANT_STATE_DEFAULT
          - PERMISSION_GRANT_STATE_DENIED
          - PERMISSION_GRANT_STATE_GRANTED
        created_on:
          title: Created on
          type: string
          format: date-time
          readOnly: true
        updated_on:
          title: Updated on
          type: string
          format: date-time
          readOnly: true
        is_active:
          title: Is active
          type: boolean
        app:
          title: App
          type: string
          format: uuid
    EmmDevice:
      type: object
      properties:
        id:
          type: integer
          format: int64
        google_device_id:
          type: string
        managementType:
          type: string
        device:
          type: string
          format: uuid
        google_user:
          type: integer
          format: int64
        policy:
          type: integer
          format: int64
        created_on:
          type: string
          format: date-time
        updated_on:
          type: string
          format: date-time
        is_active:
          type: boolean
          default: true
  securitySchemes:
    apiKey:
      description: "#### API KEY - Access Token\nAccess token for APIs passed as authorization header in calls. You need to generate this from your Esper Dev Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper Dev account. Please follow the instructions [here](https://docs.esper.io/home/module/genapikey.html) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication scheme [here](https://console-docs.esper.io/API/generate.html).\n"
      name: Authorization
      type: apiKey
      in: header
x-tagGroups:
- name: API Reference
  tags:
  - Enterprise
  - Application
  - Application V1
  - Device
  - Device Group
  - Commands
  - Group Commands
  - Token
  - Commands V2
  - Enterprise Policy
  - Geofence
  - Reports
  - Subscription
  - Content