Thing Management API

The Thing Management API is used to manage things and thing certificates.

CREATE

Required role: ReadWrite
Required privilege: Things.CREATE on the specified domain

Creates a new thing and a corresponding thing certificate.

API Endpoint: [POST]: /things

Request

Headers

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

Body

thingName: The ID to give the new thing.
- The thing name is the part of the MQTT-topic used to interact with the thing ($aws/things/<thingName>/shadow/update and thing-update/<domainTopic>/<thingName>), and as such it needs to comply with all rules of the AWS IoT platform. This is also the reason why this field is not named id.
- If no thingName is provided, the system generates a sequential ID left-padded with zeros to be at least 8 characters long.
- Once a thingName is set, it cannot be changed.
- If possible, we recommend using Thing Label and having the system auto-generate the thingName
thingType: The ID of the thing type that the thing should belong to. required
domain: The ID of the domain that the thing should belong to. required
externalId: Unique identifier of your device, useful if you need to update the unique identifier at a later time
simulated: A boolean indicating if the thing is for simulation or not. Can not be true for a networked thing.
parentThingName: If you are using networked things with multiple device shadows, specify the parent thing name in order to create networked things. You can not use a simulated thing as parent. If this parameter is set, the request parameters must adhere to the following rules:
protocol: The protocol type (mqtt | iotgw)
imei: IMEI (only relevant for the iotgw protocol)
imsi: IMSI (only relevant for the iotgw protocol)
- thingName is required
- thingName cannot be empty
- thingName cannot include __ or -
- parentThingName cannot include __

Example payload

{
  "thingName": "mything",
  "thingType": "1",
  "domain": "root",
  "externalId": "123456",
  "parentThingName": "myparentthing"
}

Response

thingName: The ID of the created thing.
thingType: The ID of the thing type that the created thing belongs to.
domain: The ID of the domain that the created thing belongs to.
label: A label describing the created thing. At creation time the label is the same as thingName but it can be updated later to something more descriptive.
createdAt: The time when the thing was created.
createdBy: The user name of the user that created the thing.
externalId: Unique identifier of your device.
simulated: A boolean indicating if the thing is for simulation or not.

Errors

Key	Property	Description
`NOT_AUTHORIZED_DOMAIN`	`domain`	Returned if the user tries to create a thing on a domain that the user is not authorized to to see.
`PROPERTY_REQUIRED`	`thingType`	Returned if no thing type was provided.
`PROPERTY_REQUIRED`	`domain`	Returned if no domain was provided.
`INVALID_ARGUMENTS`		Returned if the attributes aren’t allowed. For allowed attributes, see documentation above
`INVALID_ARGUMENTS`	`thingType`	Returned if the thing type ID does not fulfil the thing type ID pattern requirements
`THING_EXISTS`	`externalId, thingName`	Returned if a thing with that externalId or thingName already exists
`THING_TYPE_NOT_FOUND`	`thingType`	Returned if the thing type does not exist

Life cycle events

Creating a thing will trigger a life cycle event with the type THING.CREATE.

GET

Required role: Read
Required privilege: Things.READ on the domain of the Thing

Gets information about a thing.

API Endpoint: [GET]: things/

Request

Headers

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

Query Parameters

thingName: The ID of the thing to get required
- You must include either thingName or externalId
- If you include both, thingName is ignored
externalId: The external ID of the thing to get required
- You must include either thingName or externalId
- If you include both, thingName is ignored
attributes: A comma-separated list of attributes to return. If not specified, all attributes are returned. The list may contain the following values:
- thingType, domain, label, description, createdAt, createdBy, shadow, domainTopic, parentThingName, hasNetworkedThings, simulated

The domainTopic is used in combination with the Thing Update API to know which topic to subscribe to. So if you want to subscribe to all updates related to the thing you should subscribe to thing-update/<domainTopic>/<thingName>.

Response

thingName: The ID of the requested thing.
thingType: The ID of the thing type that the requested thing belongs to. optional
domain: The domain that the requested thing belongs to. optional
- id: The ID of the domain.
- name: The name of the domain.
- description: A longer description of the domain.
- data: Custom data about the domain (see the Domain API for more information).
label: A label describing the requested thing. optional
description: A longer description of the requested thing. optional
createdAt: The time when the requested thing was created. optional
createdBy: The user name of the user who created the requested thing. optional
simulated: A boolean indicating if the thing is for simulation or not. optional
shadow: The device shadow of the requested thing. optional

The content of the shadow is the entire shadow document from the IoT registry, so it includes state, metadata, timestamp and version. For more information, see the AWS Documentation.
domainTopic: The domain topic of the requested thing. optional
externalId: The externalId of the requested thing.

Errors

Key	Property	Description
`DOMAIN_NOT_FOUND`		Returned if the user requested that the domain should be included in the response but the domain cannot be found.
`NOT_AUTHORIZED_DOMAIN`		Returned if the user tries to get a thing that belongs to a domain that the user is not authorized to see.
`PROPERTY_REQUIRED`	`thingName`	Returned if no thing name was provided.
`THING_NOT_FOUND`	`thingName`	Returned if the thing cannot be found.

