Esper Commands V2 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 Commands V2 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: Commands V2
  description: Commands V2.0 is to provide advanced device commands capabilities like queuing, support for offline devices, dynamic device set for commands and command history. Commands 2.0 is in active development and support for all the commands will be added soon.
  externalDocs:
    description: Find out more about commands V2.0
    url: https://docs.esper.io/
paths:
  /v0/enterprise/{enterprise_id}/command/:
    post:
      summary: Create a command request
      description: API to create a command request for the device.
      operationId: createCommand
      produces:
      - application/json
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        type: string
        format: uuid
      - name: request
        in: body
        description: The request body to create a command for set of devices or groups
        required: true
        schema:
          $ref: '#/definitions/V0CommandRequest'
      responses:
        201:
          description: command request successfully created
          schema:
            $ref: '#/definitions/V0CommandRequest'
      security:
      - apiKey: []
      tags:
      - Commands V2
    get:
      operationId: listCommandRequest
      summary: List command requests
      description: API to get and filter command requests
      produces:
      - application/json
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        type: string
        format: uuid
      - name: command_type
        in: query
        description: Filter by type of command request i.e device, group etc
        required: false
        type: string
      - name: devices
        in: query
        description: Filter by device IDs. Accepts comma separated values.
        required: false
        type: string
      - name: device_type
        in: query
        description: Filter by device type i.e active, inactive etc
        required: false
        type: string
      - name: command
        in: query
        description: Filter by command name
        required: false
        type: string
      - name: issued_by
        in: query
        description: Filter by user. Accepts user id.
        required: false
        type: string
      responses:
        '200':
          description: on successful request
          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/V0CommandRequest'
      security:
      - apiKey: []
      tags:
      - Commands V2
  /v0/enterprise/{enterprise_id}/command/{request_id}/status/:
    get:
      operationId: getCommandRequestStatus
      summary: get status list for command request
      description: API to get and filter command request status
      produces:
      - application/json
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        type: string
        format: uuid
      - name: request_id
        in: path
        description: ID for the command request
        required: true
        type: string
        format: uuid
      - name: device
        in: query
        description: Filter status result by device id.
        required: false
        type: string
      - name: state
        in: query
        description: Filter by command state
        required: false
        type: string
      responses:
        '200':
          description: on successful request
          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/V0CommandStatus'
      security:
      - apiKey: []
      tags:
      - Commands V2
  /v0/enterprise/{enterprise_id}/device/{device_id}/command-history/:
    get:
      operationId: getDeviceCommandHistory
      summary: get command history for device
      description: API to get and filter deivce command history
      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 for the command request
        required: true
        type: string
        format: uuid
      - name: state
        in: query
        description: Filter by command state
        required: false
        type: string
      responses:
        '200':
          description: on successful request
          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/V0CommandStatus'
      security:
      - apiKey: []
      tags:
      - Commands V2
