Device API

The Device API allows you to interact with your devices (including creating new devices, updating devices, pushing data to a device stream, updating a device location, etc.) as well as public devices that belong to other M2X accounts. A Device is any individual generator of data that can be connected to M2X. This could be a physical device, application, service, or something else (e.g. a smart thermostat, iPhone app, etc.).

Devices can be identified in API calls to the Device API using either their unique id or the user defined serial of the Device. To identify a Device by its serial, just replace the {id} string with serial/{serial}, where {serial} is the actual user defined serial number. Notice that this method of identifying the Device only works on devices owned by you.

Authentication

With the exception of creating, updating, listing, searching and deleting Devices, all methods described in this page support both Master (account) and Device level API keys in the X-M2X-KEY header. Device level API keys can only access the Device which they belong to, and its access can be optionally limited to a single stream. Any attempt to use a Device level API key to access a different Device or Stream would result in a 403 Forbidden response. Learn more about API Keys.

List Public Devices Catalog

GET /devices/catalog

This allows unauthenticated users to search Devices from other accounts that have been marked as public, allowing them to read public Device metadata, locations, streams list, and view each Devices' stream metadata and its values.

The list of Public Devices can be paginated by using one or more of the (optional) following parameters:

  • page Page number to be retrieved.
  • limit Number of devices to return per page. It must be a number between 0 and 100. If a higher value is sent, the API will use 100 instead.

The catalog of public devices is sorted by descendant creation date by default, that is, newer devices appear first on the results list. Sorting direction is controlled by the dir parameter, allowing the values asc (default) and desc for ascending and descending order, respectively. The sorting field can be set by passing one of the following values on the sort parameter:

  • created: The device's creation date; this is the default.
  • name: The device's name
  • serial: The device's serial attribute.

Responses

Success

200 OK
Content-Type: application/json

{
  "devices": [
    {
      "id": "65b89448f954f49e42b746d73b385cbb",
      "url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb",
      "name": "Sample Device",
      "description": "Longer description for Sample Device",
      "visibility": "public",
      "status": "enabled",
      "collections": [],
      "serial": "1234",
      "tags": [],
      "location": {},
      "created": "2014-09-01T10:00:00.411Z",
      "updated": "2014-09-02T10:00:00.411Z"
    },
    { "id": "9033bda03e2cad5cb757d024aa4a8462",
      "name": "Another Device",
      "description": "Longer description for Another Device",
      "visibility": "private",
      "status": "enabled",
      "collections": ["f52434327625fcb490272d9fa6c34989"],
      "serial": "12345",
      "tags": [ "lorem", "ipsum" ],
      "url": "https://api-m2x.att.com/v2/devices/9033bda03e2cad5cb757d024aa4a8462",
      "location": {
        "name": "Storage Room",
        "latitude": -37.9788423562422,
        "longitude": -57.5478776916862,
        "elevation": 5 },
      "created": "2014-09-01T10:00:00.764Z",
      "updated": "2014-09-02T10:00:00.245Z"
    }
  ],
  "total": 1000,
  "pages": 500,
  "limit": 2,
  "current_page": 1
}

Search Public Devices Catalog

GET /devices/catalog/search

Search the catalog of public Devices. This allows unauthenticated users to search Devices from other accounts that have been marked as public, allowing them to read public Device metadata, locations, streams list, and view each Devices' stream metadata and its values.

The list of Public Devices can be filtered by using one or more of the (optional) following parameters:

  • name Text to search. Only devices containing this text in their name will be returned.
  • description Text to search. Only devices containing this text in their description will be returned.
  • page Page number to be retrieved.
  • limit Number of devices to return per page. It must be a number between 0 and 100. If a higher value is sent, the API will use 100 instead.
  • tags A comma delimited list of device tags.
  • serial A comma separated list of serial numbers. Only devices having a serial number from the list will be returned.

The catalog of public devices is sorted by descendant creation date by default, that is, newer devices appear first on the results list. Sorting direction is controlled by the dir parameter, allowing the values asc (default) and desc for ascending and descending order, respectively. The sorting field can be set by passing one of the following values on the sort parameter:

  • created: The device's creation date; this is the default.
  • name: The device's name.
  • serial: The device's serial attribute.

It is not possible to search for public devices of a specific account. If you want to search your own devices, then see the List/Search Devices endpoint documentation.

Devices can also be searched by their current stream values. The streams metadata, and location parameters, contrary to the other ones, cannot be sent via the query string. Instead, they should be sent as a JSON payload in the body of the request. Below follows a more detailed description and specification of each parameter.

Stream Filters

The streams parameter should be an object in which each key is the exact name of a stream, and the value is an object that holds the desired filters for the given stream.

The stream filters object can have multiple keys, and each one should be a valid operator, pointing to the value to be used for that particular operator.

This is an example of what this streams object could look like:

{
  "streams": {
    "temperature": {
      "gt": 10,
      "lt": 20
    },
    "altitude": {
      "eq": 2500
    },
    "contacts": {
      "match": "john"
    }
  }
}

In this example, Devices would be filtered returning only the ones that have a temperature stream with values greater than 10, but lower than 20, and at the same time having an altitude stream with a value of 2500 and a contacts stream with an alphanumeric value that contains the word "john".

The name used for each stream in this type of search needs to be an exact match, and the list of names cannot have repeated values.

Stream Filter Operators

Currently, the following operators are supported:

  • gt: filters numeric streams that have a value greater than the one specified.
  • gte: filters numeric streams that have a value equal to or greater than the one specified.
  • lt: filters numeric streams that have a value lesser than the one specified.
  • lte: filters numeric streams that have a value equal to or lesser than the one specified.
  • eq: filters numeric streams that have a value equal to the one specified.
  • match: filters alphanumeric streams that have a value which contains the one specified.

When using the eq or match operator, developers cannot specify additional filters for the same stream.

Metadata Filters

The metadata parameter should be an object in which each key is the exact name of a custom device metadata field, and the value is an object that holds the desired filters for the given field.

The metadata filters object should have a valid operator as the key, pointing to the value to be used for that particular operator.

This is an example of what this metadata object could look like:

{
  "metadata": {
    "color": {
      "match": "blue"
    },
    "owner": {
      "match": "Smith"
    }
  }
}

In this example, Devices would be filtered returning only the ones that have a color metadata field that contains the word blue, and an owner metadata field that contains the word Smith.

The name used for each metadata field in this type of search needs to be an exact match, and the list of names cannot have repeated values.

Metadata Filter Operators

Currently, only one operator is supported:

  • match: filters metadata fields that have a value which contains the one specified.

Location Filters

The location parameter should be an object in which each key is a valid location filter operator and the value contains the operator-specific parameters for that filter.

The location parameter can also be "none", which will filter devices that have no location information.

Location Filter Operators

