Skip to content

ESPER API REFERENCE (1.0.0)

Introduction

Welcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more.

Esper API endpoints use REST-based architecture and return JSON responses.

See our documentation for:

Authentication

You need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup.

Some endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console.

Pagination

Responses may be paginated. Use the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page.

ParameterData TypeExplanation
limitintegerLimit the data returned. Default = 20.
offsetintegerOffset to the first item returned. Default = 0.
orderingstringOrder the results set by the field name. Varies by endpoint.
nextstringPaginate to the next response set.
previousstringPaginate to the last set response.

Errors

We use standard HTTP status codes for success or failure. A typical error response may look something like this:

{
  "errors": [],
  "message": "error message",
  "status": 400
}
  • errors - List of error details
  • message - Error description
  • status - HTTP status code

Some common status codes and messages are:

NumberMessageExplanation
200OKThe request succeeded.
201Resource creationA resource was created.
401UnauthorizedThe API key is invalid.
404Not foundThe resource was not found.
429Rate limit exceededToo many requests. Wait a moment and try again.
500Server errorInternal error. Wait a moment and try again. If the issue persists, contact Esper.

See how our systems are doing by checking our status page.

Rate Limits

To ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:

  • Try sending requests in batches.
  • Begin with about 20 requests at a time and building up from there.
  • Ensure your scripts are efficient and don’t contain redundant calls.
  • Reach out to your account manager to discuss your options.
Download OpenAPI description
openapi.json
openapi.yaml
Overview
E-mail
developer@esper.io
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://develop-api.esper.io/_mock/openapi
https://{foo}-api.esper.cloud/api

Company Settings

The Company Settings API manage the account information set up for your organization. Formerly known as Enterprise Information.

Operations

Application

APIs for application management

Operations

Application V1

APIs for application management

Operations

AndroidDevice

APIs for android device management

Operations

Device Group

APIs for device group management

Operations

Token (Deprecated)

⚠️ Deprecation Notice: The following APIs will soon be deprecated. Use the console to manage API keys instead.

Operations

Commands V2

Commands V2.0 provides 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 we will add support for all the commands soon

Operations

Enterprise Policy

APIs to Esper Compliance Policy

Operations

Geofence

APIs for geofence management

Operations

Content

APIs to manage files

Operations

User (Deprecated)

⚠️ Deprecation Notice: The following APIs will soon be deprecated. Please transition to the User APIs.

Operations

User

APIs for User Management

Operations

Blueprint (Deprecated)

This is the API for the former Blueprints service.

⚠️ Deprecation Notice: The following APIs will soon be deprecated. Use Blueprints API instead.

Operations

Directory Record

APIs for Directory Record management. These APIs are only available to the customers using the new Onboarding experience.

Operations

Tile Icon

APIs to manage tile icons. Tile icons allow Templates-based users to apply a icons to devices.

Operations

Alerts

Operations

Alarms

Operations

Wallpapers

Operations

Device Telemetry

Operations

Daily and Custom Reports

Operations

SSO Connections

Operations

Roles

Operations

Personal Access Token

Operations

Blueprints API

APIs to manage blueprints. Learn more about blueprints.

Operations

Custom Actions API

APIs to manage custom actions. Custom actions allow you to define custom scripts and commands that can be executed on Linux devices. Currently, only Linux platform is supported for custom actions.

Operations

System Status Code

System status code descriptions

  • 900 (INTERNAL_REQUEST_SKIPPED) - Response code is used when a request is valid, but cannot be fulfilled.

System

System level APIs

Operations

Pipelines

Pipelines composition APIs

Operations

Stages

APIs to modify Stage information

Operations

Target Lists

APIs to modify Target List

Operations

Targets

Targets subsystem

Operations

Device Groups

APIs to modify Device Groups

Operations

Operation Lists

APIs to modify Operation List

Operations

Operations

Operations subsystem

Operations

Pipeline Runs

APIs to manage Pipeline Runs. Pipeline run status descriptions

  • PENDING - Pipeline run created.
  • QUEUED - Pipeline run queued for processing.
  • PROCESSING - Pipeline run received by scheduler for processing. (Processing a pipeline involves performing the operations required before starting a pipeline)
  • RUNNING - Pipeline run has started running.
  • WAITING - Pipeline run is waiting for an action (manual/automatic).
  • COMPLETE - The pipeline run has completed processing i.e. All stage runs are processed. A complete pipeline run can move to success or failure.
  • SUCCESS - A completed pipeline run moves to success if all stage runs are successful.
  • FAILURE - A completed pipeline run moves to failure if all stage runs are not successful.
  • CANCELLED - Pipeline run is cancelled by the user.
  • TIMEOUT - The pipeline run has a timed out. This happens when the pipeline has not completed processing even after the timeout period (Default 21 days).
  • INVALID - A pipeline run moves to invalid state when Pipeline run has no stageruns i.e pipeline has zero stages.
Operations

Stage Runs

APIs to manage Stage Runs. Stage run status descriptions

  • PENDING - Stage run created.
  • QUEUED - Stage run queued for processing.
  • PROCESSING - Stage run received by scheduler for processing.(Processing a stage run can involve performing the operations required before starting a stage run. In this case creating the target runs for the stage.)
  • RUNNING - Stage run has started running.
  • COMPLETE - Stage run moves to complete if all target runs are complete (target runs are complete if they are in a terminal state).
  • SUCCESS - A completed stage run moves to success if all target runs are successful.
  • FAILURE - A completed stage moves to failure if all target runs are not successful.
  • CANCELLED - Stage run cancelled by user.
  • TIMEOUT - The stage run has a timed out. This happens when the stage run has not completed processing even after the timeout period (Default 7 days).
  • INVALID - A stage run moves to invalid state when a. The associated stage has no targets. b. The associated stage has no operations.
