Esper Manage 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
  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
tags:
- name: Enterprise
  description: The Esper Enterprise APIs to manage the account information set up for your company’s account. Read our Esper Manage documentation or use the Esper Manage Dashboard through the Esper Developer Console
  externalDocs:
    description: Find out more about enterprise settings
    url: https://docs.esper.io/home/console.html#company-settings
- name: Application
  description: APIs for application management
  externalDocs:
    description: Find out more about application management
    url: https://docs.esper.io/home/console.html#apps
- name: Application V1
  description: APIs for application management
- name: Device
  description: APIs for device management
  externalDocs:
    description: Find out more about device management
    url: https://docs.esper.io/home/console.html#devices
- name: Device Group
  description: APIs for device group management
  externalDocs:
    description: Find out more about device group management
    url: https://docs.esper.io/home/console.html#groups
- name: Commands
  description: 'APIs to run device commands.

    `This version of commands is being deprecated and documentation will be archived soon. Please use Commands V2.`

    '
  externalDocs:
    description: Find out more about device commands
    url: https://docs.esper.io/home/console/device-management/-/#device-actions
- name: Group Commands
  description: APIs to run group commands. Command will be run on all the active devices in a group
  externalDocs:
    description: Find out more in `Actions` of group commands
    url: https://docs.esper.io/home/console.html#groups
- name: Token
  description: Fetch API token information
  externalDocs:
    description: Find out more about API get generation
    url: https://docs.esper.io/home/module/genapikey.html
- 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/
- name: Enterprise Policy
  description: APIs to Esper Compliance Policy
  externalDocs:
    description: Find out more about Compliance Policy
    url: https://docs.esper.io/
- name: Geofence
  description: APIs for geofence management
  externalDocs:
    description: Find out more about Geofence
    url: https://docs.esper.io/home/console.html#geofence
- name: Subscription
  description: APIs for Subscription management
  externalDocs:
    description: Find out more about Report
    url: https://docs.esper.io/home/console.html#subscription
- name: Content
  description: APIs for Content management
  externalDocs:
    description: Find out more about Content management
    url: https://docs.esper.io/home/console.html#content