Currently, the following operators are supported:

  • within_circle: filters devices to only those whose current location is within the described circle. The parameters object must specify the center of the circle as an object with latitude and longitude, and the radius of the circle as an object with a single key (a valid unit of distance: mi, miles or km) and value (the number of given units of distance).
{
  "location": {
    "within_circle": {
      "center": { "latitude": -37.978842, "longitude": -57.547877 },
      "radius": { "km": 100 }
    }
  }
}
  • within_polygon: filters devices to only those whose current location is within the described polygon. The parameters must be a sequential array of points describing the polygon, with each point being an object with latitude and longitude.
{
  "location": {
    "within_polygon": [
      { "latitude": -37.907115, "longitude": -57.492295 },
      { "latitude": -38.141558, "longitude": -57.509314 },
      { "latitude": -38.127339, "longitude": -57.681049 },
      { "latitude": -38.005071, "longitude": -57.730351 },
      { "latitude": -37.918260, "longitude": -57.685979 }
    ]
  }
}

Responses

Success

200 OK
Content-Type: application/json

{
  "devices": [
    {
      "id": "65b89448f954f49e42b746d73b385cbb",
      "url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb",
      "name": "Sample Device",
      "description": "Longer description for Sample Device",
      "visibility": "public",
      "status": "enabled",
      "collections": [],
      "serial": "1234",
      "tags": [],
      "location": {},
      "created": "2014-09-01T10:00:00.411Z",
      "updated": "2014-09-02T10:00:00.411Z"
    },
    { "id": "9033bda03e2cad5cb757d024aa4a8462",
      "name": "Another Device",
      "description": "Longer description for Another Device",
      "visibility": "private",
      "status": "enabled",
      "collections": ["f52434327625fcb490272d9fa6c34989"],
      "serial": "12345",
      "tags": [ "lorem", "ipsum" ],
      "url": "https://api-m2x.att.com/v2/devices/9033bda03e2cad5cb757d024aa4a8462",
      "location": {
        "name": "Storage Room",
        "latitude": -37.9788423562422,
        "longitude": -57.5478776916862,
        "elevation": 5 },
      "created": "2014-09-01T10:00:00.764Z",
      "updated": "2014-09-02T10:00:00.245Z"
    }
  ],
  "total": 1000,
  "pages": 500,
  "limit": 2,
  "current_page": 1
}

List Devices

GET /devices

Retrieve the list of devices accessible by the authenticated API key.

The current values for the streams of each device can be included using the following query parameter:

  • include_stream_values Either true, false, or a comma-separated list of stream names. If true, then the current value of all streams for each listed device will be included in the response. If false, no stream values will be retrieved (this is the default behavior). If a list of stream names is specified, then only the current value of those streams will be included in the response. Any stream which can't be found will be silently ignored.

The metadata of devices can be included using the following parameter:

  • include_metadata Either true or false.

The list of devices can be paginated and ordered by using one or more of the following parameters:

  • page Page number to be retrieved.
  • limit Number of devices to return per page. It must be a number between 0 and 100. If a higher value is sent, the API will use 100 instead.

Listed devices are sorted by descendant last activity timestamp by default. Sorting direction is controlled by the dir parameter, allowing the values asc (default) and desc for ascending and descending order, respectively. The sorting field can be set by passing one of the following values on the sort parameter:

  • created: device's creation date; this is the default.
  • last_activity: device's last activity.
  • name: device's name.
  • serial: device's serial attribute.

Responses

Success

200 OK
Content-Type: application/json

{ "devices": [
  { "id": "65b89448f954f49e42b746d73b385cbb",
    "name": "Sample Device",
    "description": "Longer description for Sample Device",
    "visibility": "public",
    "status": "enabled",
    "collections": [],
    "serial": "1234",
    "tags": [],
    "url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb",
    "location": {},
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb/streams",
      "count": 1,
      "values": {
        "temperature": 60
      }
    },
    "created": "2014-09-01T10:00:00.411Z",
    "updated": "2014-09-02T10:00:00.411Z" },
  { "id": "9033bda03e2cad5cb757d024aa4a8462",
    "name": "Another Device",
    "description": "Longer description for Another Device",
    "visibility": "private",
    "status": "enabled",
    "collections": ["f52434327625fcb490272d9fa6c34989"],
    "serial": "12345",
    "tags": [ "lorem", "ipsum" ],
    "url": "https://api-m2x.att.com/v2/devices/9033bda03e2cad5cb757d024aa4a8462",
    "location": {
      "name": "Storage Room",
      "latitude": -37.9788423562422,
      "longitude": -57.5478776916862,
      "elevation": 5
    },
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/9033bda03e2cad5cb757d024aa4a8462/streams",
      "count": 1,
      "values": {
        "pressure": 1200
      }
    },
    "created": "2014-09-01T10:00:00.764Z",
    "updated": "2014-09-02T10:00:00.245Z" }
  ],
  "total": 1000,
  "pages": 500,
  "limit": 2,
  "current_page": 1 }

Inactive Account

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

Search Devices

GET /devices/search

Retrieve the list of devices accessible by the authenticated API key that meet the search criteria.

The current values for the streams of each device can be included using the following query parameter:

  • include_stream_values Either true, false, or a comma-separated list of stream names. If true, then the current value of all streams for each listed device will be included in the response. If false, no stream values will be retrieved (this is the default behavior). If a list of stream names is specified, then only the current value of those streams will be included in the response. Any stream which can't be found will be silently ignored.

The metadata of devices can be included using the following parameter:

  • include_metadata Either true or false.

The list of devices can be filtered by using one or more of the following parameters:

  • ids A comma separated list of device IDs. Only devices having an ID from the list will be returned.
  • name Text to search. Only devices containing this text in their name will be returned.
  • description Text to search. Only devices containing this text in their description will be returned.
  • page Page number to be retrieved.
  • limit Number of devices to return per page. It must be a number between 0 and 100. If a higher value is sent, the API will use 100 instead.
  • tags A comma delimited list of device tags. A special value none searches devices which have no tags.
  • status Either enabled or disabled. When not specified, both enabled and disabled devices will be returned.
  • visibility Either public or private. When not specified, both public and private devices will be returned.
  • modified_since An ISO8601 timestamp. All devices modified since this parameter will be included. Any updates to a device including updating device details or pushing values to the device are considered modifications to the device.
  • unmodified_since An ISO8601 timestamp. All devices modified before this parameter will be included. Any updates to a device including updating device details or pushing values to the device are considered modifications to the device.
  • serial A comma separated list of serial numbers. Only devices having a serial number from the list will be returned.
  • collection An optional id of a Collection owned by the authenticated account. Only devices included in the collection will be returned.
  • distribution An optional id of a Distribution owned by the authenticated account. Only devices included in the distribution will be returned.
  • triggers A comma separated list of trigger names. Only devices having triggers with the given names will be returned.
  • activated_triggers A comma separated list of trigger names. Only devices having activated triggers with the given names will be returned. Developers can also use * as the value for this filter in order to search for devices that have any activated triggers, regardless of their name.
  • inactive_triggers A comma separated list of trigger names. Only devices having inactive triggers with the given names will be returned. Developers can also use * as the value for this filter in order to search for devices that have any inactive triggers, regardless of their name.
  • enabled_triggers A comma separated list of trigger names. Only devices having enabled triggers with the given names will be returned. Developers can also use * as the value for this filter in order to search for devices that have any enabled triggers, regardless of their name.
  • disabled_triggers A comma separated list of trigger names. Only devices having disabled triggers with the given names will be returned. Developers can also use * as the value for this filter in order to search for devices that have any disabled triggers, regardless of their name.
  • command_status One of pending, rejected or processed. Will only return devices that were sent one or more commands within the last 7 days (or since command_since) that have the given status.
  • command_name Will only return devices that were sent one or more commands within the last 7 days (or since command_since) that have the given name.
  • command_since An ISO8601 timestamp which cannot be older than 7 days ago. Will only return devices that were sent one or more commands since the given timestamp.

