Commands are used to communicate with one or more specific devices. Commands will be delivered directly to target devices that are connected via MQTT, or devices may check periodically for outstanding commands via HTTP.
The Commands API allows you to send custom user-defined commands to devices and allows devices to issue their responses. The Commands API can also be used to view and audit the history of recently sent commands, along with the device responses.
The Commands API endpoints for sending commands and viewing sent commands require a Master API key in the X-M2X-KEY header. The endpoints for acknowledging commands and viewing received commands require a Primary Device API key (or Master API key) in the X-M2X-KEY header. Any attempt to use the incorrect key to access these endpoints would result in a 403 Forbidden response. Learn more about API Keys.
GET /commands
Retrieve the list of recent commands sent by the current account (as given by the API key). The following parameters are accepted:
limit the number of commands to return per page (optional). It must be a number between 1 and 1000. If a higher value is sent, the API will use 1000 instead. The default value is 100.page the page number to retrieve (optional). The default value is 1.dir the sorting direction for commands (optional). Commands are always sorted by sent_at time. The default direction is desc, which sorts in descending order (showing more recent commands first). If asc is specified, commands will be sorted in ascending order (showing older commands first).start return only commands sent after this time (optional).end return only commands sent before this time (optional).name return only commands whose name exactly matches the given name (optional).This endpoint requires a Master API key in the X-M2X-KEY header.
200 OK
Content-Type: application/json
{ "commands": [
{ "id": "201511ba7177ab93a26dc415fa01b11c498ec2",
"url": "https://api-m2x.att.com/v2/commands/201511ba7177ab93a26dc415fa01b11c498ec2",
"name": "CHECK_UPDATES",
"sent_at": "2015-11-01T10:30:46.508Z",
"status_counts": { "processed": 55, "rejected": 6, "pending": 39 } },
{ "id": "2015106b2ad8a344f1e4fb8b1f43acede30670",
"url": "https://api-m2x.att.com/v2/commands/2015106b2ad8a344f1e4fb8b1f43acede30670",
"name": "MAINTENANCE_UNLOCK",
"sent_at": "2015-10-22T23:42:13.438Z",
"status_counts": { "processed": 100 } },
{ "id": "2015105e8b6825053b5b9c66c261b66c206ae2",
"url": "https://api-m2x.att.com/v2/commands/2015105e8b6825053b5b9c66c261b66c206ae2",
"name": "MAINTENANCE_LOCK",
"sent_at": "2015-10-22T23:18:41.272Z",
"status_counts": { "processed": 100 } } ] }
POST /commands
Send a command with the given name to the given target devices. The name should be a custom string defined by the user and understood by the device.
A command may also include an optional custom data object with arbitrary string values at custom field names.
The M2X API will respond with a Location header providing the URL of the new command resource that the developer can GET to check device responses later.
name the user-defined name of the command (required).data an object containing custom data fields and values (optional).targets an object containing one or more target specifiers. For target specifier devices containing an array of device IDs, the command will be delivered to specified devices. For target specifier collections containing an array of collection IDs, the command will be delivered to all devices contained in specified collections and any nested subcollections. All devices and collections need to exist and be accessible by the API key (required).This endpoint requires a Master API key in the X-M2X-KEY header.
Content-Type: application/json
{ "name": "CHECK_UPDATES",
"data": { "updates_server": "https://updates.example.com/" },
"targets": { "devices": ["3d15f9f98ba9a4beb4790ebad4311cd6",
"65b89448f954f49e42b746d73b385cbb",
"9033bda03e2cad5cb757d024aa4a8462"],
"collections": ["1b3ba972fcf92a156fc8c0ca1554434c"] } }
202 Accepted
Location: https://api-m2x.att.com/v2/commands/20151189ab77eaffd7e16b4bb09bf746b5ba0a
403 Forbidden
Content-Type: application/json
{ "message": "Account Not Active", "description": "Your account has not been activated yet. If you need to re-send the activation email, please visit https://m2x.att.com/activation-required" }
422 Unprocessable Entity
Content-Type: application/json
{
"message": "Validation Failed",
"errors": {
"name": ["not_present"],
"data": [{ "update server": ["name_not_valid"],
"version_code": ["not_valid"] }],
"targets": [{
"devices": [{
"3d15f9f98ba9a4beb4790ebad4311cd6": ["not_found"],
"65b89448f954f49e42b746d73b385cbb": ["not_found"],
"9033bda03e2cad5cb757d024aa4a8462": ["not_found"]
}],
"collections": [{
"1b3ba972fcf92a156fc8c0ca1554434c": ["not_found"]
}]
}]
}
}
A developer will receive this response if one of these validations fail:
name must be a string (not_valid) no longer than 250 characters (too_long).data parameter, if given, must be an object containing valid field names and values. Field names must begin with a lowercase letter, may contain only lowercase letters, numbers, and the _ character (name_not_valid) and may be up to 250 characters long (name_too_long). Field values may be any string (not_valid) up to 5,000 characters long (too_long).targets parameter must be an object (not_valid) containing one or more known target specifiers (unknown). The devices target specifier should be an array of device IDs (not_valid) for devices that exist and are accessible by the permissions of the API key (not_found). The collections target specified should be an array of collection IDs (not_valid) for collections that exist and belong to the API key owner (not_found).GET /commands/{id}
Get details of a sent command including the delivery information for all devices that were targetted by the command at the time it was sent.
The deliveries attribute will contain an object with each key indicating the targetted device ID and the corresponding value being an object containing delivery information. The delivery information will include the status string, which starts as pending. When a command delivery is acknowledged by a device as processed or rejected, the delivery information will also include the received_at time and response_data, if any was given by the device.
This endpoint requires a Master API key in the X-M2X-KEY header.
200 OK
Content-Type: application/json
{
"id": "2015114750b32709e776efe0e4ea8563f20a02",
"url": "https://api-m2x.att.com/v2/commands/2015114750b32709e776efe0e4ea8563f20a02",
"name": "CHECK_UPDATES",
"data": { "update_server": "https://updates.example.com/" },
"sent_at": "2015-11-01T10:30:46.508Z",
"deliveries": {
"3d15f9f98ba9a4beb4790ebad4311cd6": { "status": "pending" },
"65b89448f954f49e42b746d73b385cbb": {
"status": "processed",
"response_data": { "updated_to": "v4.5.2" },
"received_at": "2015-11-01T10:30:47.324Z"
},
"9033bda03e2cad5cb757d024aa4a8462": {
"status": "rejected",
"response_data": { "reason": "timeout" },
"received_at": "2015-11-01T10:31:47.289Z"
}
}
}
404 Not Found
Content-Type: application/json
{ "message": "Command Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified command does not exist.
GET /devices/{id}/commands
Retrieve the list of recent commands sent to the current device (as given by the API key). The following parameters are accepted:
limit the number of commands to return per page (optional). It must be a number between 1 and 1000. If a higher value is sent, the API will use 1000 instead. The default value is 100.page the page number to retrieve (optional). The default value is 1.dir the sorting direction for commands (optional). Commands are always sorted by sent_at time. The default direction is desc, which sorts in descending order (showing more recent commands first). If asc is specified, commands will be sorted in ascending order (showing older commands first).start return only commands sent after this time (optional).end return only commands sent before this time (optional).name return only commands whose name exactly matches the given name (optional).status return only commands whose status matches the given status (optional).This endpoint requires a Primary Device API key (or Master API key) in the X-M2X-KEY header.
200 OK
Content-Type: application/json
{ "commands": [
{ "id": "201511ba7177ab93a26dc415fa01b11c498ec2",
"url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb/commands/201511ba7177ab93a26dc415fa01b11c498ec2",
"name": "CHECK_UPDATES",
"sent_at": "2015-11-01T10:30:46.508Z",
"status": "pending" },
{ "id": "2015106b2ad8a344f1e4fb8b1f43acede30670",
"url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb/commands/2015106b2ad8a344f1e4fb8b1f43acede30670",
"name": "MAINTENANCE_UNLOCK",
"sent_at": "2015-10-22T23:42:13.438Z",
"status": "processed",
"received_at": "2015-11-01T10:42:15.218Z" },
{ "id": "2015105e8b6825053b5b9c66c261b66c206ae2",
"url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb/commands/2015105e8b6825053b5b9c66c261b66c206ae2",
"name": "MAINTENANCE_LOCK",
"sent_at": "2015-10-22T23:18:41.272Z",
"status": "processed",
"received_at": "2015-11-01T23:18:41.965Z" } ] }
GET /devices/{id}/commands/{id}
Get details of a received command including the delivery information for this device.
The delivery information will include the status string, which starts as pending. When a command delivery is acknowledged by this device as processed or rejected, the delivery information will also include the received_at time and response_data, if any was given by the device.
This endpoint requires a Primary Device API key (or Master API key) in the X-M2X-KEY header.
200 OK
Content-Type: application/json
{ "id": "2015114750b32709e776efe0e4ea8563f20a02",
"url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb/commands/2015114750b32709e776efe0e4ea8563f20a02",
"name": "CHECK_UPDATES",
"data": { "update_server": "https://updates.example.com/" },
"sent_at": "2015-11-01T10:30:46.508Z",
"status": "processed",
"response_data": { "updated_to": "v4.5.2" },
"received_at": "2015-11-01T10:30:47.324Z" }
404 Not Found
Content-Type: application/json
{ "message": "Command Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified command does not exist or was not sent to this device.
POST /devices/{id}/commands/{id}/process
Mark the given command as processed by the device, changing the status from "pending" to "processed". If the status is already "processed" or "rejected", this endpoint will have no effect and the M2X API will respond with a conflict error.
A device may also provide optional response data as the JSON body of the API request. The response data takes the same form as the original command data, with arbitrary string values at custom field names.
This endpoint requires a Primary Device API key (or Master API key) in the X-M2X-KEY header.
Content-Type: application/json
{ "updated_to": "v4.5.2" }
204 No Content
404 Not Found
Content-Type: application/json
{ "message": "Command Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified command does not exist or was not sent to this device.
409 Conflict
Content-Type: application/json
{ "message": "Conflict", "description": "The delivery status for this command was already 'processed'" }
A developer will receive this response when the delivery of the command to this device was already acknowledged as "processed" or "rejected".
POST /devices/{id}/commands/{id}/reject
Mark the given command as rejected by the device, changing the status from "pending" to "rejected". If the status is already "processed" or "rejected", this endpoint will have no effect and the M2X API will respond with a conflict error.
A device may also provide optional response data as the JSON body of the API request. The response data takes the same form as the original command data, with arbitrary string values at custom field names.
This endpoint requires a Primary Device API key (or Master API key) in the X-M2X-KEY header.
Content-Type: application/json
{ "reason": "timeout" }
204 No Content
404 Not Found
Content-Type: application/json
{ "message": "Command Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified command does not exist or was not sent to this device.
409 Conflict
Content-Type: application/json
{ "message": "Conflict", "description": "The delivery status for this command was already 'rejected'" }
A developer will receive this response when the delivery of the command to this device was already acknowledged as "processed" or "rejected".
