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 Params 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 Params 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 Params 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 Params 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 Params 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 Params 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 Params 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 Params 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.