Thing Groups API

The Thing Groups REST API is used to manage thing groups.

CREATE

Required role: ReadWrite
Required privilege: ThingGroups.CREATE on the specified domain
Required privilege: ThingGroups.READ on the specified domain

Creates a new thing group.

A group may be a child group of another group, if so, they have to share the same domain.

API Endpoint: [POST]: /thing-groups

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Body

• domain: The id of the domain that the thing group should belong to. required
• description: A description of the thing group. required
• parent: The id of another group. optional

Example body

{
    "domain": "root",
    "description": "My group",
    "parent": "another-thing-group-id"
}

Response

• id: The id of the thing group.
• description: The description.
• domain: The domain.
• createdAt: A UNIX timestamp indicating the moment of creation.
• parent: The id of the parent group, if applicable. optional

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
NOT_AUTHORIZED_DOMAIN		domain	Returned if the domain does not exist.
THING_GROUP_NOT_FOUND		parent	Returned if the parent group does not exist.

UPDATE

Required role: ReadWrite
Required privilege: ThingGroups.UPDATE on the domain of the specified Thing Group
Required privilege: ThingGroups.READ on the domain of the specified Thing Group

Update a thing group.

API Endpoint: [PATCH]: /thing-groups/{id}

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Path

• id: The id of the thing group. required

Body

• description: A description of the thing group. required

Example body

{
    "description": "My updated description"
}

Response

• id: The id of the thing group.
• description: The description.
• domain: The domain.
• createdAt: A UNIX timestamp indicating the moment of creation.
• parent: The id of the parent group, if applicable. optional

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
THING_GROUP_NOT_FOUND		id	Returned if the thing group does not exist.

DELETE

Required role: ReadWrite
Required privilege: ThingGroups.DELETE on the domain of the specified Thing Group
Required privilege: ThingGroups.READ on the domain of the specified Thing Group

Delete a thing group.

API Endpoint: [DELETE]: /thing-groups/{id}

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Path

• id: The id of the thing group. required

Response

The response is an empty object ({}).

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
THING_GROUP_NOT_FOUND		id	Returned if the thing group does not exist.
THING_GROUP_HAS_THINGS		id	Returned if the thing group has things.
THING_GROUP_HAS_CHILD_GROUPS		id	Returned if the thing group has child groups.

LIST

Required role: Read
Required privilege: ThingGroups.READ

Get all thing groups.

Note: This operation is eventually consistent. In other words, changes to the thing group might not be reflected immediately.

API Endpoint: [GET]: /thing-groups?parent={parent}

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Query

• parent: The id of a thing group. If set, the results are filtered to only contain groups with this parent. optional

Response

• groups[]:
  • id: The id of the thing group.
  • description: The description.
  • domain: The domain.
  • createdAt: A UNIX timestamp indicating the moment of creation.
  • parent: The id of the parent group, if applicable. optional

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.

DESCRIBE

Required role: Read
Required privilege: ThingGroups.READ on the domain of the specified Thing Group

Get a thing group.

API Endpoint: [GET]: /thing-groups/{id}

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Path

• id: The id of the thing group. required

Response

• id: The id of the thing group.
• description: The description.
• domain: The domain.
• createdAt: A UNIX timestamp indicating the moment of creation.
• parent: The id of the parent group, if applicable. optional

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
THING_GROUP_NOT_FOUND		id	Returned if the thing group does not exist.

ADD_THINGS

Required role: ReadWrite
Required privilege: ThingGroups.UPDATE on the domain of the specified Thing Group
Required privilege: ThingGroups.READ on the domain of the specified Thing Group
Required privilege: Things.UPDATE on the domain of each of the specified Things

Add thing(s) to a thing group.

API Endpoint: [POST]: /thing-groups/{id}/things

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Path

• id: The id of the thing group. required

Body

• thingNames[]: A list of thingNames that will be added. required

Example body

{
    "thingNames": ["my-thing-id", "another-thing-id"]
}

Response

The response is an empty object ({}).

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
THING_GROUP_NOT_FOUND		id	Returned if the thing group does not exist.
THING_GROUP_HAS_THING		thingNames	Returned if the thing group already contains a provided thing.
THING_NOT_FOUND		thingNames	Returned if a provided thing does not exist.

REMOVE_THING

Required role: ReadWrite
Required privilege: ThingGroups.UPDATE on the domain of the specified Thing Group
Required privilege: ThingGroups.READ on the domain of the specified Thing Group
Required privilege: Things.UPDATE on the domain of the specified Thing

Remove a thing from a group.

API Endpoint: [DELETE]: /thing-groups/{id}/things/{thingName}

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Path

• id: The id of the thing group. required
• thingName: The name of the thing to remove. required

Response

The response is an empty object ({}).

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
THING_GROUP_NOT_FOUND		id	Returned if the thing group does not exist.
THING_NOT_FOUND		thingName	Returned if the provided thing does not exist.

LIST_THINGS

Required role: Read
Required privilege: ThingGroups.READ on the domain of the specified Thing Group

The things in a thing group.

Note: This operation is eventually consistent. In other words, changes to the thing group might not be reflected immediately.

API Endpoint: [GET]: /thing-groups/{id}/things

Request

Headers

• Authorization: The Authorization token returned from /auth/login
• x-api-key: The API Key to identify the request

Path

• id: The id of the thing group. required

Response

• things[]: A list of thing names

Errors

Key	Params	Property	Description
NOT_AUTHORIZED			Returned if the user is not authorized for the operation.
PROPERTY_REQUIRED			Returned if a required parameter is missing.
INVALID_ARGUMENTS			Returned if a parameter does not fulfil requirements.
THING_GROUP_NOT_FOUND		id	Returned if the thing group does not exist.