Listing your devices is sorted by descendant last activity timestamp by default. Sorting direction is controlled by the dir parameter, allowing the values asc (default) and desc for ascending and descending order, respectively. The sorting field can be set by passing one of the following values on the sort parameter

  • created: device's creation date; this is the default.
  • last_activity: device's last activity.
  • name: device's name.
  • serial: device's serial attribute.

Devices can also be searched by their metadata and/or current stream values. The streams metadata, and location parameters, contrary to the other ones, cannot be sent via the query string. Instead, they should be sent as a JSON payload in the body of the request. Below follows a more detailed description and specification of each parameter.

Stream Filters

The streams parameter should be an object in which each key is the exact name of a stream, and the value is an object that holds the desired filters for the given stream.

The stream filters object can have multiple keys, and each one should be a valid operator, pointing to the value to be used for that particular operator.

This is an example of what this streams object could look like:

{
  "streams": {
    "temperature": {
      "gt": 10,
      "lt": 20
    },
    "altitude": {
      "eq": 2500
    },
    "contacts": {
      "match": "john"
    }
  }
}

In this example, Devices would be filtered returning only the ones that have a temperature stream with values greater than 10, but lower than 20, and at the same time having an altitude stream with a value of 2500 and a contacts stream with an alphanumeric value that contains the word "john".

The name used for each stream in this type of search needs to be an exact match, and the list of names cannot have repeated values.

Stream Filter Operators

Currently, the following operators are supported:

  • gt: filters numeric streams that have a value greater than the one specified.
  • gte: filters numeric streams that have a value equal to or greater than the one specified.
  • lt: filters numeric streams that have a value lesser than the one specified.
  • lte: filters numeric streams that have a value equal to or lesser than the one specified.
  • eq: filters numeric streams that have a value equal to the one specified.
  • match: filters alphanumeric streams that have a value which contains the one specified.

When using the eq or match operator, developers cannot specify additional filters for the same stream.

Metadata Filters

The metadata parameter should be an object in which each key is the exact name of a custom device metadata field, and the value is an object that holds the desired filters for the given field.

The metadata filters object should have a valid operator as the key, pointing to the value to be used for that particular operator.

This is an example of what this metadata object could look like:

{
  "metadata": {
    "color": {
      "match": "blue"
    },
    "owner": {
      "match": "Smith"
    }
  }
}

In this example, Devices would be filtered returning only the ones that have a color metadata field that contains the word blue, and an owner metadata field that contains the word Smith.

The name used for each metadata field in this type of search needs to be an exact match, and the list of names cannot have repeated values.

Metadata Filter Operators

Currently, only one operator is supported:

  • match: filters metadata fields that have a value which contains the one specified.

Location Filters

The location parameter should be an object in which each key is a valid location filter operator and the value contains the operator-specific parameters for that filter.

The location parameter can also be "none", which will filter devices that have no location information.

Location Filter Operators

Currently, the following operators are supported:

  • within_circle: filters devices to only those whose current location is within the described circle. The parameters object must specify the center of the circle as an object with latitude and longitude, and the radius of the circle as an object with a single key (a valid unit of distance: mi, miles or km) and value (the number of given units of distance).
{
  "location": {
    "within_circle": {
      "center": { "latitude": -37.978842, "longitude": -57.547877 },
      "radius": { "km": 100 }
    }
  }
}
  • within_polygon: filters devices to only those whose current location is within the described polygon. The parameters must be a sequential array of points describing the polygon, with each point being an object with latitude and longitude.
{
  "location": {
    "within_polygon": [
      { "latitude": -37.907115, "longitude": -57.492295 },
      { "latitude": -38.141558, "longitude": -57.509314 },
      { "latitude": -38.127339, "longitude": -57.681049 },
      { "latitude": -38.005071, "longitude": -57.730351 },
      { "latitude": -37.918260, "longitude": -57.685979 }
    ]
  }
}

This method requires that a master API key is specified in the X-M2X-KEY header.

Responses

Success

200 OK
Content-Type: application/json

{ "devices": [
  { "id": "65b89448f954f49e42b746d73b385cbb",
    "name": "Sample Device",
    "description": "Longer description for Sample Device",
    "visibility": "public",
    "status": "enabled",
    "collections": ["f52434327625fcb490272d9fa6c34989"],
    "serial": "1234",
    "tags": [],
    "url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb",
    "location": {},
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/65b89448f954f49e42b746d73b385cbb/streams",
      "count": 1,
      "values": {
        "temperature": 60
      }
    },
    "created": "2014-09-01T10:00:00.411Z",
    "updated": "2014-09-02T10:00:00.411Z" },
  { "id": "9033bda03e2cad5cb757d024aa4a8462",
    "name": "Another Device",
    "description": "Longer description for Another Device",
    "visibility": "private",
    "status": "enabled",
    "collections": [],
    "serial": "12345",
    "tags": [ "lorem", "ipsum" ],
    "url": "https://api-m2x.att.com/v2/devices/9033bda03e2cad5cb757d024aa4a8462",
    "location": {
      "name": "Storage Room",
      "latitude": -37.9788423562422,
      "longitude": -57.5478776916862,
      "elevation": 5
    },
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/9033bda03e2cad5cb757d024aa4a8462/streams",
      "count": 1,
      "values": {
        "temperature": 60
      }
    },
    "created": "2014-09-01T10:00:00.764Z",
    "updated": "2014-09-02T10:00:00.245Z" } ],
  "total": 1000,
  "pages": 500,
  "limit": 2,
  "current_page": 1 }

Inactive Account

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

List Device Tags

GET /devices/tags

Retrieve the list of device tags for the authenticated account.

This method requires that a Master API Key is specified in the X-M2X-KEY header.

Responses

Success

200 OK
Content-Type: application/json

{ "tags": {
    "tag #1": 14,
    "tag #2": 10
  } }

Inactive Account

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

Create Device

POST /devices

Create a new Device. Accepts the following parameters:

  • name the name of the new device (required).
  • description containing a longer description (optional).
  • visibility either "public" or "private" (required).
  • tags a comma separated list of device tag names. The tag "none" is reserved for internal use (optional).
  • metadata an object containing custom metadata fields and values (optional).
  • base_device the id of an existing device to be duplicated (optional).
  • serial the device serial number (optional). Only letters, numeric digits, dashes, underscores and dots can be used for this field. Serial numbers cannot be repeated between devices belonging to the same account.

This method requires that a Master API Key is specified in the X-M2X-KEY header.

When sending the base_device parameter, the attributes from that device will be used to create the new one. base_device can be the id of any device on your account, or any device with "public" visibility (regardless of account owner).

In that case, The name, description and visibility parameters become optional and are used to override the base device attributes.

All streams within the base device will be copied over to the newly created device. If the developer owns the base device, then all the triggers will be copied as well, in a disabled state.

Request

Content-Type: application/json