definitions:
  V0DeviceCommandEnum:
    type: string
    description: "Following commands are supported\n\n```\n* ADD_TO_WHITELIST: Whitelist an installed sytem app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper \n* ADD_WIFI_AP : Add wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points\n* CLEAR_APP_DATA : Clear data for an installed app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper \n* INSTALL: Install an app on a device. Requires `app_version` in command arguments where `app_version` is the version id of app uploaded on Esper\n* LOCK: Lock device screen\n* REBOOT: Reboot a device\n* REMOVE_FROM_WHITELIST : Remove an installed system app from whitelist. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper \n* REMOVE_WIFI_AP : Remove Wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points\n* SET_APP_PERMISSION : Set permission for an installed app. Requires `package_name`, `grant_state`, `permission` in command arguments where `package_name` is the app package uploaded on Esper, `grant_state` should be \"PERMISSION_GRANT_STATE_DEFAULT\", \"PERMISSION_GRANT_STATE_DENIED\", \"PERMISSION_GRANT_STATE_GRANTED\" and `permission` is a valid permission\n* SET_APP_STATE : Set the state of an app - SHOW/HIDE/DISABLE. Requries `app_state` and `package_name` in command arguments where `app_state` is the state of app and `package_name` is the app package uploaded on Esper\n* SET_BLUETOOTH_STATE : Set bluetooth state (ON/OFF) for device. Requires `bluetooth_state` in command arguments where `bluetooth_state` is a boolean.\n* SET_BRIGHTNESS_SCALE : Set brightness for device. Requires `brightness_value` in command arguments where `brightness_value` is an integer (1-100).\n* SET_DEVICE_LOCKDOWN_STATE : Set lockdown state for a device. Requires `state` and `message` in command arguments where `state` is LOCKED/UNLOCKED and `message` is the message to be added with command\n* SET_GPS_STATE :Set the GPS state for a device. Requires `gps_state` in command arguments where `gps_state` should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)\n* SET_KIOSK_APP : Command to set the Kiosk app for a device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper  \n* SET_NEW_POLICY : Apply policy on device. Requires `policy_url` in command arguments where `policy_url` is the URL to the policy \n* SET_ROTATION_STATE : Set screen orientation. Requires `rotate_state` in command arguments where `rotate_state` should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)\n* SET_SCREEN_OFF_TIMEOUT: Set screen off timeout for a device. Requires `screen_off_timeout` in command arguments where `screen_off_timeout` should be either -1 or between 5000 and 1800000\n* SET_STREAM_VOLUME : Set strema volume for a device. Requires `stream` and `volume_level` in command arguments where `stream` should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music) and `volume_level` should be a value from 0 to 100\n* SET_TIMEZONE : Set the timezone for a device. Requires `timezone_string` in command arguments where `timezone_string` is a valid string representing the timezone\n* SET_WIFI_STATE : Set the wifi state (ON/OFF) for a device. Requires `wifi_state` in command arguments where `wifi_state` is a boolean. \n* UNINSTALL: Uninstall an app from device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper\n* UPDATE_DEVICE_CONFIG: Push additional configurations to the Device\n* UPDATE_HEARTBEAT: Ping a device\n* UPDATE_LATEST_DPC : Prompt device to update the DPC app to the latest versions.\n* WIPE : Wipes the device.\n```\n"
    enum:
    - ADD_TO_WHITELIST
    - ADD_WIFI_AP
    - CLEAR_APP_DATA
    - INSTALL
    - LOCK
    - REBOOT
    - REMOVE_FROM_WHITELIST
    - REMOVE_WIFI_AP
    - SET_APP_PERMISSION
    - SET_APP_STATE
    - SET_BLUETOOTH_STATE
    - SET_BRIGHTNESS_SCALE
    - SET_DEVICE_LOCKDOWN_STATE
    - SET_GPS_STATE
    - SET_KIOSK_APP
    - SET_NEW_POLICY
    - SET_ROTATION_STATE
    - SET_SCREEN_OFF_TIMEOUT
    - SET_STREAM_VOLUME
    - SET_TIMEZONE
    - SET_WIFI_STATE
    - UNINSTALL
    - UPDATE_DEVICE_CONFIG
    - UPDATE_HEARTBEAT
    - UPDATE_LATEST_DPC
    - WIPE
  V0CommandScheduleArgsTimeTypeEnum:
    type: string
    description: 'The Time-Type argument, in Schedule args, is to indicate which timezone the Command Framework should utilize when scheduling the command.

      Following Schedule Args for Time-Type are supported:


      ```

      * CONSOLE: Use the local timezone of the user creating the schedule.

      * DEVICE: Use the local timezone of the device, to which the command is issued, wherever it may be.

      ```

      '
    enum:
    - console
    - device
  V0CommandScheduleEnum:
    type: string
    description: 'Following Schedule types are supported


      ```

      * IMMEDIATE: Schedule the command to execcute Immediately

      * WINDOW: Schedule the command to execute within the given window

      * RECURRING: Schedule the command to execute repeatedly, within given parameters

      ```

      '
    enum:
    - IMMEDIATE
    - WINDOW
    - RECURRING
  V0CommandRequest:
    type: object
    properties:
      id:
        title: Id
        description: Unique command request identifier
        type: string
        format: uuid
        readOnly: true
      enterprise:
        title: Enterperise ID
        description: Esper account identifier
        type: string
        format: uuid
        readOnly: true
      command_type:
        type: string
        description: "Identifies the type of command\n\n```\n* DEVICE: command request is meant for devices\n* GROUP: command request is meant for groups\n* DYNAMIC: command request is meant for dynamic set of devices\n  i.e subset of devices from different groups or otherwise.\n```\n"
        enum:
        - DEVICE
        - GROUP
        - DYNAMIC
      devices:
        type: array
        description: list of devices to run commands
        items:
          type: string
          format: uuid
        minItems: 0
        maxItems: 500
      groups:
        type: array
        description: list of groups to run commands
        items:
          type: string
          format: uuid
        minItems: 0
        maxItems: 500
      device_type:
        type: string
        description: "Type of devices to run commands on\n\n```\n* active: Run commands on currently online devices\n* inactive: Run commands on currently offline devices\n* all: Run commands on all the devices.\n  Commands will be queued for offline devices until they come back online.\n```\n"
        default: active
        enum:
        - active
        - inactive
        - all
      command:
        $ref: '#/definitions/V0DeviceCommandEnum'
      command_args:
        $ref: '#/definitions/V0CommandArgs'
      schedule:
        $ref: '#/definitions/V0CommandScheduleEnum'
      schedule_args:
        $ref: '#/definitions/V0CommandScheduleArgs'
      issued_by:
        type: string
        format: url
        description: command is issued by this user
        readOnly: true
      created_on:
        title: Created on
        description: Timestamp of command request
        type: string
        format: date-time
        readOnly: true
      status:
        title: Current Status
        description: Show creent status of commands issued during in this request
        type: array
        items:
          $ref: '#/definitions/V0CommandRequestStatus'
        readOnly: true
  V0CommandArgs:
    title: Command args
    type: object
    properties:
      device_alias_name:
        description: Alternate human-readable name for your Device
        type: string
      custom_settings_config:
        description: Managed configurations for your device (passed as JSON object)
        type: object
      app_version:
        description: The version id of app uploaded on Esper
        type: string
      package_name:
        description: The app package name uploaded on Esper
        type: string
      policy_url:
        description: The URL to the policy
        type: string
      wifi_access_points:
        description: Wifi access points for the device (passed as JSON object)
        type: object
      state:
        description: LOCKED/UNLOCKED
        type: string
      message:
        description: Message to be added with command
        type: string
      app_state:
        description: The state of app - SHOW/HIDE/DISABLE
        type: string
      bluetooth_state:
        description: The state of bluetooth - ON/OFF
        type: boolean
      brightness_value:
        description: The brightness value of a device(1-100)
        type: integer
      gps_state:
        description: The GPS state of a device. Should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)
        type: integer
      rotate_state:
        description: The screen orientation of a device. Should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)
        type: integer
      screen_off_timeout:
        description: The value for screen timeout of a device. Should be either -1 or between 5000 and 1800000
        type: integer
      stream:
        description: The value of the volume stream. Should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music)
        type: integer
      volume_level:
        description: The level of volume. Should be a value from 0 to 100
        type: integer
      timezone_string:
        description: The timezone of a device. Should be a valid timezone string
        type: integer
      wifi_state:
        description: The state of WIFI - ON/OFF
        type: boolean
      wifi_revert_timeout:
        description: The WIFI revert timeout. Should be greater than or equal to 1
        type: integer
  V0CommandRequestStatus:
    type: object
    properties:
      state:
        title: Command State
        description: Current State of command
        type: string
        format: uuid
      total:
        title: Count
        description: No of commands currently in this state
        type: integer
        format: int64
  V0CommandStatus:
    type: object
    properties:
      id:
        title: Id
        description: Unique command identifier
        type: string
        format: uuid
        readOnly: true
      request:
        title: Request Id
        description: Request Id associated with this command
        type: string
        format: uuid
        readOnly: true
      device:
        title: Device
        description: Device associated with this command
        type: string
        format: url
        readOnly: true
      state:
        type: string
        description: Current state of the command
        enum:
        - Command Queued
        - Command Initiated
        - Command Acknowledged
        - Command In Progress
        - Command TimeOut
        - Command Success
        - Command Failure
        - Command Scheduled
        - Command Cancelled
      reason:
        type: string
        description: details briefing the reason for current command state
      created_on:
        title: Created on
        description: Timestamp of command creation
        type: string
        format: date-time
        readOnly: true
      updated_on:
        title: Updated on
        description: Last updated timestamp of command
        type: string
        format: date-time
        readOnly: true
  V0CommandScheduleArgs:
    title: Command Schedule Arguments
    type: object
    properties:
      name:
        type: string
      start_datetime:
        type: string
        format: date-time
      end_datetime:
        type: string
        format: date-time
      time_type:
        $ref: '#/definitions/V0CommandScheduleArgsTimeTypeEnum'
      window_start_time:
        type: string
      window_end_time:
        type: string
      days:
        type: array
        items:
          type: string
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