Device commands
The device command endpoints send a command to one managed device. They need an API key with the DEVICES_COMMAND permission, or DEVICES_COMMAND_DESTRUCTIVE for the destructive commands.
Overview
Each call acts on exactly one device, identified by its assetId, which is the pathName returned by GET /assets. There is no bulk endpoint. To command several devices, make one call per device within the rate limit. The endpoints do the same thing as the MCP command tools.
The key needs DEVICES_COMMAND and DEVICES_READ. change-policy also needs POLICIES_READ. The destructive commands need DEVICES_COMMAND_DESTRUCTIVE and DEVICES_READ instead. Send the key in the X-API-Key header. The REST API does not accept an Authorization header.
The device must be enrolled (status ACTIVE, INACTIVE or SYNCHRONIZING). Some commands work only on one kind of device, as each description below says: Android Management (Google-managed) devices, or devices managed by the Nomid agent (AOSP). Any other device gets 409. A message is a push notification to the Nomid agent and needs a registered push token.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /assets/{assetId}/commands/lock | Lock the device screen immediately. Android Management devices only. No request body. |
| POST | /assets/{assetId}/commands/lost-mode | Lock the device and show a message, with optional contact details, on its lock screen. Android Management devices only. |
| POST | /assets/{assetId}/commands/found | End lost mode. Nothing happens, and no error is returned, if the device was not in lost mode. Android Management devices only. No request body. |
| POST | /assets/{assetId}/commands/message | Show a plain-text push notification on the device. |
| POST | /assets/{assetId}/commands/status-report | Ask the device to send a fresh status report now. The report arrives later: read it with GET /assets/ASSET_ID. No request body. |
| POST | /assets/{assetId}/commands/location-update | Ask the device to report its current location now. The location arrives later: read it with GET /assets/ASSET_ID. No request body. |
| POST | /assets/{assetId}/commands/sync-policy | Send the device its current policy again. Devices managed by the Nomid agent (AOSP) only: Android Management devices receive policy changes automatically and answer 409. No request body. |
| POST | /assets/{assetId}/commands/reboot | Restart the device now. Whoever is using it is interrupted, and unsaved work may be lost. No request body. |
| POST | /assets/{assetId}/commands/shutdown | Power the device off now. It cannot be turned back on remotely. Devices managed by the Nomid agent (AOSP) only. No request body. |
| POST | /assets/{assetId}/commands/launch-app | Open an installed app on the device by package name. Devices managed by the Nomid agent (AOSP) only. |
| POST | /assets/{assetId}/commands/clear-app-data | Delete all data of the given apps (accounts, settings and files), as if they had just been installed. It cannot be undone. Android Management devices only. |
| POST | /assets/{assetId}/commands/change-policy | Move the device to another policy of the company. The device applies the new policy's apps, restrictions and settings, and anything only the current policy had is removed. Also needs POLICIES_READ. |
Send Content-Type: application/json with the lost-mode, message, launch-app, clear-app-data, uninstall-apps, change-policy and change-screen-lock-password endpoints. The other endpoints take no body. Unknown fields are rejected, and required text fields cannot be blank.
Destructive commands
These commands erase data, uninstall apps, remove or replace the screen lock, or end management of the device. With an API key they run as soon as the request is accepted. There is no approval step in the portal.
They need an API key with DEVICES_COMMAND_DESTRUCTIVE and DEVICES_READ. The company must also turn on destructive commands under AI agent access in the portal. That setting is off by default and needs device commands to be turned on too. Without it, the request returns 403 with code forbidden.
A key or connection can send at most 5 of these commands per hour, on top of the command rate limit. Over that limit the request returns 429 with a Retry-After header, and nothing is sent.
| Method | Endpoint | Description |
|---|---|---|
| POST | /assets/{assetId}/commands/wipe | Remove the device from management and erase its managed data. A company-owned device is factory reset: every app and all data on it are erased. On a personally owned device with a work profile, only the work profile and its apps and data are removed; personal apps and data stay. Irreversible. No request body. |
| POST | /assets/{assetId}/commands/reset-screen-lock | Remove the device's screen lock (PIN, pattern or password), so it can be unlocked without one. Android Management devices only. No request body. |
| POST | /assets/{assetId}/commands/change-screen-lock-password | Set a new screen lock password. The device locks, and only the new password unlocks it. Android Management devices only. |
| POST | /assets/{assetId}/commands/uninstall-apps | Uninstall the given apps and all their data from the device. Devices managed by the Nomid agent (AOSP), version 4.5.20 or later, only: Android Management devices answer 409, and an older agent records the command as failed. The device runs it when it next checks in, even days later. An app the device's policy still installs comes back on the next policy sync, so block it in the policy to keep it off. |
| POST | /assets/{assetId}/commands/relinquish-ownership | Release a company-owned device to its user. The work profile and its data are removed, and the device is no longer managed. Irreversible. No request body. |
change-screen-lock-password takes the new password in newPassword. Nomid never stores, returns or logs it.
Request bodies
Lost mode request body
| Field | Required | Description |
|---|---|---|
| message | Yes | Text shown on the lock screen. Up to 4096 characters. |
| phoneNumber | No | Contact phone number shown on the lock screen. Up to 4096 characters. |
| No | Contact email address shown on the lock screen. Must be a valid email address, up to 320 characters. | |
| streetAddress | No | Contact street address shown on the lock screen. Up to 4096 characters. |
| organization | No | Organization name shown on the lock screen. Up to 4096 characters. |
Message request body
| Field | Required | Description |
|---|---|---|
| title | Yes | Notification title. Up to 60 characters. |
| body | Yes | Notification text. Up to 500 characters. |
Launch app request body
| Field | Required | Description |
|---|---|---|
| packageName | Yes | Package name of the installed app to open, for example com.example.app. |
Clear app data request body
| Field | Required | Description |
|---|---|---|
| packageNames | Yes | Array of 1 to 20 package names, for example com.example.app, whose data is cleared. |
Change policy request body
| Field | Required | Description |
|---|---|---|
| policyId | Yes | The new policy, by its policyId (the pathName returned by GET /policies). |
Change screen lock password request body
| Field | Required | Description |
|---|---|---|
| newPassword | Yes | The new screen lock password, 4 to 128 characters, with no leading or trailing spaces. It is never stored, returned or logged. |
Uninstall apps request body
| Field | Required | Description |
|---|---|---|
| packageNames | Yes | Array of 1 to 20 package names, for example com.example.app, each listed once. The Nomid agent's own packages are refused with 400. |
Example: send a message
Replace the asset id with a pathName from GET /assets, and keep the key in an environment variable.
curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/message" \
-H "X-API-Key: $NOMID_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Please return this device", "body": "Bring it to the IT desk by 5 pm."}' {
"assetId": "k3x9m2pa",
"type": "NOTIFICATION_MESSAGE",
"status": "SUCCESS",
"createdAt": "2026-10-06T14:30:00Z"
} A 200 response means the command was created. The status field is the state of the command when the request returned. For a message, SUCCESS means the push was accepted for delivery, not that the user has seen it. Follow up with GET /assets/ASSET_ID/commands.
Example: lock a device
curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/lock" \
-H "X-API-Key: $NOMID_API_KEY" {
"assetId": "k3x9m2pa",
"type": "LOCK",
"status": "IN_PROGRESS",
"createdAt": "2026-10-06T14:30:00Z"
} Lock and lost mode return IN_PROGRESS while the device has not yet confirmed the command. The command history shows SUCCESS once it does. The lock endpoint takes no body.
Example: wipe a device
curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/wipe" \
-H "X-API-Key: $NOMID_API_KEY" {
"assetId": "k3x9m2pa",
"type": "WIPE_COMPANY_DATA",
"status": "IN_PROGRESS"
} A wipe of an Android Management device answers IN_PROGRESS without createdAt. Check the command history to follow it.
Responses and what to do
The retry rules matter. Retrying a command whose outcome is unknown can deliver it twice.
| Status | Meaning | What to do |
|---|---|---|
| 200 | The command was created and queued. | Read the status field. It is IN_PROGRESS until the device confirms the command, so check the command history for SUCCESS. Some commands, such as a reboot, wipe or relinquish ownership on an Android Management device, answer IN_PROGRESS without createdAt. |
| 202 | UNCONFIRMED. Nomid cannot tell whether the command reached the device, for example because the provider timed out or failed on its side. The body is the normal result object with status UNCONFIRMED and guidance in detail. Outside the lock, lost-mode, found and message endpoints it never has createdAt. | Do not resend. Check the device's command history first, and ask the user before sending again. For a message, the history may show ERROR even if the notification was shown. The command may only appear once the device acknowledges it. |
| 400 | The request body failed validation, or a parameter is invalid. | Fix the fields listed in the errors array or in detail. No command was sent. |
| 401 | The API key is missing, invalid or expired. | Send a valid key in the X-API-Key header. |
| 403 | The key does not have the permission the command needs, or, for a destructive command, the company has not turned on destructive commands. | Use a key created with DEVICES_COMMAND and DEVICES_READ, plus POLICIES_READ for change-policy, or with DEVICES_COMMAND_DESTRUCTIVE and DEVICES_READ for a destructive command. For destructive commands, also check the company setting under AI agent access in the portal. |
| 404 | No asset with this id exists in the key's company. An asset from another company also returns 404. On the lock, lost-mode, found and message endpoints the body is empty. On the other endpoints it is problem details with code not_found, and change-policy also returns it for an unknown policy. | Check the asset id against GET /assets, and for change-policy the policy id against GET /policies. |
| 409 | The device cannot take this command: it has no managed device, an ineligible status or an unsupported device type, or, for a message, no valid push token. change-policy also returns 409 when the device already uses that policy. Also returned when the provider reports that the device is no longer managed. Nomid then marks the device as deleted. | Retrying fails the same way until the device's state changes. Do not retry in a loop. |
| 422 | The provider evaluated the request and refused it for this device or message, or reported that the command already failed. | Do not retry with the same arguments. |
| 429 | The command rate limit was exceeded. A Retry-After header gives the seconds until the window resets. | Wait for the Retry-After time, then try again. |
| 500 | Unexpected error. Outside the lock, lost-mode, found and message endpoints the body has code internal_error and retryable false. Whether the command reached the device is unknown. | Do not resend straight away. Check the asset and its command history first. |
| 502 | Android Management rejected the command for a reason that is not about this device. The retryable member says whether to try again. Messages never return 502. | If retryable is true (the provider is throttling or reported a temporary conflict), retry after a short delay. If it is false, the company's Android Management setup has a problem: do not retry and contact support. |
| 503 | Not sent. The request failed inside Nomid before anything was dispatched. retryable is always true. | Safe to retry. Nothing was delivered, so a retry cannot duplicate the command. |
Error bodies
Errors from the command endpoints use application/problem+json (RFC 9457). On the lock, lost-mode, found and message endpoints, 401 and 429 return a small JSON object with error, message and status, 404 has no body, and only 502 and 503 add a boolean retryable member. On the other endpoints every error except 401 is problem details with a code member, such as not_found, unsupported, forbidden, invalid_arguments or rate_limited, and 429, 500, 502 and 503 also carry retryable. A 202 response is not an error: it carries the normal result object.
Example 202 response
HTTP/1.1 202 Accepted
{
"assetId": "k3x9m2pa",
"type": "LOCK",
"status": "UNCONFIRMED",
"detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
} Example 503 response
HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Service Unavailable",
"status": 503,
"detail": "Command was not sent; it is safe to retry.",
"instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
"retryable": true
} Example 404 response from an endpoint other than lock, lost-mode, found and message
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "No device found with assetId: k3x9m2pa",
"instance": "/emm/api/v1/assets/k3x9m2pa/commands/reboot",
"code": "not_found"
} Rate limit
Commands are limited to 10 per minute per API key, destructive commands included. The same budget is shared with the MCP command tools, with policy changes (each propose and apply call) and with provisioning QR codes, over REST or MCP. Over REST, requests over the limit get HTTP 429 with a Retry-After header.
On the lock, lost-mode, found and message endpoints, only keys with DEVICES_COMMAND spend this budget, and a request with an invalid body or an unknown asset id still counts, because the limit is applied before the request is validated. The other command endpoints, policy change calls and provisioning QR code requests spend it only once the request has passed the permission checks and argument validation.
Audit trail
Every command is recorded in the device's command history in the Nomid portal and attributed to the API key that sent it, not to a person. The entry shows api-key, the key id and the key prefix. The history returned by GET /assets/ASSET_ID/commands and by the MCP list_device_commands tool contains only type, status, createdAt, feedbackAt and outcome, not who sent the command.