{ "name": "Sample Device",
  "description": "Longer description for Sample Device",
  "tags": "lorem, ipsum",
  "visibility": "public" }

Responses

Success

201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782

{ "id": "b1e8abbad65cb52b0d75eb2e63efa782",
  "name": "Sample Device",
  "description": "Longer description for Sample Device",
  "visibility": "public",
  "serial": null,
  "status": "enabled",
  "collections": [],
  "tags": ["ipsum", "lorem"],
  "metadata": {},
  "url": "https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782",
  "streams": {
    "url": "https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782/streams",
    "count": 0,
    "values": {}
  },
  "key": "78981e4daf83c38cab03d83d513db7be",
  "created": "2014-10-21T23:13:03.667Z",
  "updated": "2014-10-21T23:13:03.667Z" }

Inactive Account

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

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "name": ["not_present"] } }

A developer will receive this response if one of these validations fail:

  • The name must be specified (not_present).
  • The visibility must be either "public" or "private" (not_valid).
  • The tags must be a string (not_valid).
  • The tags must not contain "none" (not_valid).
  • The metadata parameter must be an object containing valid metadata (see Update Device Metadata).

Update Device Details

PUT /devices/{id}
PUT /devices/serial/{serial}

Update an existing Device's information. Accepts the following parameters:

  • name (required)
  • description (optional)
  • visibility either "public" or "private" (required).
  • tags a comma separated list of device tag names. The tag "none" is reserved for internal use (optional).
  • metadata an object containing custom metadata fields and values (optional).
  • serial the device serial number (optional). Only letters, numeric digits, dashes, underscores and dots can be used for this field. Serial numbers cannot be repeated between devices belonging to the same account.

This method requires that a Master API Key is specified in the X-M2X-KEY header.

Request

Content-Type: application/json

{ "name": "Sample Device",
  "description": "Longer description for Sample Device",
  "tags": "",
  "visibility": "public" }

Responses

Success

204 No Content

Inactive Account

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

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "name": ["not_present"] } }

A developer will receive this response if one of these validations fail:

  • The name must be specified (not_present).
  • The visibility must be either "public" or "private" (not_valid).
  • The tags must be a string (not_valid).
  • The tags must not contain "none" (not_valid).
  • The metadata parameter must be an object containing valid metadata (see Update Device Metadata).

View Device Details

GET /devices/{id}
GET /devices/serial/{serial}

Get details of an existing Device.

The current values for the streams of each device can be included using the following query parameter:

  • include_stream_values Either true, false, or a comma-separated list of stream names. If true, then the current value of all streams for each listed device will be included in the response. If false, no stream values will be retrieved (this is the default behavior). If a list of stream names is specified, then only the current value of those streams will be included in the response. Any stream which can't be found will be silently ignored.

Responses

Success

200 OK
Content-Type: application/json

{ "id": "a4f919d931c265ddd7b76649eac22f7e",
  "name": "Sample Device",
  "description": "Sample Device",
  "visibility": "public",
  "status": "enabled",
  "collections": ["f52434327625fcb490272d9fa6c34989"],
  "serial": "1234",
  "tags": [ "lorem" ],
  "metadata": {},
  "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e",
  "location": {
    "name": "Storage Room",
    "latitude": "-37.9788423562422",
    "longitude": "-57.5478776916862",
    "elevation": "5"
  },
  "streams": {
    "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/streams",
    "count": 1,
    "values": {
      "temperature": 72
    }
  },
  "created": "2014-09-10T13:00:00.234Z",
  "updated": "2014-09-10T14:10:00.765Z"
}

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Read Device Location

GET /devices/{id}/location
GET /devices/serial/{serial}/location

Get location details of an existing Device. Returns the most recently logged location, along with the 30 most recent waypoints.

Responses

Success

200 OK
Content-Type: application/json

{ "name": "Storage Room",
  "latitude": -37.9788423562422,
  "longitude": -57.5478776916862,
  "elevation": 5,
  "timestamp": "2014-09-10T19:15:00.756Z",
  "waypoints": [ { "timestamp": "2014-09-10T19:15:00.756Z",
                   "latitude": -37.9788423562422,
                   "longitude": -57.5478776916862,
                   "elevation": 5 } ] }

No Location Info Available

204 No Content

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Read Device Location History

GET /devices/{id}/location/waypoints
GET /devices/serial/{serial}/location/waypoints

Get location history details of an existing Device. Returns the 30 most recently logged locations by default.

It accepts the following parameter:

  • limit (optional) Maximum number of waypoints to return. If omitted it defaults to 30. The maximum value for this parameter is 10,000. If a greater number is specified, the server will only return the 10,000 most recent waypoints registered for this device.

Responses

Success

200 OK
Content-Type: application/json

{ "waypoints": [
  { "name": "Storage Room",
    "latitude": -37.9788423562422,
    "longitude": -57.5478776916862,
    "elevation": 5,
    "timestamp": "2014-09-10T19:20:00.756Z" },
  { "name": "Storage Room",
    "latitude": -37.9788423562422,
    "longitude": -57.5478776916862,
    "elevation": 10,
    "timestamp": "2014-09-10T19:15:00.756Z" } ] }

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Delete Location History

DELETE /devices/{id}/location/waypoints
DELETE /devices/serial/{serial}/location/waypoints

Delete waypoints in a device's location history by a date range. Deletion will take place asynchronously. The following parameters are required:

  • from timestamp in ISO 8601 format.
  • end timestamp in ISO 8601 format.

Request

Content-Type: application/json

{ "from": "2014-09-09T19:15:00.624Z",
  "end": "2014-09-09T20:15:00.522Z" }

Responses

Success

202 Accepted

Bad Request

400 Bad Request
Content-Type: application/json

{ "message": "Invalid range" }

A developer will receive this response if from is not less than or equal to end timestamp.

400 Bad Request
Content-Type: application/json

{ "message": "Invalid start/end timestamp" }

A developer will receive this response if from or end are invalid ISO8601 timestamps.

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Update Device Location

PUT /devices/{id}/location
PUT /devices/serial/{serial}/location

Update the current location of the specified device. Accepts the following parameters:

  • name a name identifying this location (optional).
  • latitude (required)
  • longitude (required)
  • elevation (optional)
  • timestamp (optional, defaults to server current time)

Request

Content-Type: application/json

{ "name": "Storage Room",
  "latitude": -37.9788423562422,
  "longitude": -57.5478776916862,
  "timestamp": "2014-09-10T19:15:00.756Z",
  "elevation": 5 }

Responses

Success

202 Accepted

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "latitude": ["not_present"], "longitude": ["not_valid"] } }

A developer will receive this response if one or more of these validations fail:

  • Latitude and longitude values must be provided (not_present).
  • Latitude must be a numeric value between -90 and 90 (not_in_range).
  • Longitude must be a numeric value between -180 and 180 (not_in_range).

Notice that name and elevation values are optional.

Read Device Metadata

GET /devices/{id}/metadata
GET /devices/serial/{serial}/metadata

Get custom metadata of an existing Device.

Responses

Success

200 OK
Content-Type: application/json

{ "color": "blue",
  "owner": "John Smith" }

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Update Device Metadata

PUT /devices/{id}/metadata
PUT /devices/serial/{serial}/metadata

