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.