Esper Device API

openapi: 3.2.0
info:
  description: "# Introduction\nEsper 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. With these APIs, you can orchestrate and manage devices that have been provisioned against your Esper Manage environment. Furthermore, these APIs allows you to manage the Android applications installed on your Dedicated Device fleet. To read more about the various capabilities of Esper APIs and Esper managed devices, please visit [esper.io](https://esper.io). This guide describes all the available APIs in detail, along with code samples for you to quickly ramp up to using them.\\\nTo use these APIs you will need to create a developer account with Esper and get access to the Esper Dev Console and the Esper ManageDashboard. You can find out more about Esper and sign up for free at [esper.io/signup](https://esper.io/signup)\\\nWe've done our best to keep this document up to date, but if you find any issues, please reach out to us at developer@esper.io.\n\n# SDK\n\n  You are welcome to use your favorite HTTP/REST library for your programming language in order to call these APIs, or you can use our SDK (currently supporting [python](https://github.com/esper-io/esper-client-py)) to do so.\n\n\n# Authentication\nThe client needs to send authentication details to access the Esper APIs by generating and applying an API key. Be sure to sign up for your free trial account with Esper Dev to generate your key:\n\n# Errors\nThe APIs use standard HTTP status codes to indicate success or failure. All error responses will have a JSON body in the following format:\n\n```\n{\n  \"errors\": [],\n  \"message\": \"error message\",\n  \"status\": 400\n}\n```\n* `errors` -  List of error details\n* `message` - Error description\n* `status` - HTTP status code\n"
  version: 1.0.0
  title: ESPER API REFERENCE Application 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:
    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
    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
    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
    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
    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
    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
    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
    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
    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
  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