UPDATE

Required role: ReadWrite
Required privilege: Things.UPDATE on the domain of the Thing
Optional privilege: Things.CREATE on the specified domain, if moving the Thing to a new domain

Updates one or more of the attributes of a thing.

API Endpoint: [PATCH]: /things/{thingName}

Request

Headers

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

Path Parameters

thingName: The name of the thing. required

Body

domain: The ID of the new domain that the thing should belong to.
label: A label describing the thing.
description: A longer description of the thing.
externalId: Unique identifier of your device.
protocol: The protocol type (mqtt | iotgw). If not set, then defaults to mqtt. optional
imei: IMEI (only relevant for the iotgw protocol)
imsi: IMSI (only relevant for the iotgw protocol)
moveNetworkedThings: Determines if potential networked things should be moved to the same domain as the updated thing. Defaults to true. (true | false)

Example payload

This payload would require the optional privileges Things.UPDATE on the current domain of the Thing and Things.CREATE on targetDomain (the domain specified in the request).

{
  "domain": "targetDomain",
  "label": "My test thing",
  "description": "A description of my test thing.",
  "externalId": "Unique identifier of your device"
}

Response

thingName: The ID of the updated thing.
thingType: The ID of the thing type that the updated thing belongs to.
domain: The ID of the domain that the updated thing belongs to.
label: A label describing the updated thing.
description: A longer description of the updated thing.
createdAt: The time when the updated thing was created. optional
createdBy: The user name of the user who created the updated thing. optional
externalId: Unique identifier of your device.
simulated: A boolean indicating if the thing is for simulation or not.
protocol: The protocol type optional
imei: IMEI (only relevant for the iotgw protocol)optional
imsi: IMSI (only relevant for the iotgw protocol)optional

Errors

Key	Property	Description
`NOT_AUTHORIZED_DOMAIN`		Returned if the user tries to update a thing that belongs to a domain that the user is not authorized to see.
`NOT_AUTHORIZED_DOMAIN`	`domain`	Returned if the user tries to move a thing to a domain that the user is not authorized to see.
`PROPERTY_REQUIRED`	`thingName`	Returned if no thing name was provided.
`THING_NOT_FOUND`		Returned if the thing cannot be found.
`INVALID_ARGUMENTS`		Returned if the attributes aren’t allowed. For allowed attributes, see documentation above
`THING_EXISTS`	`externalId`	Returned if a thing with that externalId already exists
`INTERNAL_SERVER_ERROR`		Thing update failed, due to third party issues

Life cycle events

Updating a thing will trigger a life cycle event with the type THING.UPDATE.

REMOVE

Required role: ReadWrite
Required privilege: Things.DELETE on the domain of the Thing

Removes a thing, its corresponding thing certificate, its networked things and all nested resources connected to the thing.

API Endpoint: [DELETE]: /things/{thingName}

Request

Headers

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

Query Parameters

thingName: The ID of the thing to remove, set in query path. required
purgeObservations: Determines if the indexed observations should be deleted or not. Defaults to false. (true | false) optional
- Warning: This action is not reversible.

Indexed observations created by the thing are retained by default, unless purgeObservations=true are set in query parameters.

Stored observations are always retained and can only be removed by setting a retention policy.

If an existing scheduled Data Export Job exists that references the deleted Thing, that existing job will continue to function as normal.

Any new Data Export Job created at the Thing Type level will include the data of the deleted Thing.

Response

This action doesn’t have any response.

Errors

Key	Property	Description
`NOT_AUTHORIZED_DOMAIN`		Returned if the user tries to remove a thing that belongs to a domain that the user is not authorized to see.
`PROPERTY_REQUIRED`	`thingName`	Returned if no thing name was provided.
`THING_NOT_FOUND`		Returned if the thing cannot be found.
`THING_REFERENCED_BY_RULE`		Returned if the thing is referenced by a rule.

Life cycle events

Removing a thing will trigger a life cycle event with the type THING.REMOVE.

DOWNLOAD_CERTIFICATE

Required role: ReadWrite
Required privilege: Things.CREATE on the domain of the Thing

Downloads a certificate for a thing. You can not download a certificate for a simulated thing.

API Endpoint: [POST]: /things/certificate

Request

Headers

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

Body

thingName: The ID of the thing to download the certificate for. required
- You must include either thingName or externalId
- If you include both, thingName is ignored
externalId: The externalId of the thing to download the certificate for. required
- You must include either thingName or externalId
- If you include both, thingName is ignored

Example payload

{
  "thingName": "mything"
}

Response

A zip-file, base64 encoded, sent as a JSON string.

The zip-file contains the certificate for the thing. The file contains the following parts:

cert.pem: The X.509 certificate.
privkey.pem: The private key for the certificate.
pubkey.pem: The public key for the certificate.

