Collections API

Collections allow a user to organize Devices into nested groups. Each Device can belong to multiple Collections. The Collections API makes it easy to manage Collections and to organize Devices into Collections. Additionally, you can access all Devices contained within a Collection via the Device API using a Collection API Key.

Authentication

All methods described in this page require that a Master API Key is specified in the X-M2X-KEY header. Any attempt of using a Device or Collection level API key would result in a 403 Forbidden response.

All collections have a primary Collection Key associated to them, and more can be created via the Keys API. Information on API Keys and the difference between key types can be found in the API Keys Overview documentation.

It's important to emphasize that Collection Keys grant access to all the devices included in the collection, or any of its sub-collections, so developers need to be aware of that when adding or removing sub-collections, and sharing their keys with other users.

List collections

GET /collections

Retrieve a list of collections accessible by the authenticated account. The list can be further filtered using the following parameter:

  • parent The ID of a collection owned by the authenticated account. Only its sub-collections will be returned. If the parent parameter is present but it's set to an empty value, only top level collections will be returned. (optional)

  • name The name of the collection owned by the user. Can be a partial match. (Optional)

  • tags A comma-separated list of tag names of the collection owned by the user. Only collections matching all the tags will be returned. (Optional)

Responses

Success

200 OK
Content-Type: application/json

{ "collections": [
  { "id": "1b3ba972fcf92a156fc8c0ca1554434c",
    "parent": null,
    "name": "My devices",
    "description": null,
    "devices": 10,
    "collections": 5,
    "tags": [],
    "metadata": {},
    "key": "78981e4daf83c38cab03d83d513db7be",
    "created": "2014-10-09T17:09:43.443Z",
    "updated": "2014-10-09T17:09:43.443Z" } ] }

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 Collection

POST /collections

Create a new collection. Accepts the following parameters:

  • name The name of the new collection (required).
  • description A longer description of the collection (optional).
  • parent The ID of the collection where this one will be included (optional).
  • tags a comma separated list of tag names (optional).
  • metadata an object containing custom metadata fields and values (optional).

Request

Content-Type: application/json

{ "name": "My devices" }

Responses

Success

201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/collections/1b3ba972fcf92a156fc8c0ca1554434c

{ "id": "1b3ba972fcf92a156fc8c0ca1554434c",
  "url": "https://api-m2x.att.com/v2/collections/1b3ba972fcf92a156fc8c0ca1554434c",
  "parent": null,
  "name": "My devices",
  "description": null,
  "devices": 0,
  "collections": 0,
  "tags": ["ipsum", "lorem"],
  "metadata": {},
  "key": "78981e4daf83c38cab03d83d513db7be",
  "created": "2014-10-09T17:09:43.443Z",
  "updated": "2014-10-09T17:09:43.443Z" }

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 parent, when present, must belong to a valid collection owned by the developer (not_valid).
  • The tags parameter must be a comma separated list of tags (not_valid).
  • The metadata parameter must be an object containing valid metadata (see Update Collection Metadata).

View Collection Details

GET /collections/{id}

Retrieve information about an existing collection.

Responses

Success

200 OK
Content-Type: application/json

{ "id": "1b3ba972fcf92a156fc8c0ca1554434c",
  "parent": null,
  "name": "Sample device collection",
  "description": "Longer description for this collection",
  "devices": 10,
  "collections": 5,
  "tags": [],
  "metadata": {
    "color": "blue",
    "owner": "John Doe"
  },
  "key": "78981e4daf83c38cab03d83d513db7be",
  "created": "2014-10-09T17:09:43.526Z",
  "updated": "2014-10-09T17:09:43.526Z" }

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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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." }

Developers will receive this response when the specified collection does not exist or belongs to another developer.

Update Collection Details

PUT /collections/{id}

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

  • name The name of the new collection (required).
  • description A longer description of the collection (optional).
  • parent The ID of the collection where this one will be included, or null to remove the collection from its parent (optional).
  • tags a comma separated list of device tag names (optional).
  • metadata an object containing custom metadata fields and values (optional).

Request

Content-Type: application/json

{ "name": "Sample Collection",
  "description": "Longer description for this collection" }

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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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." }

Developers will receive this response when the specified collection 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 parent, when present, must belong to a valid collection owned by the developer (not_valid).
  • Additionally, the parent cannot reference a collection that is already included in the current collection (not_valid).
  • The tags parameter must be a comma separated list of tags (not_valid).
  • The metadata parameter must be an object containing valid metadata (see Update Collection Metadata).

