M2X Command-Line Cheatsheet

The sample M2X commands below use cURL, a command line tool used to transfer data from or to a server. For more information on using cURL, please review the Using cURL Tutorial.

Service Status

Checking status & version of M2X API server

This command does not require any API key.

curl -i https://api-m2x.att.com/v2/status?pretty

Device Management

All the commands listed in this section require the use of a Master API Key. You can obtain and generate Master API Keys from the Account Settings page.

Replace the API key 7611hg8391k834829gkff640j8j990i2 in the commands below with your own API key.

Creating a Device

This command will create a public device named "Sample Device".

curl -i -X POST https://api-m2x.att.com/v2/devices -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"name\": \"Sample Device\", \"description\": \"My first device\", \"visibility\": \"public\" }"

Take note of the Location header in the response. You will use this URL for POSTing values to the device you have just created or configuring it.

Adding a Stream to an existing Device

Use this command to create a new stream called "temperature" (replace "temperature" in the command below in order to create or update other streams).

curl -i -X PUT https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"unit\": { \"label\": \"Celsius\", \"symbol\": \"C\" } }"

Retrieving information about a specific Device

Use this command to retrieve information about a specific Device.

curl -i https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i?pretty -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

Retrieving location information of a specific Device

curl -i https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/location?pretty -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

Updating location information of a specific Device

curl -i -X PUT https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/location -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"name\": \"Central Park\", \"latitude\": 40.77177, \"longitude\": -73.97352, \"elevation\": 0 }"

Retrieving list of streams and their current values for a specific Device

curl -i https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams?pretty -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

Retrieving values registered for a specific stream

The following command retrieves the three (3) most recent values registered for the temperature stream between Oct 1st 2014 and Oct 3rd 2014.

curl -i "https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/values?start=2014-10-01T12:00:00Z&end=2014-10-03T12:00:00Z&limit=3&pretty" -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

The start, end and limit parameters are optional.

min and max parameters can also be used to filter the returned data.

Retrieving values registered for a specific stream in CSV format

The following command retrieves the three (3) most recent values registered for the temperature stream between Oct 1st 2014 and Oct 3rd 2014 in CSV format.

curl -i "https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/values.csv?start=2014-10-01T12:00:00Z&end=2014-10-03T12:00:00Z&limit=3&pretty" -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

The start, end and limit parameters are optional.

min and max parameters can also be used to filter the returned data.

Sampling values for a specific stream

The following command retrieves every 2nd value registered for the temperature stream between Oct 1st 2014 and Oct 3rd 2014.

curl -i "https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/sampling?type=nth&interval=2&start=2014-10-01T12:00:00Z&end=2014-10-03T12:00:00Z&limit=4&pretty" -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

The type parameter is used to specify the required sampling type: accepted values are nth, min, max, count, avg and sum.

The interval parameter is used to specify the size of the sequence from which the first value is returned or the the interval time (in seconds) used to build the aggregation. Refer to the Device documentation for more information.

The start, end and limit parameters are optional.

min and max parameters can also be used to filter the returned data.

Sampling values for a specific stream in CSV format

The following command retrieves every 2nd value registered for the temperature stream between Oct 1st 2014 and Oct 3rd 2014 in CSV format.

curl -i "https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/sampling.csv?type=nth&interval=2&start=2014-10-01T12:00:00Z&end=2014-10-03T12:00:00Z&limit=4&pretty" -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

The type parameter is used to specify the required sampling type: accepted values are nth, min, max, count, avg and sum.

The interval parameter is used to specify the size of the sequence from which the first value is returned or the the interval time (in seconds) used to build the aggregation. Refer to the Device documentation for more information.

The start, end and limit parameters are optional.

min and max parameters can also be used to filter the returned data.

Retrieving statistics for a specific stream

The following command retrieves count, min, max, average and standard deviation stats from the temperature stream between Oct 1st 2014 and Oct 3rd 2014.

curl -i "https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/stats?start=2014-10-01T12:00:00Z&end=2014-10-03T12:00:00Z&pretty" -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