The certificate is signed using a CA certificate that can be downloaded here.

Errors

Key	Property	Description
`NOT_AUTHORIZED_DOMAIN`	`domain`	Returned if the user tries to download a certificate for a thing that belongs to a domain that the user is not authorized to see.
`PROPERTY_REQUIRED`	`thingName` or `externalId`	Returned if no thing name or external ID was provided.
`THING_NOT_FOUND`	`thingName` or `externalId`	Returned if the thing cannot be found.

REPLACE_CERTIFICATE

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

Revokes the current certificate of a thing and generates a new certificate.

API Endpoint: [PUT]: /things/certificate

Request

Headers

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

Body

thingName: The ID of the thing to replace the certificate for. required
- You must include either thingName or externalId
- If you include both, thingName is ignored
externalId: The externalId of the thing to replace the certificate for. required
- You must include either thingName or externalId
- If you include both, thingName is ignored

Example payload

{
  "thingName": "mything"
}

Response

Empty json object: {}

Errors

Key	Property	Description
`NOT_AUTHORIZED_DOMAIN`		Returned if the user tries to replace the certificate of a thing that belongs to a domain that the user is not authorized to see.
`PROPERTY_REQUIRED`	`thingName` or `externalId`	Returned if no thing name was provided.
`THING_NOT_FOUND`		Returned if the thing cannot be found.

SET_RESOURCES

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

Set a new value for one or more resources on a thing.

API Endpoint: [PUT]: /things/resources

Request

Headers

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

Body

thingName: The name of the thing. required
- You must include either thingName or externalId
- If you include both, thingName is ignored
externalId: The externalId of the thing. required
- You must include either thingName or externalId
- If you include both, thingName is ignored
thingType: The thing type of the thing. required
resources[]:
- name: The resource name. required
- value: The resource value to set. required
- subThingType: The sub thing type, if it is a sub thing resource. optional
- subThingName: The sub thing name, if it is a sub thing resource. optional Required if subThingType is provided.
- virtual: Set to true if the resource is virtual optional

Example payload

{
  "thingType": "mythingtype",
  "thingName": "mythingname",
  "resources": [
    {
      "name": "myresourcename",
      "value": 10
    }
  ]
}

Response

This action doesn’t have any response.

Errors

Key	Property	Description
`NOT_AUTHORIZED`		Returned if the user is not authorized.
`PROPERTY_REQUIRED`		Returned if a required property was not present.
`INVALID_ARGUMENTS`		Returned if a provided property is forbidden.
`INVALID_ARGUMENTS`	`name`	Returned if a resource was specified twice in the `resources` payload.
`INVALID_ARGUMENTS`	`resources`	Returned if `resources` was not an array.
`THING_TYPE_NOT_FOUND`	`id`	Returned if the provided thing type was not found.

FIND

Required role: Read
Required privilege: Things.READ on one or more domains containing a Thing

Executes an Elasticsearch query to find things and/or subthings.

API Endpoint: [POST]: /things/find

Request

Headers

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

Body

query: The query to run on Elasticsearch specified using Elasticsearch Query DSL. required
Any query and any aggregations are permitted to use, but since Managed IoT Cloud prevents the user from seeing events on domains that the user is not authorized to see, the query must satisfy the following requirements:
- The query cannot contain global aggregations.
type: The type of thing to search for can be thing (default), sub_thing or both thing,sub_thing. optional
sort: The thing attribute to sort by. optional

Most thing attributes can be used for sorting. However, the label attribute is a special case where you should use the label.lowercase field instead:
```
  query: {"match_all": {}},
  sort: [ {"label.lowercase": "asc"}]
```

Filter context

Consider using a filter context if possible. In filter context, a query clause answers the question “Does this document match this query clause?” The answer is a simple Yes or No — no scores are calculated. Filter context is mostly used for filtering structured data, e.g.

Does this timestamp fall into the range 2015 to 2016?
Is the status field set to “published”?

Example payload

{
  "query": {
    "size": 1000,
    "query": {
      "bool": {
        "filter": {
          "term": {
            "thingType": "1"
          }
        }
      }
    }
  },
  "type": "thing,sub_thing"
}

Example payload with filters and only specific fields returned

{
  "query": {
    "size": 1000,
    "query": {
      "bool": {
        "must": [
          {
            "range": {
              "state.tcxn.connection_status": {
                "gt": 1
              }
            }
          },
          {
            "regexp": {
              "thingName": "0000...."
            }
          }
        ],
        "filter": {
          "term": {
            "thingType": "2"
          }
        }
      }
    },
    "_source": [
      "timestamp",
      "thingName",
      "state.tcxn.connection_status"
    ]
  }
}

Response

The output from the Elasticsearch query.

Errors

Key	Property	Description
`INVALID_ARGUMENTS`	`query`	Returned if the query includes a global aggregations.
`INVALID_ARGUMENTS`	`type`	Returned if the type is not one of the allowed types.
`PROPERTY_REQUIRED`	`query`	Returned if no query was provided.