Collections

A collection resource allows you to group a set of Thngs under some common grouping criteria. For example, a collection can be used to represent a production batch of some product, where the Thngs in the collection are the individual manufactured items from that batch. This can make it easier for Application Users to manage all the Thngs they created while using an application. This works by assigning a reference to the collection to each Thng, and listing the Thngs that reside in each collection. Collections can be added as children to other collections (such as a pallet within a container), and so on.

Collections have a similar data model to other resources in the Platform (a name and description, tags, and customFields etc.) and are created in a similar manner. Once a collection has been created, users can add or remove Thngs to or from that collection. See below for examples.

In addition to specifying a collection in an action, it is also possible to create an action through the collection itself using aliased actions.

API Status General Availability: /collections /collections/:collectionId /collections/:collectionId/thngs /collections/:collectionId/collections /collections/:collectionId/collections/:childCollectionId

CollectionDocument Data Model

See also: ScopesDocument

Filterable Fields

This resource type can be filtered using the following fields and operators.

__

Create a Collection

Create a new collection.

Read All Collections

Read all available collections. The result may be paginated if there are more than 30 items.

Update a Collection

Update a collection's fields with new data. Nested fields such as tags are replaced entirely with the value in the payload. The response payload is the complete updated collection document.

❗Note

There is a limit of 10,000 Thngs updated per API call on collections. If your collection contains more than 10,000 elements you should consider an iterative solution.

Delete a Collection

Delete a single collection by ID.

❗Note

If the collection contains more than 500 Thngs, these will need to be removed from the collection (but not deleted themselves) before the collection may be deleted itself.

Read All Thngs in a Collection

Get the list of all the thngs in a collection can be retrieved via a GET on the /thngs resource of a collection. The result may be paginated if there are more than 30 items.

Read a Collection

Read a single collection by its ID.

Add Thngs to a Collection

Thngs can be added to a collection by PUTing an array with their respective thngIds to the /thngs.

❗Note

The maximum number of Thngs that can be added to a collection is 10,000 per request.

You can also add Thngs to collections as they are created, by including an array of IDs of collections the Thng should be added to in the creation request:

Remove a Thng from a Collection

Thngs can be removed from within a collection, by sending a DELETE to their ID within the :collectionID/thngs sub-resource of a collection.

❗Note

There is a limit of 500 Thngs deleted per API call on collections. If your collection contains more than 500 elements you should consider an iterative solution.

Remove All Thngs from a Collection

All Thngs within a collection can be removed by sending a DELETE to the /thngs resource of a collection.

Read All Collections in a Collection

The list of all the collections in a collection can be retrieved via a GET on the /collections sub-resource of a collection. The result may be paginated if there are more than 30 items.

Add Collections to a Collection

Child collections can be added to a collection by POSTing an array with their respective IDs to the /collections endpoint.

Remove a Collection from a Collection

Collections can be removed from within a collection, by sending a DELETE to their ID within the :collectionId/collections sub-resource of a collection.

Remove all Collections from a Collection

All collections within a collection can be removed by sending a DELETE to the /collections resource of a collection.