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"
.