Update the custom metadata of the specified Device. Device metadata can store arbitrary string values at custom field names. Each time the device metadata is updated, the current metadata is discarded and only the updated metadata is retained.

Field names must begin with a lowercase letter, may contain only lowercase letters, numbers, and the _ character and may be up to 250 characters long. Field values may be any string up to 5,000 characters.

Request

Content-Type: application/json

{ "color": "blue",
  "owner": "John Smith" }

Responses

Success

204 No Content

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "color_code": ["not_valid"], "owner name": ["name_not_valid"] } }

A developer will receive this response if one or more of these validations fail:

  • Field value must be a string (not_valid).
  • Field value must be no longer than 5,000 characters (too_long).
  • Field name must contain only allowed characters (name_not_valid).
  • Field name must be no longer than 250 characters (name_too_long).

Read Device Metadata Field

GET /devices/{id}/metadata/{field}
GET /devices/serial/{serial}/metadata/{field}

Get the value of a single custom metadata field from an existing Device. The final segment of the path specifies the metadata field name from which the value should be read.

Responses

Success

200 OK
Content-Type: application/json

{ "value": "John Smith" }

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Metadata Field Not Found

404 Not Found
Content-Type: application/json

{ "message": "Metadata Field 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 metadata field does not exist in the given Device.

Update Device Metadata Field

PUT /devices/{id}/metadata/{field}
PUT /devices/serial/{serial}/metadata/{field}

Update the custom metadata of the specified Device. Device metadata can store arbitrary string values at custom field names. The final segment of the path specifies the metadata field name in which the given value should be stored.

Field names must begin with a lowercase letter, may contain only lowercase letters, numbers, and the _ character and may be up to 250 characters long. Field values may be any string up to 5,000 characters.

Request

Content-Type: application/json

{ "value": "John Smith" }

Responses

Success

204 No Content

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "owner": ["not_valid"] } }

A developer will receive this response if one or more of these validations fail:

  • Field value must be a string (not_valid).
  • Field value must be no longer than 5,000 characters (too_long).
  • Field name must contain only allowed characters (name_not_valid).
  • Field name must be no longer than 250 characters (name_too_long).

List Data Streams

GET /devices/{id}/streams
GET /devices/serial/{serial}/streams

Retrieve list of data streams associated with the specified device.

Responses

Success

200 OK
Content-Type: application/json

{ "streams": [
  { "name": "temperature",
    "display_name": "Temperature",
    "type": "numeric",
    "value": 32,
    "latest_value_at":"2014-09-10T19:15:00.325Z",
    "unit": { "label": "celsius", "symbol": "C" },
    "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/streams/temperature",
    "created": "2014-09-09T19:15:00.895Z",
    "updated": "2014-09-10T19:15:00.325Z" },
  { "name": "humidity",
    "display_name": "Humidity",
    "type": "numeric",
    "value": 80,
    "latest_value_at":"2014-09-10T19:15:00.325Z",
    "unit": { "label": "percent", "symbol": "%" },
    "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/streams/humidity",
    "created": "2014-09-09T19:15:00.875Z",
    "updated": "2014-09-10T19:15:00.234Z" } ] }

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Create/Update Data Stream

PUT /devices/{id}/streams/{name}
PUT /devices/serial/{serial}/streams/{name}

Update a data stream associated with the specified Device (if a stream with this name does not exist it gets created).

Data streams accept only numeric values by default, this behavior can be configured by setting the type attribute to alphanumeric upon creation. Once a stream is created, it's type cannot be changed.

This request accepts the following parameters:

  • display_name the name used in reports and charts to identify this stream. Unlike the name attribute, it accepts spaces and symbols (optional).
  • unit a JSON object describing the unit used to measure this stream's values. It accepts two attributes: label and symbol (optional).
  • type the stream's type. This value can be numeric or alphanumeric and can only be specified when creating a data stream. (optional, type is numeric by default)

Alphanumeric streams have a limit of 5,000 characters for each pushed value.

Request

Content-Type: application/json

{ "display_name": "Temperature", "unit": { "label": "celsius", "symbol": "C" } }

Responses

Success

204 No Content

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Create Multiple Data Streams

POST /devices/{id}/streams
POST /devices/serial/{serial}/streams
PUT /devices/{id}/streams
PUT /devices/serial/{serial}/streams

Create (POST/PUT) and/or update (PUT only) multiple data streams associated with the specified Device.

The request accepts the following parameters:

  • streams an array of stream attributes.

The stream attributes should be an object with the following attributes:

  • name (required) will be the name of the stream.
  • display_name the name used in reports and charts to identify this stream. Unlike the name attribute, it accepts spaces and symbols (optional).
  • unit a JSON object describing the unit used to measure this stream's values. It accepts two attributes: label and symbol.
  • type the stream's type. This value can be numeric or alphanumeric and can only be specified when creating a data stream. (optional, type is numeric by default)

Alphanumeric streams have a limit of 5,000 characters for each pushed value.

Differences between the POST and PUT version of this request: * POST: all streams must not exist on the device, otherwise the request will fail completely. * PUT: any streams that already exist on the device will be updated and those that do not already exist will be created.

Request

Content-Type: application/json

{ "streams": [
    { "name": "temperature", "display_name": "Temperature", "unit": { "label": "celsius", "symbol": "C" } },
    { "name": "humidity", "display_name": "Humidity" }
    ]
}

Responses

Success

200 OK
Content-Type: application/json

[
  { "name": "temperature",
    "display_name": "Temperature",
    "type": "numeric",
    "value": 0,
    "latest_value_at": null,
    "unit": { "label": "celsius", "symbol": "C" },
    "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/streams/temperature",
    "created": "2014-09-09T19:15:00.344Z",
    "updated": "2014-09-10T19:15:00.390Z" },
  { "name": "humidity",
    "display_name": "humidity",
    "type": "numeric",
    "value": 0,
    "latest_value_at": null,
    "unit": null,
    "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/streams/humidity",
    "created": "2014-09-09T19:15:00.344Z",
    "updated": "2014-09-10T19:15:00.390Z" }
  ]

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.

Update Data Stream Value

PUT /devices/{id}/streams/{name}/value
PUT /devices/serial/{serial}/streams/{name}/value

Update the current stream value of the specified stream. Optionally, a timestamp can be specified. If omitted, the current server time will be used.

Request

Content-Type: application/json

{ "timestamp": "2014-10-01T12:00:00Z", "value": 100 }

Responses

Success

202 Accepted

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist.

Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 Stream does not exist.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "value": ["not_present"] } }

A developer will receive this response if one or more of these validations fail:

  • value must be provided (not_present).
  • timestamp must be valid if provided (not_valid).

View Data Stream

GET /devices/{id}/streams/{name}
GET /devices/serial/{serial}/streams/{name}

Get details of a specific data Stream associated with an existing device.

Responses

Success

200 OK
Content-Type: application/json

{ "name": "temperature",
  "display_name": "Temperature",
  "type": "numeric",
  "value": 32,
  "latest_value_at":"2014-09-10T19:15:01.325Z",
  "unit": { "label": "celsius", "symbol": "C" },
  "url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/streams/temperature",
  "created": "2014-09-09T19:15:00.344Z",
  "updated": "2014-09-10T19:15:00.390Z" }

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist. It will also receive this status code if the specified device does not exist or belongs to another developer.