The start and end parameters are optional.

min and max parameters can also be used to filter the returned data.

Retrieving values registered for all streams of a device

The following command retrieves the ten (10) most recent values registered for the device's streams between Oct 1st 2014 and Oct 3rd 2014.

curl -i "https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/values?start=2014-10-01T12:00:00Z&end=2014-10-03T12:00:00Z&limit=10&pretty" -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

The start, end and limit parameters are optional.

min and max parameters can also be used to filter the returned data.

Pushing values to a specific device/stream

There are three different ways of pushing values to streams.

Updating a specific stream's current value

This command will push the specified value to the corresponding device & stream.

curl -i -X PUT https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/value -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"timestamp\": \"2014-10-03T12:00:00.789Z\", \"value\": 40 }"

Pushing multiple values to an existing stream at once

Another alternative is to push several values at once to an existing stream, like in the following command.

curl -i -X POST https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/streams/temperature/values -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"values\": [ { \"timestamp\": \"2014-10-01T12:00:00.123Z\", \"value\": 15 }, { \"timestamp\": \"2014-10-02T12:00:00.456Z\", \"value\": 20 }, { \"timestamp\": \"2014-10-03T12:00:00.789Z\", \"value\": 25 } ] }"

Notice that in this case, if the specified stream does not exist, the command will fail.

Timestamps should be specified in ISO-8601 format, plus three (3) optional fractions of a second.

Pushing multiple values to multiple streams at once

Finally, you can also push multiple values to several different streams at once with the following command:

curl -i -X POST https://api-m2x.att.com/v2/devices/02h280h4j05536hh19k5il21i085997i/updates -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"values\": { \"temperature\": [ { \"timestamp\": \"2014-10-01T12:00:00Z\", \"value\": 15 }, { \"timestamp\": \"2014-10-02T12:00:00.123Z\", \"value\": 20 }, { \"timestamp\": \"2014-10-03T12:00:00Z\", \"value\": 25 } ], \"humidity\": [ { \"timestamp\": \"2014-10-01T12:00:00Z\", \"value\": 80 }, { \"timestamp\": \"2014-10-02T12:00:00Z\", \"value\": 85 }, { \"timestamp\": \"2014-10-03T12:00:00Z\", \"value\": 80 } ] } }"

Launching a Device Distribution from an existing Device

This command will create a new device distribution named "Sample Distribution". All devices attached to this distribution will be based on the referenced base device.

curl -i -X POST https://api-m2x.att.com/v2/distributions?base_device=02h280h4j05536hh19k5il21i085997i -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"name\": \"Sample Distribution\", \"description\": \"My first distribution\", \"visibility\": \"public\" }"

You can also omit the base_device parameter. In this case, devices attached to this distribution will be created with no streams or triggers by default.

Take note of the Location header in the response. You will need this URL for adding devices to this distribution.

Retrieving information about a specific Distribution

Use this command to retrieve information about a specific Distribution and its structure.

curl -i https://api-m2x.att.com/v2/distributions/2g8678421335j99405k1l50205g5k85l?pretty -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2"

Adding a Device to an existing Distribution

This command will create a new device with the specified serial number and will attach it to the referenced distribution. The new device will be an identical copy of the distribution's base device.

curl -i -X POST https://api-m2x.att.com/v2/distributions/2g8678421335j99405k1l50205g5k85l/devices -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"serial\": \"ABC123\" }"

Notice that the serial number must be unique within the distribution.

Sending a Command to a Device

The following will send a user-defined command named "CHECK_UPDATES" to specified devices.

curl -i -X POST https://api-m2x.att.com/v2/commands -H "X-M2X-KEY: 7611hg8391k834829gkff640j8j990i2" -H "Content-Type: application/json" -d "{ \"name\": \"CHECK_UPDATES\", \"data\": { \"updates_server\": \"https://updates.example.com/\" }, \"targets\": { \"devices\": [\"02h280h4j05536hh19k5il21i085997i\"] } }"