Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/esper:esper-commands-command-status-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: ESPER API REFERENCE commands_Command Status API
x-logo:
url: esper-logo-white.svg
backgroundColor: '#141418'
altText: Logo
description: '# 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:
* Getting started guides
* Commonly used API examples
* API command examples
* Automated Script examples
* And more
# 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. # Lifecycle Labels
Esper uses lifecycle labels to communicate the support status of each API endpoint. Use the following table to understand what each label means and how to respond. Badge
What it means
Recommended action
Stable
This endpoint is fully supported and safe for production use. No action needed. Beta
This endpoint is publicly available but may change. It is not recommended for production integrations. Use with caution. Monitor the API changelog for updates before relying on this endpoint. Legacy
This endpoint uses an older architecture and is still supported, but a newer equivalent exists. It is not recommended for new integrations. Plan migration to the recommended replacement when possible. See the endpoint description for the alternative. Deprecated
This endpoint has stopped being supported. A removal date may be added at a later time. A replacement is available or the feature is entirely retired. Migrate before the removal date listed in the endpoint description. Do not use this endpoint in new integrations. # 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. Parameter
Data Type
Explanation
limit
integer
Limit the data returned. Default = 20. offset
integer
Offset to the first item returned. Default = 0. ordering
string
Order the results set by the field name. Varies by endpoint. next
string
Paginate to the next response set. previous
string
Paginate 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:
```json
{
"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:
Number
Message
Explanation
200
OK
The request succeeded. 201
Resource creation
A resource was created. 401
Unauthorized
The API key is invalid. 404
Not found
The resource was not found. 429
Rate limit exceeded
Too many requests. Wait a moment and try again. 500
Server error
Internal 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.'
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
version: 1.0.0
x-prefix-tag: esper cloud api
servers:
- url: https://{foo}-api.esper.cloud/api
variables:
foo:
default: develop
description: Custom end point
tags:
- name: commands_Command Status
description: APIs to view, filter, and manage command requests.
x-displayName: Command Status
paths:
/commands/v0/status/:
get:
x-badges:
- name: Stable
color: green
summary: Get status list for command request
description: 'Retrieves a paginated, filterable list of individual command status records across the tenant.
Each record represents one command''s execution on one device, including its current state and the reason for that state. Filter by request, device, or state to narrow the list to the commands you''re investigating.
**About List Command Status**
While a command request can target many devices at once, each device gets its own CommandStatus record tracking its individual progress through the command lifecycle, moving through Command Queued, Command Initiated, Command Acknowledged, Command In Progress, and a terminal state such as Command Success, Command Failure, Command TimeOut, or Command Cancelled. This endpoint is the primary way to see exactly which devices succeeded or failed within a given command request.
**Key Fields / Query Parameters**
request — filters by one or more command request IDs, accepts comma-separated values
device — filters by one or more device IDs, accepts comma-separated values
state — filters by command state, for example Command Failure or Command Queued
exclude_internal_commands — excludes internally generated commands from the results when set to true
**Common Use Cases**
Listing every device that failed a specific command request
Checking whether a specific device has picked up a command it was sent
Auditing all command activity for a device over time by filtering on device alone
**Best Practices**
Combine request and state filters to jump straight to the failed devices within a large command request
Use exclude_internal_commands to keep results focused on customer-issued commands when auditing
**Workflow**
Identify the request id from the command request, or the device id you want to investigate
Call this endpoint with the appropriate filters
Use the returned command status id with GET /commands/v0/status/{id}/ for full detail on a specific record'
operationId: getCommandRequestStatuses
tags:
- commands_Command Status
security:
- commands_apiKey: []
parameters:
- in: query
name: request
description: Filter status result by command request IDs. Accepts comma separated values.
schema:
type: string
- in: query
name: device
description: Filter status result by device IDs. Accepts comma separated values.
schema:
type: string
- in: query
name: state
description: Filter by command state
schema:
type: string
enum:
- Command Queued
- Command Initiated
- Command Acknowledged
- Command In Progress
- Command TimeOut
- Command Success
- Command Failure
- Command Scheduled
- Command Cancelled
- in: query
name: exclude_internal_commands
description: Filter to exclude internal commands
schema:
type: boolean
default: false
- in: query
name: limit
schema:
type: number
- in: query
name: offset
schema:
type: number
responses:
'200':
description: Status list for a command request
content:
application/json:
schema:
type: object
properties:
code:
type: integer
message:
type: string
content:
type: object
properties:
count:
type: integer
previous:
type: string
next:
type: string
results:
type: array
items:
$ref: '#/components/schemas/commands_CommandStatus'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_401_Unauthorized'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_500_Internal_Server_Error'
/commands/v0/status/{id}/:
get:
x-badges:
- name: Stable
color: green
summary: Get a command status
description: 'Retrieves a single command status record by its ID.
Returns the full CommandStatus object for one device''s execution of one command, including its current state, the associated device and request IDs, and the reason for its current state.
**About Get Command Status**
This is the most granular status check available for a command''s execution on a specific device. Use it once you already have a command status id, typically obtained by filtering GET /commands/v0/status/ down to the record you care about.
**Common Use Cases**
Checking the current state and reason for one device''s execution of a command
Confirming a command has reached a terminal state before considering it complete
**Best Practices**
Use the reason field to understand why a command failed rather than only checking state
Cache this result briefly rather than polling continuously if the state is already terminal
**Workflow**
Filter GET /commands/v0/status/ by device or request to find the specific command status id
Call this endpoint with that id for the full record'
operationId: getCommandStatus
tags:
- commands_Command Status
security:
- commands_apiKey: []
parameters:
- name: id
in: path
description: ID of the command status object
required: true
schema:
type: string
responses:
'200':
description: Command status information
content:
application/json:
schema:
type: object
properties:
code:
type: integer
message:
type: string
content:
$ref: '#/components/schemas/commands_CommandStatus'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_401_Unauthorized'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_404_Not_Found'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_500_Internal_Server_Error'
put:
x-badges:
- name: Stable
color: green
summary: Update command status
description: 'Updates the state of an individual command status record. Supports only CANCEL. Cancellations are not always guaranteed and depends on the command''s exact state.
**About Update Command Status**
Each CommandStatus record tracks the execution of one command against one device and is created automatically when a command request targets that device. This endpoint lets you override the current lifecycle state directly rather than waiting for the device to report back. It''s typically used by internal tooling and integrations that need to reconcile command state (such as cancelling a command stuck in Command Queued) rather than as part of a normal command-issuing workflow.
**Key Fields / Request Body**
state — the new command state; accepts Command Cancelled
reason — free text explaining why the state was changed
**Common Use Cases**
Cancelling a command that is stuck in a queued state before it reaches the device
Forcing a command into a terminal state when a device is known to be offline or decommissioned
**Best Practices**
Use GET /commands/v0/status/{id}/ first to confirm the command''s current state before changing it
Always include a reason so the change is auditable in the command history
Prefer letting the device report its own status through the normal command lifecycle; only override manually when necessary
**Workflow**
Call GET /commands/v0/status/{id}/ to review the command''s current state and device
Determine the correct terminal or intermediate state to apply
PUT the new state and reason to this endpoint
Confirm the update by re-fetching the command status record'
operationId: updateCommandStatus
tags:
- commands_Command Status
parameters:
- name: id
in: path
description: ID of the command status object
required: true
schema:
type: string
security:
- commands_apiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/commands_CommandStatus_PUT'
responses:
'200':
description: Command status successfully updated.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
message:
type: string
content:
$ref: '#/components/schemas/commands_CommandStatus'
'304':
description: Command status was not modified because the requested state transition is not allowed.
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_400_Bad_Data'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_401_Unauthorized'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_500_Internal_Server_Error'
/v2/command-inbox/:
get:
x-badges:
- name: Stable
color: green
summary: Get queued commands to be executed by the physical device
description: 'Retrieves the commands currently queued for a specific device to execute.
This is the device-facing endpoint the Esper agent itself calls to pick up its pending work; it returns commands in the Command Queued state for the given device_id, along with the command arguments and basic device metadata.
**About Command Inbox**
While GET /commands/v0/status/ gives an administrative view of command execution across the tenant, the command inbox is the device-side queue that the Esper agent polls to find out what it needs to run next. It is scoped to a single device_id and reflects only commands that have not yet been picked up.
**Key Fields / Query Parameters**
device_id — the device whose queued commands should be returned, required
**Common Use Cases**
Verifying that a command was actually queued for delivery to a specific device
Diagnosing a device that isn''t executing commands by checking whether they are reaching its inbox at all
**Best Practices**
If a command doesn''t appear here after being issued, check the device''s connectivity and last-seen time before assuming the command failed to queue
Use this alongside GET /commands/v0/status/{id}/ to distinguish between a command that never reached the device and one that reached it but failed to execute
**Workflow**
Issue a command targeting the device through POST /commands/v0/commands/
Call this endpoint with the device_id to confirm the command is queued
If the command doesn''t appear, check the device''s last-seen status before retrying'
operationId: getCommandInbox
tags:
- commands_Command Status
parameters:
- in: query
name: device_id
description: Filter status result by device IDs.
required: true
schema:
type: string
security:
- commands_apiKey: []
responses:
'200':
description: List of Queued Command Status
content:
application/json:
schema:
type: object
properties:
code:
type: integer
message:
type: string
content:
$ref: '#/components/schemas/commands_CommandInbox'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_400_Bad_Data'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_401_Unauthorized'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/commands_Error_500_Internal_Server_Error'
components:
schemas:
commands_Error_500_Internal_Server_Error:
type: object
properties:
code:
type: integer
format: int32
default: 500
message:
type: string
content:
type: object
required:
- code
- message
commands_CommandStatus_PUT:
type: object
properties:
state:
type: string
description: Command state to update
enum:
- Command Acknowledged
- Command In Progress
- Command TimeOut
- Command Success
- Command Failure
- Command Scheduled
- Command Cancelled
reason:
type: string
description: State change reason to update
commands_Error_400_Bad_Data:
type: object
properties:
code:
type: integer
format: int32
default: 400
message:
type: string
content:
type: object
required:
- code
- message
commands_Error_404_Not_Found:
type: object
properties:
code:
type: integer
format: int32
default: 404
message:
type: string
content:
type: object
required:
- code
- message
commands_CommandInbox:
type: object
properties:
id:
type: string
description: Unique command identifier
format: uuid
readOnly: true
command:
type: string
description: The command to be executed
command_args:
type: object
description: Arguments for the command
properties:
script:
type: string
description: The script to be executed
device_meta:
type: object
description: Metadata about the device
properties:
platform:
type: string
description: The platform of the device
state:
type: string
description: Current state of the command
enum:
- Command Queued
created_on:
type: string
description: Timestamp of command creation
format: date-time
readOnly: true
updated_on:
type: string
description: Last updated timestamp of command
format: date-time
readOnly: true
commands_Error_401_Unauthorized:
type: object
properties:
code:
type: integer
format: int32
default: 401
message:
type: string
content:
type: object
required:
- code
- message
commands_CommandStatus:
type: object
properties:
id:
type: string
description: Unique command identifier
format: uuid
readOnly: true
request:
title: Request Id
type: string
description: Request Id associated with this command
format: uuid
readOnly: true
device:
title: Device
type: string
description: Device associated with this command
format: uuid
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_at:
type: string
description: Timestamp of command creation
format: date-time
readOnly: true
updated_at:
type: string
description: Last updated timestamp of command
format: date-time
readOnly: true
command_meta:
type:
- object
- 'null'
description: 'Optional metadata associated with the command execution result. Present only for commands that return structured data from the device.
'
properties:
result:
description: 'Command-specific result data. Structure varies by command type. For OS_UPDATE_STATUS, result is an object with fields: product_key, is_downloaded, download_percent_complete, status, product_version. For SCAN_OS_UPDATES, result is an array of objects with fields: product_key, product_version, build, human_readable_name, is_critical, download_size.
'
securitySchemes:
esper_cloud_api_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
pipelines_SCAPIAuthToken:
type: http
scheme: bearer
device_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
apps_management_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
commands_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
drift_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
device_onboarding_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
tenant_apiKey:
type: http
scheme: bearer
description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper 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 account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) 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 [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
foundation_AuthToken:
type: apiKey
in: header
name: Authorization
reports_bearerAuth:
type: http
scheme: bearer
geofence_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
x-tagGroups:
- name: ESPER CLOUD API
tags:
- esper_cloud_api_Company Settings
- esper_cloud_api_Application
- esper_cloud_api_Application V1
- esper_cloud_api_AndroidDevice
- esper_cloud_api_Device Group
- esper_cloud_api_Token (Deprecated)
- esper_cloud_api_Commands V2
- esper_cloud_api_Enterprise Policy
- esper_cloud_api_Geofence
- esper_cloud_api_Content
- esper_cloud_api_User (Deprecated)
- esper_cloud_api_User
- esper_cloud_api_Blueprint (Deprecated)
- esper_cloud_api_Directory Record
- esper_cloud_api_Tile Icon
- esper_cloud_api_Alerts
- esper_cloud_api_Alarms
- esper_cloud_api_Wallpapers
- esper_cloud_api_Device Telemetry
- esper_cloud_api_Daily and Custom Reports
- esper_cloud_api_SSO Connections
- esper_cloud_api_Roles
- esper_cloud_api_Personal Access Token
- name: BLUEPRINTS
tags:
- blueprints_Blueprints API
- blueprints_Custom Actions API
- blueprints_Background Scripts API
- name: PIPELINES
tags:
- pipelines_System Status Code
- pipelines_System
- pipelines_Pipelines
- pipelines_Stages
- pipelines_Target Lists
- pipelines_Targets
- pipelines_Device Groups
- pipelines_Operation Lists
- pipelines_Operations
- pipelines_Pipeline Runs
- pipelines_Stage Runs
- pipelines_Target Runs
- name: DEVICE
tags:
- device_Device
- device_Device Heartbeat
- device_Device Apps
- device_Device Enrollment in EMM
- device_Operations
- device_DeviceOperations
- device_MultiOS Remote Viewer
- name: APPS MANAGEMENT
tags:
- apps_management_VPP License Management
- apps_management_VPP App Management
- apps_management_Tenant Apps
- apps_management_Apple App Store
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/esper/refs/heads/main/openapi/esper-commands-command-status-api-openapi.yml