List Data Stream Values

GET /devices/{id}/streams/{name}/values
GET /devices/{id}/streams/{name}/values.json
GET /devices/{id}/streams/{name}/values.csv
GET /devices/{id}/streams/{name}/values.msgpack
GET /devices/serial/{serial}/streams/{name}/values
GET /devices/serial/{serial}/streams/{name}/values.json
GET /devices/serial/{serial}/streams/{name}/values.csv
GET /devices/serial/{serial}/streams/{name}/values.msgpack

List values from an existing data stream associated with a specific device, sorted in reverse chronological order (most recent values first).

The response format can be specified as a file extension. In the current version of the M2X API, the supported values are json (the default), csv and msgpack.

The values can be filtered by using one or more of the following parameters:

  • start (optional) An ISO 8601 timestamp specifying the start of the date range to be considered. Any values registered before this timestamp will be simply ignored. Omit this filter to include any values registered since the stream was created.
  • end (optional) An ISO 8601 timestamp specifying the end of the date range to be considered. Any values registered after this timestamp will be simply ignored. If omitted, it defaults to the current time of the M2X server.
  • min (optional) a float value to filter values greater or equal than this value.
  • max (optional) a float value to filter values lesser or equal than this value.
  • limit (optional) Maximum number of values to return. If omitted it defaults to 1,000. The maximum value for this parameter is 10,000. If a greater number is specified, the server will only return the 10,000 most recent values on the specified date range.

Listed values are sorted by descendant timestamp by default. Sorting direction is controlled by the dir parameter, allowing the values asc (default) and desc for ascending and descending order, respectively. The sorting field can be set by passing one of the following values on the sort parameter:

  • timestamp: datapoint's timestamp
  • value: datapoint's value

Notice that both start and end must include the time part.

The start, end, min and max parameters define which values should be considered in the resulting set. If the number of values registered in the specified date range is greater than the value of the limit parameter (which defaults to 1,000 if omitted) only the n most recent values from that date range will be returned, where n is the value of the limit parameter (or 10,000, if a greater value was used).

Remember that the end parameter defaults to the current server time if omitted, so using just start and limit would return the n most recent values in the range defined from today until start.

Responses

Success

200 OK
Content-Type: application/json

{ "start": "2014-09-01T00:00:00.000Z",
  "end": "2014-09-30T23:59:59.000Z",
  "limit": 100,
  "values": [
  { "timestamp": "2014-09-09T19:15:00.563Z", "value": 32 },
  { "timestamp": "2014-09-09T20:15:00.874Z", "value": 29 },
  { "timestamp": "2014-09-09T21:15:00.325Z", "value": 30 } ] }

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist. It will also receive this status code if the specified device does not exist or belongs to another developer.

Data Stream Sampling

GET /devices/{id}/streams/{name}/sampling
GET /devices/{id}/streams/{name}/sampling.json
GET /devices/{id}/streams/{name}/sampling.csv
GET /devices/{id}/streams/{name}/sampling.msgpack
GET /devices/serial{serial}/streams/{name}/sampling
GET /devices/serial{serial}/streams/{name}/sampling.json
GET /devices/serial{serial}/streams/{name}/sampling.csv
GET /devices/serial{serial}/streams/{name}/sampling.msgpack

Sample values from an existing data stream associated with a specific device, sorted in reverse chronological order (most recent values first).

This endpoint only works for numeric streams.

The response format can be specified as a file extension. In the current version of the M2X API, the supported values are json (the default), csv and msgpack.

Two types of sampling are available, configurable by the type parameter:

  • Systematic sampling: Samples values returning every nth value recorded for the stream. The type attribute should have a value of nth.
  • Time based sampling: Returns a statistical aggregation of the stream values, grouped using time intervals. The accepted values for type are: min, max, count, avg, sum and stddev.

In both cases, the interval parameter is required: - On systematic sampling: the size of the sequence from which the first value is returned. Should be a positive integer. - On time based sampling: the interval time (in seconds) used to build the aggregation. Should be a value between 1 and 86,400

The values can be filtered by using one or more of the following parameters:

  • interval (required)
  • type (optional) Defaults to avg. Valid options are: nth, min, max, count, avg and sum.
  • start (optional) An ISO 8601 timestamp specifying the start of the date range to be considered. Any values registered before this timestamp will be simply ignored.
  • end (optional) An ISO 8601 timestamp specifying the end of the date range to be considered. Any values registered after this timestamp will be simply ignored. If omitted, it defaults to the current time of the M2X server.
  • min (optional) a float value to filter values greater or equal than this value.
  • max (optional) a float value to filter values lesser or equal than this value.
  • limit (optional) Maximum number of values to return.

Notice that both start and end must include the time part.

When using aggregated sampling, the maximum number of values returned by this endpoint will be 1,000. If the range between start and end holds more values than the limit, start will be overridden in order to return 1,000 values at most. In that case, you should consider using shorter ranges or higher intervals.

When using systematic sampling, the maximum allowed value for limit is such as limit * interval <= 1,000. Any higher value will be overridden to satisfy this equation.

Responses

Success

200 OK
Content-Type: application/json

{ "start": "2014-09-01T00:00:00.000Z",
  "end": "2014-09-05T23:59:59.000Z",
  "values": [
    { "timestamp": "2014-09-01T19:15:00.563Z", "value": 10 },
    { "timestamp": "2014-09-02T19:15:00.563Z", "value": 15 },
    { "timestamp": "2014-09-03T19:15:00.563Z", "value": 20 }
  ] }

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist or is not a numeric stream. It will also receive this status code if the specified device does not exist or belongs to another developer.

Data Stream Stats

GET /devices/{id}/streams/{name}/stats
GET /devices/serial/{serial}/streams/{name}/stats

Return count, min, max, average and standard deviation stats for the values on an existing data stream. This endpoint only works for numeric streams.

The stats can be filtered by using one or more of the following parameters:

  • start (optional) An ISO 8601 timestamp specifying the start of the date range to be considered. Any values registered before this timestamp will be simply ignored.
  • end (optional) An ISO 8601 timestamp specifying the end of the date range to be considered. Any values registered after this timestamp will be simply ignored.
  • min (optional) a float value to filter values greater or equal than this value.
  • max (optional) a float value to filter values lesser or equal than this value.

Notice that both start and end must include the time part.

The start and end parameters define which values should be considered for computing the stats. These parameters have the following defaults:

  • if both start and end aren't present, then end is the time of this stream's last value and start is that time minus one month.
  • if only start is present then end is the value of start plus one month.
  • if only end is present then start is the value of end minus one month.
  • otherwise use the selected values.

Responses

Success

200 OK
Content-Type: application/json

{ "start": "2014-09-01T00:00:00.000Z",
  "end": "2014-09-30T23:59:59.000Z",
  "stats": {
    "count": 3,
    "min": 30.0,
    "max": 50.0,
    "avg": 40.0,
    "stddev": 8.164966
  } }

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist or is not a numeric stream. It will also receive this status code if the specified device does not exist or belongs to another developer.

List Values from all Data Streams of a Device