List Devices from an existing Collection

GET /collections/{id}/devices

Retrieve a list of devices assigned to the specified collection. By default, only devices at the root level will be returned. Developers can use the following param to change this default:

  • include_children When this parameter is present and set to true or 1, all devices within the collection will be returned. Not only the ones directly assigned to the collection but also the ones assigned to its sub-collections as well.

The list 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: The device's creation date; this is the default.
  • last_activity: The device's last recorded activity.
  • name: The device's name.

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.

In order to search for devices within a collection using more filters and parameters, please refer to the device serch API endpoint.

Responses

Success

200 OK
Content-Type: application/json

{ "devices": [
  {
    "id": "b1e8abbad65cb52b0d75eb2e63efa782",
    "name": "Sensor",
    "description": "Description",
    "visibility": "private",
    "serial": "ABC11111",
    "status": "enabled",
    "tags": ["ipsum", "lorem"],
    "url": "https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782",
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782/streams",
      "count": 1,
      "values": {
        "temperature": 72
      }
    },
    "key": "78981e4daf83c38cab03d83d513db7be",
    "created": "2014-10-21T23:13:03.965Z",
    "updated": "2014-10-21T23:13:03.965Z"
  },
  {
    "id": "e38f93669c88151e76f1c587edd9ef74",
    "name": "Sensor",
    "description": "Description",
    "visibility": "private",
    "serial": "ABC11112",
    "status": "enabled",
    "tags": [],
    "url": "https://api-m2x.att.com/v2/devices/e38f93669c88151e76f1c587edd9ef74",
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/e38f93669c88151e76f1c587edd9ef74/streams",
      "count": 0,
      "values": {}
    },
    "key": "8a2567003b282f494ddfc7ee64dcb327",
    "created": "2014-10-21T23:13:22.225Z",
    "updated": "2014-10-21T23:13:22.225Z"
  },
  {
    "id": "b1d1a0b9df316531241d0fd48b5c8fe6",
    "name": "Sensor",
    "description": "Description",
    "visibility": "private",
    "serial": "ABC12345",
    "status": "enabled",
    "tags": [],
    "url": "https://api-m2x.att.com/v2/devices/b1d1a0b9df316531241d0fd48b5c8fe6",
    "streams": {
      "url": "https://api-m2x.att.com/v2/devices/b1d1a0b9df316531241d0fd48b5c8fe6/streams",
      "count": 0,
      "values": {}
    },
    "key": "43fc778532e092b93e3d8a871164297c",
    "created": "2014-10-21T23:06:46.001Z",
    "updated": "2014-10-21T23:06:46.001Z"
  } ],
  "total": 900,
  "pages": 300,
  "limit": 3,
  "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" }

Collection Not Found

404 Not Found
Content-Type: application/json

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

Add device to collection

PUT /collections/{id}/devices/{device_id}

Add the given device to the collection. If the device already belongs to the collection, it will not be added twice.

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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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." }

Developers will receive this response when the specified collection does not exist or belongs to another developer.

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

Remove device from collection

DELETE /collections/{id}/devices/{device_id}

Removes the given device from the collection, if it is included within it.

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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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." }

Developers will receive this response when the specified collection does not exist or belongs to another developer.

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 Collection Metadata

GET /collections/{id}/metadata

Get custom metadata of an existing Collection.

Responses

Success

200 OK
Content-Type: application/json

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

Collection Not Found

404 Not Found
Content-Type: application/json

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

Update Collection Metadata

PUT /collections/{id}/metadata

Update the custom metadata of the specified Collection. Collection metadata can store arbitrary string values at custom field names. Each time the collection 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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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 collection 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 Collection Metadata Field

GET /collections/{id}/metadata/{field}

Get the value of a single custom metadata field from an existing Collection. 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" }

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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 collection 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 Collection.

Update Collection Metadata Field

PUT /collections/{id}/metadata/{field}

Update the custom metadata of the specified Collection. Collection 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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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 collection 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).

Delete Collection

DELETE /collections/{id}

Delete an existing collection along with all of its children collections. The devices included in the collection will, however, remain intact.

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

Collection Not Found

404 Not Found
Content-Type: application/json

{ "message": "Collection 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." }

Developers will receive this response when the specified collection does not exist or belongs to another developer.