Esper Device API

swagger: '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
host: foo-api.esper.cloud
basePath: /api
schemes:
- https
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
      produces:
      - application/json
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        type: string
        format: uuid
      - name: name
        in: query
        description: Filter by device name
        required: false
        type: string
      - name: group
        in: query
        description: Filter by group id
        required: false
        type: string
        format: uuid
      - name: imei
        in: query
        description: filter by imei
        required: false
        type: string
      - name: serial
        in: query
        description: filter by serial number
        required: false
        type: string
      - name: state
        in: query
        description: filter by device state
        required: false
        type: integer
      - name: brand
        in: query
        description: filter by brand
        required: false
        type: string
      - name: is_gms
        in: query
        description: filter for gms devices
        required: false
        type: boolean
      - name: search
        in: query
        description: A search term. Search by device name, imei or mac address
        required: false
        type: string
      - name: tags
        in: query
        description: A partial text search for device tags
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
        default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        type: integer
        default: 0
      responses:
        '200':
          description: successful operation
          schema:
            type: object
            properties:
              count:
                type: integer
                format: int64
              next:
                type: string
                format: url
              previous:
                type: string
                format: url
              results:
                type: array
                items:
                  $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        type: string
        format: uuid
      - name: device_id
        in: path
        description: ID of the device
        required: true
        type: string
        format: uuid
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/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
      type: string
    - name: device_id
      description: A UUID string identifying device.
      in: path
      required: true
      type: string
    get:
      operationId: getDeviceApps
      summary: List all device apps
      description: Returns DeviceApp list
      produces:
      - application/json
      parameters:
      - name: package_name
        in: query
        description: Filter by Package name
        required: false
        type: string
      - name: whitelisted
        in: query
        description: Whitelist filter
        required: false
        type: string
      - name: search
        in: query
        description: A search term. Search by app_name.
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
        default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        type: integer
      responses:
        '200':
          description: successful operation
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: url
                x-nullable: true
              previous:
                type: string
                format: url
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/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
      type: string
      format: uuid
    - name: enterprise_id
      description: A UUID string identifying this device.
      in: path
      required: true
      type: string
    - name: device_id
      description: A UUID string identifying this enteprise.
      in: path
      required: true
      type: string
    get:
      operationId: getDeviceAppById
      summary: Get device app details
      description: Returns DeviceApp instance
      produces:
      - application/json
      parameters: []
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/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
      type: string
    - name: device_id
      description: A UUID string identifying device.
      in: path
      required: true
      type: string
    get:
      operationId: getAppInstalls
      summary: List installed apps
      description: Returns AppInstall list
      produces:
      - application/json
      parameters:
      - name: device
        in: query
        description: filter by device id
        required: false
        type: string
      - name: package_name
        in: query
        description: filter by package name
        required: false
        type: string
      - name: application_name
        in: query
        description: filter by application name
        required: false
        type: string
      - name: install_state
        in: query
        description: filter by install state
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
        default: 20
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        type: integer
        default: 0
      responses:
        '200':
          description: successful operation
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: url
                x-nullable: true
              previous:
                type: string
                format: url
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/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
      type: string
    - name: device_id
      description: A UUID string identifying device.
      in: path
      required: true
      type: string
    get:
      operationId: getDeviceEvent
      summary: Get latest device event
      description: Returns DeviceStatus instance
      produces:
      - application/json
      parameters:
      - name: latest_event
        in: query
        description: Flag to get latest event
        required: true
        type: integer
      responses:
        '200':
          description: successful operation
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: url
                x-nullable: true
              previous:
                type: string
                format: url
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/DeviceStatus'
      security:
      - apiKey: []
      tags:
      - Device
definitions:
  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
  DeviceApp:
    required:
    - app_name
    - package_name
    - device
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      permissions:
        type: array
        items:
          $ref: '#/definitions/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
        maxLength: 255
        minLength: 1
        x-nullable: true
      version_code:
        title: Version code
        type: string
        maxLength: 128
        minLength: 1
        x-nullable: true
      version_name:
        title: Version name
        type: string
        maxLength: 128
        minLength: 1
        x-nullable: true
      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
  AppInstallApplication:
    title: Application
    type: object
    properties:
      application_name:
        title: Application name
        type: string
      package_name:
        title: Package name
        type: string
      version:
        $ref: '#/definitions/AppInstallVersion'
      is_enabled:
        title: Is enabled
        type: boolean
  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: '#/definitions/EmmDevice'
      is_gms:
        type: boolean
        default: true
      is_active:
        type: boolean
        default: true
  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
  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
  AppInstall:
    required:
    - application
    - install_state
    - enterprise
    - device
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      application:
        $ref: '#/definitions/AppInstallApplication'
      install_state:
        $ref: '#/definitions/AppInstallStateEnum'
      reason_details:
        title: Reason details
        type: string
        minLength: 1
        x-nullable: true
      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
  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
securityDefinitions:
  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