GET /devices/{id}/values
GET /devices/{id}/values.json
GET /devices/{id}/values.csv
GET /devices/{id}/values.msgpack
GET /devices/serial/{serial}/values
GET /devices/serial/{serial}/values.json
GET /devices/serial/{serial}/values.csv
GET /devices/serial/{serial}/values.msgpack

List values from all data streams associated with a specific device, sorted in reverse chronological order (most recent values first).

The response format can be specified as a file extension. In the current version of the M2X API, the supported values are json (the default), csv and msgpack.

The values can be filtered by using one or more of the following parameters:

  • start (optional) An ISO 8601 timestamp specifying the start of the date range to be considered. Any values registered before this timestamp will be simply ignored. Omit this filter to include any values registered since the device was created.
  • end (optional) An ISO 8601 timestamp specifying the end of the date range to be considered. Any values registered after this timestamp will be simply ignored. If omitted, it defaults to the current time of the M2X server.
  • limit (optional) Maximum number of values to return. If omitted it defaults to 1,000. The maximum value for this parameter is 10,000. If a greater number is specified, the server will only return the 10,000 most recent values on the specified date range.
  • streams (optional) A comma separated string with the names of the streams to be included in the export. If omitted, the data from all streams will be included.
  • include_location (optional) This parameter can be passed to the request (set to no value, or any value other than "false") in order to additionally include location information to the exported values. If the limit parameter is specified, then it will also apply as a limit for the amount of returned waypoints.

Notice that both start and end must include the time part.

The start and end parameters define which values should be considered in the resulting set. If the number of values registered in the specified date range is greater than the value of the limit parameter (which defaults to 1,000 if omitted) only the n most recent values from that date range will be returned, where n is the value of the limit parameter (or 10,000, if a greater value was used).

Remember that the end parameter defaults to the current server time if omitted, so using just start and limit would return the n most recent values in the range defined from today until start.

Responses

Success

200 OK
Content-Type: application/json

{ "start": "2015-02-12T00:00:00.000Z",
  "end": "2015-02-12T12:00:00.000Z",
  "limit": 1000,
  "values": [
    { "timestamp": "2015-02-12T00:00:02.000Z",
      "values": {
        "temperature": 32,
        "humidity": 60,
        "logs": "Log A"
      }
    },
    { "timestamp": "2015-02-12T00:00:01.000Z",
      "values": {
        "temperature": 40,
        "humidity": 81,
        "logs": "Log B"
      }
    },
    { "timestamp": "2015-02-12T00:00:00.000Z",
      "values": {
        "temperature": 39,
        "humidity": 75,
        "logs": "Log C"
      }
    }
  ]}

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Search Values from all Data Streams of a Device

GET /devices/{id}/values/search
GET /devices/{id}/values/search.json
GET /devices/{id}/values/search.csv
GET /devices/{id}/values/search.msgpack
GET /devices/serial/{serial}/values/search
GET /devices/serial/{serial}/values/search.json
GET /devices/serial/{serial}/values/search.csv
GET /devices/serial/{serial}/values/search.msgpack

Search and list values from all data streams associated with a specific device, sorted in reverse chronological order.

The response format can be specified as a file extension. In the current version of the M2X API, the supoorted values are json (the default,) csv and msgpack.

Values can be filtered by applying conditions on multiple streams within the device, over a period of time. Given the flexibility and complexity of this kind of search, all parameters should be sent as a JSON payload, instead of via the query string, as usual.

Below is a list of the available search parameters:

  • start (required) An ISO 8601 timestamp specifying the start of the date range to be considered. Any values registered before this timestamp will be ignored.
  • end (required) An ISO 8601 timestamp specifying the end of the date range to be considered. Any values registered after this timestamp will be ignored. This timestamp must reference a point in time between start and 24 hours past start, at most.
  • streams (required) An array of Stream names. Only values from the specified streams will be returned. Both numeric and alphanumeric Stream names can be used. The names used for each stream in this type of search need to be an exact match.
  • conditions (required) An object which specifies conditions on multiple numeric streams. Below is a detailed explanation of this parameter.

Search conditions

The conditions parameter should be an object in which each key is the name of a numeric stream, and the value is itself an object that holds the desired filters for the given stream.

The conditions filters object can have multiple keys, and each one should be a valid operator, pointing to the value to be used for that particular operator.

In order to filter results via these conditions, the API first determines during which time intervals all of those conditions are met, during the time range of the search, specfied via the start and end parameters.

This is an example of what this conditions object could look like:

{
  "conditions": {
    "temperature": {
      "gt": 10,
      "lt": 20
    },
    "altitude": {
      "eq": 2500
    },
    "velocity": {
      "gte": 300
    }
  }
}

In this case in particular, the API would first determine when does it happen that the given device has a "temperature" stream with a value between 10 and 20, an "altitude" stream with a value of exactly 2500 and a "velocity" stream with a value greater than, or equal to, 300.

It would then return all the values for each stream specified in the streams list, during those times.

These conditions can only be applied to numeric streams. If an alphanumeric stream is used as part of the conditions object, the API will simply not find any results. Alphanumierc streams can be used, however, as part of the streams list to be returned.

Operators

Currently, the following operators are supported:

  • gt: filters streams that have a value greater than the one specified.
  • gte: filters streams that have a value equal to or greater than the one specified.
  • lt: filters streams that have a value lesser than the one specified.
  • lte: filters streams that have a value equal to or lesser than the one specified.
  • eq: filters streams that have a value equal to the one specified.

When using the eq operator, developers cannot specify additional filters for the same stream.

Responses

Success

200 OK
Content-Type: application/json

{ "start": "2015-02-12T00:00:00.000Z",
  "end": "2015-02-12T12:00:00.000Z",
  "limit": 1000,
  "values": [
    { "timestamp": "2015-02-12T00:00:02.000Z",
      "values": {
        "temperature": 32,
        "humidity": 60,
        "logs": "Log A"
      }
    },
    { "timestamp": "2015-02-12T00:00:01.000Z",
      "values": {
        "temperature": 40,
        "humidity": 81,
        "logs": "Log B"
      }
    },
    { "timestamp": "2015-02-12T00:00:00.000Z",
      "values": {
        "temperature": 39,
        "humidity": 75,
        "logs": "Log C"
      }
    }
  ]}

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Post Data Stream Values

POST /devices/{id}/streams/{name}/values
POST /devices/serial/{serial}/streams/{name}/values

Post timestamped values to an existing data stream associated with a specific device.

Values are passed in a values array.

Accepted attributes for each element in the array:

  • timestamp in ISO 8601 format. (required)
  • value (required)

Request

Content-Type: application/json

{ "values": [
  { "timestamp": "2014-09-09T19:15:00.624Z", "value": 32 },
  { "timestamp": "2014-09-09T20:15:00.522Z", "value": 30 },
  { "timestamp": "2014-09-09T21:15:00.522Z", "value": 15 } ] }

Responses

Success

202 Accepted

Bad Request

400 Bad Request
Content-Type: application/json

{ "message": "You must pass an array in the values field" }

A developer will receive this response if the values parameter is omitted or it is not an array of values.

400 Bad Request
Content-Type: application/json

