Esper Commands V2 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 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
servers:
- url: https://foo-api.esper.cloud/api
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
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        schema:
          type: string
          format: uuid
      responses:
        201:
          description: command request successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V0CommandRequest'
      security:
      - apiKey: []
      tags:
      - Commands V2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V0CommandRequest'
        description: The request body to create a command for set of devices or groups
        required: true
    get:
      operationId: listCommandRequest
      summary: List command requests
      description: API to get and filter command requests
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        schema:
          type: string
          format: uuid
      - name: command_type
        in: query
        description: Filter by type of command request i.e device, group etc
        required: false
        schema:
          type: string
      - name: devices
        in: query
        description: Filter by device IDs. Accepts comma separated values.
        required: false
        schema:
          type: string
      - name: device_type
        in: query
        description: Filter by device type i.e active, inactive etc
        required: false
        schema:
          type: string
      - name: command
        in: query
        description: Filter by command name
        required: false
        schema:
          type: string
      - name: issued_by
        in: query
        description: Filter by user. Accepts user id.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: on successful request
          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/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
      parameters:
      - name: enterprise_id
        in: path
        description: ID of the enterprise
        required: true
        schema:
          type: string
          format: uuid
      - name: request_id
        in: path
        description: ID for the command request
        required: true
        schema:
          type: string
          format: uuid
      - name: device
        in: query
        description: Filter status result by device id.
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: Filter by command state
        required: false
        schema:
          type: string
      responses:
        '200':
          description: on successful request
          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/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
      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 for the command request
        required: true
        schema:
          type: string
          format: uuid
      - name: state
        in: query
        description: Filter by command state
        required: false
        schema:
          type: string
      responses:
        '200':
          description: on successful request
          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/V0CommandStatus'
      security:
      - apiKey: []
      tags:
      - Commands V2
components:
  schemas:
    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
    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
    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: '#/components/schemas/V0CommandScheduleArgsTimeTypeEnum'
        window_start_time:
          type: string
        window_end_time:
          type: string
        days:
          type: array
          items:
            type: string
    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
    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: '#/components/schemas/V0DeviceCommandEnum'
        command_args:
          $ref: '#/components/schemas/V0CommandArgs'
        schedule:
          $ref: '#/components/schemas/V0CommandScheduleEnum'
        schedule_args:
          $ref: '#/components/schemas/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: '#/components/schemas/V0CommandRequestStatus'
          readOnly: true
    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
    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
  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