schemes:
- https
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
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
paths:
  /enterprise/{enterprise_id}/application/:
    get:
      operationId: getAllApplications
      summary: List apps in enterprise
      description: Returns Application list
      produces:
      - application/json
      parameters:
      - name: application_name
        in: query
        description: filter by application name
        required: false
        type: string
      - name: package_name
        in: query
        description: filter by package name
        required: false
        type: string
      - name: package_name_exact
        in: query
        description: filter by package name (exact match)
        required: false
        type: string
      - name: has_uploaded_version
        in: query
        description: Returns applications having atleast on version uploaded
        required: false
        type: boolean
      - name: category
        in: query
        description: filter by category
        required: false
        type: string
      - name: supported_sdk
        in: query
        description: filter by supported sdk versions
        required: false
        type: integer
      - name: is_active
        in: query
        description: filter by active applications
        required: false
        type: boolean
      - name: is_hidden
        in: query
        description: filter default esper apps
        required: false
        type: boolean
        default: false
      - name: created_on_gt
        in: query
        description: filter applications created after a given timestamp
        required: false
        type: string
        format: datetime
      - name: created_on_lt
        in: query
        description: filter applications created before a given timestamp
        required: false
        type: string
        format: datetime
      - name: updated_on_gt
        in: query
        description: filter applications updated after a given timestamp
        required: false
        type: string
        format: datetime
      - name: updated_on_lt
        in: query
        description: filter applications updated before a given timestamp
        required: false
        type: string
        format: datetime
      - 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/Application'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    parameters:
    - name: enterprise_id
      description: A UUID string identifying this enterprise.
      in: path
      required: true
      type: string
  /enterprise/{enterprise_id}/application/upload/:
    post:
      operationId: upload
      summary: Upload an application to enterprise
      description: Returns application
      produces:
      - application/json
      consumes:
      - multipart/form-data
      - application/x-www-form-urlencoded
      parameters:
      - name: app_file
        description: Valid APK file
        in: formData
        required: true
        type: file
      responses:
        '201':
          description: successful operation
          schema:
            type: object
            properties:
              application:
                $ref: '#/definitions/Application'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden, no permission to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '415':
          description: Unsupported media type.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    parameters:
    - name: enterprise_id
      description: A UUID string identifying this enterprise.
      in: path
      required: true
      type: string
  /enterprise/{enterprise_id}/application/{application_id}/:
    get:
      operationId: getApplication
      summary: Get application information
      description: Returns Application instance
      produces:
      - application/json
      parameters: []
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Application'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    delete:
      operationId: deleteApplication
      summary: Delete an application
      description: Empty response
      produces:
      - application/json
      parameters: []
      responses:
        '204':
          description: The resource was deleted successfully.
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden, no permission to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    parameters:
    - name: application_id
      in: path
      description: A UUID string identifying this application.
      required: true
      type: string
      format: uuid
    - name: enterprise_id
      description: A UUID string identifying enterprise.
      in: path
      required: true
      type: string
  /enterprise/{enterprise_id}/application/{application_id}/version/:
    get:
      operationId: getAppVersions
      summary: List App versions
      description: Returns AppVersion list
      produces:
      - application/json
      parameters:
      - name: version_code
        in: query
        description: filter by version code
        required: false
        type: string
      - name: build_number
        in: query
        description: filter by build number
        required: false
        type: string
      - name: is_g_play
        in: query
        description: filter google play applications
        required: false
        type: boolean
      - name: approval_status
        in: query
        description: filter by approval status
        required: false
        type: string
        enum:
        - AVAILABLE
        - ACCEPTED
        - APPROVED
        - REJECTED
      - name: is_enabled
        in: query
        description: filter by enabled versions
        required: false
        type: boolean
      - name: is_default
        in: query
        description: filter by default versions
        required: false
        type: boolean
      - name: created_on_gt
        in: query
        description: filter applications created after a given timestamp
        required: false
        type: string
        format: datetime
      - name: created_on_lt
        in: query
        description: filter applications created before a given timestamp
        required: false
        type: string
        format: datetime
      - name: updated_on_gt
        in: query
        description: filter applications updated after a given timestamp
        required: false
        type: string
        format: datetime
      - name: updated_on_lt
        in: query
        description: filter applications updated before a given timestamp
        required: false
        type: string
        format: datetime
      - 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
      - name: ordering
        in: query
        description: 'Order result set by field name.


          ```

          * installed_count: order by asc

          * -installed_count: order by desc

          ```

          '
        required: false
        type: string
      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/AppVersion'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    parameters:
    - name: application_id
      in: path
      description: A UUID string identifying this application.
      required: true
      type: string
      format: uuid
    - name: enterprise_id
      description: A UUID string identifying enterprise.
      in: path
      required: true
      type: string
  /enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/:
    get:
      operationId: getAppVersion
      summary: Get app version information
      description: Returns AppVersion instance
      produces:
      - application/json
      parameters:
      - name: request_id
        in: query
        description: If this value exists in cache, delete the application and cache entry.
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AppVersion'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    delete:
      operationId: deleteAppVersion
      summary: Delete app version
      description: Empty response
      produces:
      - application/json
      parameters: []
      responses:
        '200':
          description: No request id is provided and the application is linked to one or more templates. Returns a request_id. Call with this request id to delete the resource.
          schema:
            $ref: '#/definitions/AppVersionDelete'
        '204':
          description: The resource was deleted successfully.
        '400':
          description: Invalid request.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden, no permission to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    patch:
      operationId: patchAppVersion
      summary: Patch an App version instance
      produces:
      - application/json
      parameters:
      - name: data
        in: body
        schema:
          type: object
          properties:
            release_name:
              title: Release name
              description: Name of the Release
              type: string
            release_comments:
              title: Release comments
              description: Additional comments about the release
              type: string
            release_track:
              title: Release track
              description: Description of the content
              type: string
              enum:
              - Alpha
              - Beta
              - Production
            is_enabled:
              title: Is Enabled
              description: Is the app version enabled
              type: boolean
            min_sdk_version:
              title: Minimum SDK version
              description: Version number of minimum SDK version that supports this app version
              type: string
            target_sdk_version:
              title: Target SDK version
              description: Target SDK version that supports this app version
              type: string
            build_number:
              title: Build Number
              description: Build number of this app version
              type: string
            version_code:
              title: Version Code
              description: Verion code of this app version
              type: string
            approval_status:
              title: Approval Status
              description: Approval status of this app version
              type: string
              enum:
              - AVAILABLE
              - ACCEPTED
              - APPROVED
              - REJECTED
            is_default:
              title: Is default
              description: Is the app version default
              type: boolean
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AppVersion'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden, no permission to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    parameters:
    - name: version_id
      in: path
      description: A UUID string identifying this app version.
      required: true
      type: string
      format: uuid
    - name: application_id
      in: path
      description: A UUID string identifying this application.
      required: true
      type: string
      format: uuid
    - name: enterprise_id
      description: A UUID string identifying enterprise.
      in: path
      required: true
      type: string
  /enterprise/{enterprise_id}/application/{application_id}/version/{version_id}/installdevices:
    get:
      operationId: getInstallDevices
      summary: List install devices
      description: Returns list of devices with the specified app version installed
      produces:
      - application/json
      parameters:
      - name: search
        in: query
        description: A search term, search based on device name, device alias_name, group name
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return per page
        required: false
        type: integer
      - 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/InstallDevices'
        '401':
          description: Authorization information is missing or invalid.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden, no permission to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found.
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - apiKey: []
      tags:
      - Application
    parameters:
    - name: version_id
      in: path
      description: A UUID string identifying this app version.
      required: true
      type: string
      format: uuid
    - name: application_id
      in: path
      description: A UUID string identifying this application.
      required: true
      type: string
      format: uuid
    - name: enterprise_id
      description: A UUID string identifying enterprise.
      in: path
      required: true
      type: string
  /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/:
    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
    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
  /enterprise/{enterprise_id}/device/{device_id}/app/{app_id}/:
    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
    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
  /enterprise/{enterprise_id}/device/{device_id}/command/:
    post:
      summary: Run commands on device
      description: Fire commands on device like reboot, ping etc. Deprecated in favour of commands V2.
      operationId: runCommand
      deprecated: true
      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
      - name: command
        in: body
        description: Command request body
        required: true
        schema:
          $ref: '#/definitions/CommandRequest'
      responses:
        200:
          description: successful operation
          schema:
            $ref: '#/definitions/DeviceCommand'
      security:
      - apiKey: []
      tags:
      - Commands
  /enterprise/{enterprise_id}/device/{device_id}/command/{command_id}/:
    get:
      operationI

# --- truncated at 32 KB (149 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/esper/refs/heads/main/openapi/esper-manage-openapi-original.yml