{ "message": "Values must be objects including 'timestamp' and 'value' fields" }

A developer will receive this response if any of the included values doesn't have the required attributes.

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist. It will also receive this status code if the specified device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "values": [ "Invalid timestamp: '2014-20-20'" ] } }

A developer will receive this response if an invalid timestamp is used for any of the values posted.

Export Values from all Data Streams of a Device

GET /devices/{id}/values/export.csv
GET /devices/serial/{serial}/values/export.csv

Export all values from all or selected data streams associated with a specific device, sorted in reverse chronological order (most recent values first).

The response format can be specified as a file extension. In the current version of the M2X API, only the csv format is specified.

This operation will be executed asynchronously meaning that a developer will not get an immediate response with the results. The request will be accepted for background processing and a Job URL will be returned in which the user will be able to track the status of said job.

Once the operation is complete, the Job will be marked as complete and the URL for downloading the exported files will be available in the result field of the Job. (See Jobs API for more information about jobs). The results file will be available for one week, after which time it will be deleted.

The resulting export can be customized by using one or more of the following parameters:

  • limit (optional) Maximum number of values to return. If omitted it will return all of the existing values on the device and the selected streams.
  • streams (optional) A comma separated string with the names of the streams to be included in the export. If omitted, the data from all streams will be included.
  • include_location (optional) This parameter can be passed to the request (set to no value, or any value other than "false") in order to additionally include location information to the exported values. If the limit parameter is specified, then it will also apply as a limit for the amount of returned waypoints.

Responses

Success

202 Accepted
Location: https://api-m2x.att.com/v2/jobs/20150789ab77eaffd7e16b4bb09bf746b5ba0a

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "temperature": ["not_valid"] } }

A developer will receive this response when one or more of the specified stream does not belong to the device.

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Delete Data Stream Values

DELETE /devices/{id}/streams/{name}/values
DELETE /devices/serial/{serial}/streams/{name}/values

Delete values in a stream by a date range. Deletion will take place asynchronously. The following parameters are required:

  • from timestamp in ISO 8601 format.
  • end timestamp in ISO 8601 format.

Request

Content-Type: application/json

{ "from": "2014-09-09T19:15:00.624Z",
  "end": "2014-09-09T20:15:00.522Z" }

Responses

Success

202 Accepted

Bad Request

400 Bad Request
Content-Type: application/json

{ "message": "Invalid range" }

A developer will receive this response if from is not less than or equal to end timestamp.

400 Bad Request
Content-Type: application/json

{ "message": "Invalid start/end timestamp" }

A developer will receive this response if from or end are invalid ISO8601 timestamps.

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist. It will also receive this status code if the specified device does not exist or belongs to another developer.

Delete Data Stream

DELETE /devices/{id}/streams/{name}
DELETE /devices/serial/{serial}/streams/{name}

Delete an existing data stream associated with a specific device.

Responses

Success

204 No Content

Device/Stream Not Found

404 Not Found
Content-Type: application/json

{ "message": "Stream 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 data stream does not exist. It will also receive this status code if the specified device does not exist or belongs to another developer.

Post Device Update (Single Values to Multiple Streams)

POST /devices/{id}/update
POST /devices/serial/{serial}/update

Posts single values to multiple streams at once.

The values attribute contains an object with one attribute per each stream to be updated. The value of each one of these attributes the value to be recorder in the stream.

The timestamp is an optional parameter, which accepts a timestamp in ISO 8601 format. If not supplied the server's time will be used.

The optional location attribute can contain location information that will be used to update the current location of the specified device.

Request

Content-Type: application/json

{ "timestamp": "2014-09-09T19:15:00.981Z",
  "values": {
    "temperature": 32,
    "humidity": 88
  }
}

Responses

Success

202 Accepted

Bad Request

400 Bad Request
Content-Type: application/json

{ "message": "You must pass a values field containing the values for each stream" }

A developer will receive this response if the values parameter is omitted or it does not follow the expected format.

400 Bad Request
Content-Type: application/json

{ "message": "Invalid iso8601 value for `timestamp': 2015-07-16 10:03:07 -0300" }

A developer will receive this response if the supplied timestamp isn't a valid ISO8601 string.

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": {
    "temp": "Stream not found",
    "humidity": "invalid_value"
  } }

A developer will receive this response if an invalid value format is used (i.e. string in numeric streams) or if the stream wasn't found in the device.

Post Device Updates (Multiple Values to Multiple Streams)

POST /devices/{id}/updates
POST /devices/serial/{serial}/updates

Post values to multiple streams at once.

The values attribute contains an object with one attribute per each stream to be updated. The value of each one of these attributes is an array of timestamped values.

Accepted attributes for each element in the array:

  • timestamp timestamp in ISO 8601 format. (required)
  • value a numeric or string value. (required)

The optional location attribute can contain location information that will be used to update the current location of the specified device.

Request

Content-Type: application/json

{ "values": {
    "temperature": [
      { "timestamp": "2014-09-09T19:15:00.981Z", "value": 32 },
      { "timestamp": "2014-09-09T20:15:00.124Z", "value": 30 },
      { "timestamp": "2014-09-09T21:15:00.124Z", "value": 15 } ],
    "humidity": [
      { "timestamp": "2014-09-09T19:15:00.874Z", "value": 88 },
      { "timestamp": "2014-09-09T20:15:00.752Z", "value": 60 },
      { "timestamp": "2014-09-09T21:15:00.752Z", "value": 75 } ]
  }
}

Responses

Success

202 Accepted

Bad Request

400 Bad Request
Content-Type: application/json

{ "message": "You must pass a values field containing the values for each stream" }

A developer will receive this response if the values parameter is omitted or it does not follow the expected format.

400 Bad Request
Content-Type: application/json

{ "message": "Values must be objects including 'timestamp' and 'value' fields" }

A developer will receive this response if any of the included values doesn't have the required attributes.

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "values": [ "Invalid timestamp: '2014-20-20'", "Stream not found: 'humidity'" ] } }

A developer will receive this response if an invalid timestamp is used for any of the values posted, or if the value sent is not a numeric value or a string.

View Request Log

GET /devices/{id}/log
GET /devices/serial/{serial}/log

Retrieve list of HTTP requests received lately by the specified device (up to 100 entries).

Responses

Success

200 OK
Content-Type: application/json

{ "requests": [
  { "timestamp": "2014-09-09T19:15:00.131Z", "status": 200, "method": "GET", "path": "/devices/123" },
  { "timestamp": "2014-09-09T19:14:32.574Z", "status": 202, "method": "PUT", "path": "/devices/123/streams/temperature" },
  { "timestamp": "2014-09-09T19:12:30.753Z", "status": 200, "method": "GET", "path": "/devices/123" },
  { "timestamp": "2014-09-09T19:11:01.630Z", "status": 204, "method": "PUT", "path": "/devices/123" } ] }

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 device does not exist or belongs to another developer.

Delete Device

DELETE /devices/{id}
DELETE /devices/serial/{serial}

Delete an existing device.

This method requires that a master API key is specified in the X-M2X-KEY header.

Responses

Success

204 No Content

Inactive Account

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

Device Not Found

404 Not Found
Content-Type: application/json

{ "message": "Device 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 Device does not exist or belongs to another developer.