Operations

Target Runs

APIs to manage Target Runs. Target run status descriptions

  • PENDING - Target run created.
  • QUEUED - Target run queued for processing.
  • PROCESSING - Target run received by scheduler for processing (During target run processing the command request for the target run is created).
  • DISPATCHED - Target run moves to dispatched when a command is successfully queued for the target run. (Command status - QUEUED)
  • RUNNING - Target run moves to running state when the command has been sent to the device (Command status - INITIATED, ACKNOWLEDGED, INPROGRESS)
  • COMPLETE - Target run moves to complete state when it has completed running (Command status - FAILURE, SUCCESS, TIMEOUT, CANCELLED)
  • SUCCESS - A completed target run moves to success when the associated command is successful (Command status - SUCCESS)
  • FAILURE - A completed target run moves to success when the associated command is unsuccessful (Command status - FAILED, TIMEOUT, CANCELLED)
  • CANCELLED - Target run cancelled by the user (Target runs ind Pending, Queued and Processing state can be cancelled by the user)
  • TIMEOUT - The target run has a timed out. This happens when the target run has not completed processing even after the timeout period (7 days).
  • INVALID - Target run is invalid.
Operations

Device

APIs to retrieve information about the device or delete the device.

Operations

Device Heartbeat

APIs to retrieve information about device's heartbeat which contains the last seen details.

Operations

Device Apps

APIs to get apps installed on iOS devices. Use Application to get apps for Android devices.

Operations

Device Enrollment in EMM

APIs to enroll device with Google EMM

Operations

Operations [alpha]

APIs to get information about operations

Operations

DeviceOperations [alpha]

APIs to get information about device operations

Operations

MultiOS Remote Viewer

API to get Remote Viewer activity for the tenant. Currently supports only Android devices with DPC 8.4 and above along with RemoteViewer 3.x.

Operations

Device V2

Operations

VPP License Management

APIs for managing VPP licenses for apps. Learn more about VPP licenses.

Operations

VPP App Management

APIs for getting information about VPP apps. Learn more about VPP apps.

Operations

Tenant Apps

API to manage Enterprise iOS apps for a tenant.

Operations

Apple App Store

API to search apple app store for apps

Operations

App List

Unified API to query Webclips and Tenant IOS Apps

Operations

Webclips

API to manage webclips for a tenant

Operations

Provisioning Profiles

APIs for managing iOS provisioning profiles for app distribution

Operations

Esper Apps

Operations

Tenant Esper Apps

Operations

Command Request

APIs to view and manage command requests. Learn more about commands or how to schedule a command.

Scheduled commands are currently compatible with Android devices.

Operations

Command Status

APIs to view, filter, and manage command requests.

Operations

Converge

APIs to list and create converge actions for devices. Learn more about converge.

Operations

Converge Command

API for converge command

Operations

DEP Sync Request

APIs to create and access DEP sync request information. Use DEP sync to sync the information from your Apple Business Manager account to the Esper console.

Operations

ABM Provisioning

APIs to perform ABM provisioning. Learn more about ABM provisioning

Operations

APNs certificate

APIs for managing APNS certificates. Learn more about APNS certificates

Operations

DEP Tokens

APIs to create and access DEP tokens. Learn more about DEP tokens

Operations

VPP Token Management

APIs to create, access, and delete VPP tokens. Learn more about VPP tokens.

Operations

Get all VPP tokens for the tenant

Request

Returns all the VPP tokens for the tenant

Security
apiKey
curl -i -X GET \
  https://develop-api.esper.io/_mock/openapi/tenant/v0/vpptokens/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

VPP tokens for the Tenant

Bodyapplication/json
codeinteger
Default 200
messagestring
contentobject
Response
application/json
{
  "code": 200,
  "message": "string",
  "content": {
    "count": 0,
    "previous": "string",
    "next": "string",
    "results": [ … ]
  }
}

Store a VPP token

Request

Uploads a VPP token

Security
apiKey
Bodymultipart/form-data
filenamestring(binary)
curl -i -X POST \
  https://develop-api.esper.io/_mock/openapi/tenant/v0/vpptokens/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F filename=string

Responses

Created

Bodyapplication/json
codeinteger
Default 201
messagestring
contentobject(VPPToken)
Response
application/json
{
  "code": 201,
  "message": "string",
  "content": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "tenant_id": "string",
    "key": "string",
    "meta": {},
    "created_by": "string",
    "updated_by": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

Delete VPP Token

Request

API to delete vpp token for a tenant

Security
apiKey
Path
idintegerrequired
curl -i -X DELETE \
  'https://develop-api.esper.io/_mock/openapi/tenant/v0/vpptokens/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
codeinteger

response code

Default 204
messagestring

response message

contentobject
Response
application/json
{
  "code": 204,
  "message": "string",
  "content": {}
}

Google Enterprise

APIs to enroll the enterprise in Google EMM.

Operations

FoundryBuilds

Operations

FoundryDeviceModels

Operations

FoundryEvents

Operations

Reports API

APIs for managing reports.
Currently supports App Reports.

Operations

Query API

Operations

Ingest API

Operations