Thngs (legacy)

A Thng is the central data structure in the EVRYTHNG Platform. Thngs are extensible data containers designed to model physical objects such as packaged consumer products, electronic devices, or other saleable goods that are manufactured in large quantities, etc. Thngs have various basic fields including name, description, tags, etc. More dynamic data can be stored in the properties, and specialised use-case specific data in customFields, or identifiers fields as required.

Thngs can be the target of actions describing events that happen to them, or they can be added to collections to express logical groupings, such as a box of individual items, as a unit. In addition to specifying a Thng in an action, it is also possible to create an action through the Thng itself using aliased actions.

API Status
General Availability:
/auth/evrythng/thngs
/thngs
/thngs/:thngId
/thngs/:thngIdentifier
/thngs/:thngId/actions/:actionType
/thngs/:thngId/location
/thngs/:thngId/properties

Jump To ↓

ThngDocument Data Model
Create a Thng
Read a Thng
Read all Thngs
Update a Thng
Update Multiple Thngs
Delete a Thng
Thng Location
Create a Thng's Redirection
Read a Thng's Redirection
Update a Thng's Redirection
Delete a Thng's Redirection
Thngs as Devices
Create Device API Key
Read Device API Key
Delete Device API Key
Using Evrythng.js in a Device

ThngDocument Data Model

.name (string, required)
    Friendly name of this resource.

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.activatedAt (integer, read-only)
    Timestamp when the Thng was activated.

.type (string)
    Type of this resource. Can be unset with an empty string.

.tags (array of string)
    Array of string tags associated with this resource.

.description (string)
    Friendly description of this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

.product (string)
    The Platform ID of a product this Thng is a class of.

.location (LocationDocument)
    An object representing a location. Either 'position' or 
    'place' us required.

.properties (object, read-only)
    A JSON object with key-value pairs describing properties of 
    the Thng.

.collections (array of string)
    An array of collection IDs of any collections this Thng 
    belongs to.

.createdByTask (string, read-only)
    The ID of this resource.

.batch (string, read-only)
    The ID of this resource.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object representing a Thng.",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "activatedAt": {
      "type": "integer",
      "description": "Timestamp when the Thng was activated.",
      "readOnly": true
    },
    "type": {
      "type": "string",
      "description": "Type of this resource. Can be unset with an empty string.",
      "maxLength": 256
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "product": {
      "type": "string",
      "description": "The Platform ID of a product this Thng is a class of.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "location": {
      "additionalProperties": false,
      "type": "object",
      "description": "An object representing a location. Either 'position' or 'place' us required.",
      "properties": {
        "position": {
          "type": "object",
          "description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
          "required": ["type", "coordinates"],
          "properties": {
            "type": {
              "type": "string",
              "description": "The type of the point.",
              "enum": ["Point"]
            },
            "coordinates": {
              "type": "array",
              "description": "The point coordinates",
              "items": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              }
            }
          }
        },
        "createdAt": {
          "type": "integer",
          "description": "Timestamp when the resource was created.",
          "readOnly": true,
          "minimum": 0
        },
        "timestamp": {
          "type": "integer",
          "description": "The time the location update occurred, or filled automatically by the Platform if omitted.",
          "readOnly": true
        },
        "longitude": {
          "type": "number",
          "description": "The longitude."
        },
        "latitude": {
          "type": "number",
          "description": "The latitude."
        },
        "place": {
          "type": "string",
          "description": "The place ID.",
          "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
        },
        "scopes": {
          "additionalProperties": false,
          "type": "object",
          "description": "Project and user scopes arrays.",
          "required": ["users", "projects"],
          "properties": {
            "users": {
              "type": "array",
              "description": "An array of Application User IDs this resource is scoped to.",
              "items": { "type": "string" }
            },
            "projects": {
              "type": "array",
              "description": "An array of project IDs this resource is scoped to.",
              "items": {
                "type": "string",
                "description": "The ID of this resource.",
                "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
                "readOnly": true
              }
            }
          }
        }
      },
      "x-filterable-fields": ["timestamp"]
    },
    "properties": {
      "type": "object",
      "description": "A JSON object with key-value pairs describing properties of the Thng.",
      "readOnly": true
    },
    "collections": {
      "description": "An array of collection IDs of any collections this Thng belongs to.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
      }
    },
    "createdByTask": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "batch": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    }
  },
  "x-filterable-fields": ["collections", "createdAt", "identifiers.<key>", "name", "product", "tags"]
}

{
  "id": "UnRPNbfD6GsYh6wawhBMNdDe",
  "createdAt": 1510920534153,
  "tags": [
    "example",
    "thng"
  ],
  "updatedAt": 1510920534153,
  "name": "Soft Blue T-Shirt",
  "description": "Single manufactured Soft Blue T-Shirt for sale.",
  "type": "tagged",
  "product": "UHR8MGsSCct4t9wwRgEKqrUr",
  "identifiers": {
    "gs1:21": "4834838943"
  }
}

Filterable Fields

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

Field	Type	Operators
`collections`	List of string	`=`
`createdAt`	Number	`<`, `>`
`identifiers.<key>`	String	`=`
`name`	String	`=`
`product`	String	`=`
`tags`	List of string	`=`

Create a Thng

Create a new Thng. It is recommended to link all Thngs to a product upon creation by specifying the product's ID in the product field.

POST /thngs
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ThngDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST "https://api.evrythng.com/thngs" \
  -d '{
    "tags": [
      "example",
      "thng"
    ],
    "name": "Soft Blue T-Shirt",
    "description": "Single manufactured Soft Blue T-Shirt for sale.",
    "product": "UHR8MGsSCct4t9wwRgEKqrUr",
    "identifiers": {
      "gs1:21": "4834838943"
    }
  }'

const payload = {
  tags: [
    'example',
    'thng'
  ],
  name: 'Soft Blue T-Shirt',
  description: 'Single manufactured Soft Blue T-Shirt for sale.',
  product: 'UHR8MGsSCct4t9wwRgEKqrUr',
  identifiers: {
    'gs1:21': '4834838943'
  }
};

user.thng().create(payload)
  .then(console.log);

Thng thng = new Thng();
thng.setName("Box of cereals");
thng.setDescription("A simple box of cereals");
apiManager.thngService().thngCreator(thng).execute();

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.evrythng.com/thngs/UNaE5DWVFKgsmwaww3y7Hakk

{
  "id": "UNaE5DWVFKgsmwaww3y7Hakk",
  "createdAt": 1560786516270,
  "tags": [
    "example",
    "thng"
  ],
  "updatedAt": 1560786516270,
  "name": "Soft Blue T-Shirt",
  "description": "Single manufactured Soft Blue T-Shirt for sale.",
  "product": "UHR8MGsSCct4t9wwRgEKqrUr",
  "identifiers": {
    "gs1:21": "4834838943"
  }
}

Read a Thng

Thng data is read using a GET request on the Thng URL including the thngId.

GET /thngs/:thngId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET "https://api.evrythng.com/thngs/U2wm8b42MVNxTCX6MYDrRpyd"

const thngId = 'U2wm8b42MVNxTCX6MYDrRpyd';

user.thng(thngId).read()
  .then(console.log);

String thngId = "U2wm8b42MVNxTCX6MYDrRpyd";

Thng thng = apiManager.thngService().thngReader(thngId).execute();

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UNaE5DWVFKgsmwaww3y7Hakk",
  "createdAt": 1560786516270,
  "tags": [
    "example",
    "thng"
  ],
  "updatedAt": 1560786516270,
  "name": "Soft Blue T-Shirt",
  "description": "Single manufactured Soft Blue T-Shirt for sale.",
  "product": "UHR8MGsSCct4t9wwRgEKqrUr",
  "identifiers": {
    "gs1:21": "4834838943"
  }
}

Read all Thngs

Read all available Thngs in scope of the authenticating API key. The result may be paginated if there are more than 30 items.

GET /thngs
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/thngs'

user.thng().read()
  .then(console.log);

Iterator<PVector<Thng>> thngs = apiManager.thngService().iterator().perPage(10).execute();

while (thngs.hasNext()) {
    PVector<Thng> page = thngs.next();
    for (Thng thng : page) {
        System.out.println("Thng: " + thng.toString());
    } 
}

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UNaE5DWVFKgsmwaww3y7Hakk",
    "createdAt": 1560786516270,
    "tags": [
      "example",
      "thng"
    ],
    "updatedAt": 1560786516270,
    "name": "Soft Blue T-Shirt",
    "description": "Single manufactured Soft Blue T-Shirt for sale.",
    "product": "UHR8MGsSCct4t9wwRgEKqrUr",
    "identifiers": {
      "gs1:21": "4834838943"
    }
  }
]

Update a Thng

Update a single Thng by ID.

📘
Note
Only the basic fields (name, description, product, identifiers, tags, and customFields) can be updated in this manner.
Properties, location and collections must be updated via their respective /thngs/:thngId/location, /thngs/:thngId/properties and /collections/:collectionId/thngs endpoints.

PUT /thngs/:thngId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ThngDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/thngs/UkYVKThN36Cfe4xACatserPs' \
  -d '{
    "tags": ["updated"]
  }'

const thngId = 'UkYVKThN36Cfe4xACatserPs';
const payload = { tags: ['updated'] };

user.thng(thngId).update(payload)
  .then(console.log);

// thng from previous thngService reader invocation
thng.setDescription("Updated Thng description");

apiManager.thngService().thngUpdater(thng.getId(), thng).execute();

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UNaE5DWVFKgsmwaww3y7Hakk",
  "createdAt": 1560786516270,
  "tags": [
    "updated"
  ],
  "updatedAt": 1560786516270,
  "name": "Soft Blue T-Shirt",
  "description": "Single manufactured Soft Blue T-Shirt for sale.",
  "product": "UHR8MGsSCct4t9wwRgEKqrUr",
  "identifiers": {
    "gs1:21": "4834838943"
  }
}

Update Multiple Thngs

Using a suitable filter, it is possible to apply (PUT) an updated ThngDocument to multiple Thngs, providing they match the filter query parameter. For example, all Thngs that begin with "Smart" to contain the 'smart' tag.

PUT /thngs?filter=name%3DSmart*
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ThngDocument (subset)

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/thngs?filter=name%3DSmart*' \
  -d '{
    "tags": [ "smart" ]
  }'

const update = { tags: ["updated"] };
const params = { filter: 'name=Test*' };

operator.thng().update(update, { params })
  .then(console.log);

The update will be applied asynchronously, and the response will be 204 'No Content'.

HTTP/1.1 204 No Content

Delete a Thng

Delete a single Thng by ID. This action cannot be undone.

DELETE /thngs/:thngId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://api.evrythng.com/thngs/UF6qwDbaVDPwQKRwagmnqyqs'

const thngId = 'UF6qwDbaVDPwQKRwagmnqyqs';

operator.thng(thngId).delete()
  .then(() => console.log('Deleted!'));

String thngId = "UF6qwDbaVDPwQKRwagmnqyqs";

apiManager.thngService().thngDeleter(thngId).execute();

HTTP/1.1 200 OK

Thng Location

As Thngs model real-world resources, they have a special property called a location to keep track of the actual position over time. See the Locations section for more information.

Create a Thng's Redirection

Use the appropriate short domain API to create a Thng redirection. This example uses tn.gg.

POST https://<short domain>/redirections
Content-Type: application/json
Authorization: $OPERATOR_API_KEY
Accept: application/json

RedirectionDocument

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://tn.gg/redirections' \
  -d '{
    "type": "thng",
    "evrythngId": "Uk6qwgSReXPat5awagfNpHsk",
    "defaultRedirectUrl": "https://google.com/{thngId}"
  }'

const thngId = 'Uk6qwgSReXPat5awagfNpHsk';

// 'type' and 'evrythngId' are handled by the SDK
const payload = { defaultRedirectUrl: 'https://example.com/{thngId}' };

operator.thng(thngId).redirection('tn.gg')
  .update(payload)
  .then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json

{
  "createdAt": 1496668317836,
  "updatedAt": 1496668348257,
  "defaultRedirectUrl": "https://google.com/Uk6qwgSReXPat5awagfNpHsk",
  "evrythngUrl": "https://api.evrythng.com/thngs/Uk6qwgSReXPat5awagfNpHsk",
  "shortDomain": "tn.gg",
  "shortId": "799yeEi4qp",
  "hits": 0
}

Read a Thng's Redirection

Use the appropriate short domain redirection API to read a Thng redirection.

GET https://<short domain>/redirections?evrythngId=:thngID
Authorization: $OPERATOR_API_KEY
Accept: application/json

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://tn.gg/redirections?evrythngId=Uk6qwgSReXPat5awagfNpHsk'

const thngId = 'Uk6qwgSReXPat5awagfNpHsk';

operator.thng(thngId).redirection('tn.gg')
  .read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "createdAt": 1496664729327,
  "updatedAt": 1496664729327,
  "defaultRedirectUrl": "https://google.com",
  "evrythngUrl": "https://api.evrythng.com/thngs/Uk6qwgSReXPat5awagfNpHsk",
  "shortDomain": "tn.gg",
  "shortId": "39aZNy4g",
  "hits": 0
}

Update a Thng's Redirection

Use the appropriate short domain redirection API and short ID to update a Thng redirection.

PUT https://<short domain>/redirections/:shortId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

RedirectionDocument

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://tn.gg/redirections/3kdh38sa' \
  -d '{
    "defaultRedirectUrl": "https://google.com/{thngId}"
  }'

const thngId = 'Uk6qwgSReXPat5awagfNpHsk';
const payload = { defaultRedirectUrl: 'https://example.com/{thngId}' };

operator.thng(thngId).redirection('tn.gg')
  .update(payload)
  .then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json

{
  "createdAt": 1496668317836,
  "updatedAt": 1496668348257,
  "defaultRedirectUrl": "https://google.com/Uk6qwgSReXPat5awagfNpHsk",
  "evrythngUrl": "https://api.evrythng.com/thngs/Uk6qwgSReXPat5awagfNpHsk",
  "shortDomain": "tn.gg",
  "shortId": "799yeEi4qp",
  "hits": 0
}

Delete a Thng's Redirection

DELETE https://<short domain>/redirections/:shortId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://tn.gg/redirections/s87dfhs2'

const thngId = 'Uk6qwgSReXPat5awagfNpHsk';

operator.thng(thngId).redirection('tn.gg')
  .delete();

HTTP/1.1 200 OK
Content-Type: application/json

Thngs as Devices

In the connected devices world, devices can be autonomous and behave as sensors and/or actuators, communicating directly with the EVRYTHNG platform as an actor. A Thng can be registered as a device by creating a Device API key, with which the device can manage the details of its corresponding Thng in the EVRYTHNG platform.

Create Device API Key

Creates an API Key for a given Thng (Device API key), which is useful when an embedded device needs to talk to its Thng in the Platform (update its properties, subscribe to actions, etc.).

A Device API key can only be created by Application Users or Operators. If called multiple times for the same Thng, the existing API key will be returned (a new one will not be generated). If you want to create a new API key for a Thng, you must delete the existing one first (see below).

POST /auth/evrythng/thngs
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

{
  "thngId": "UBPWKPA3qqtyrPe7QQm9hrrf"
}

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://api.evrythng.com/auth/evrythng/thngs' \
  -d '{ 
    "thngId": "UBPWKPA3qqtyrPe7QQm9hrrf" 
  }'

const thngId = 'UBPWKPA3qqtyrPe7QQm9hrrf';

evrythng.api({
  url: '/auth/evrythng/thngs',
  method: 'POST',
  apiKey,
  data: { thngId },
}).then(console.log);

HTTP/1.1 201 OK
Content-Type: application/json

{
  "thngId": "UBPWKPA3qqtyrPe7QQm9hrrf",
  "thngApiKey": "PEjcPTFS8Cr4CZenEg312234ialp1CiM7weR5Q..."
}

🚧
Note
Device API Keys are currently created on a per-project basis. This means that a Device API Key created with a Thng with no project scope will not be available if the Thng is later moved to a different project scope. Similarly, if a Thng already in a given project is scoped to other projects, new Device API Keys will need to be created for each new project.
In the future, Device API Keys will inherit the scope of the Thng they represent. When this change occurs this page will be updated.

Read Device API Key

Can be done by Application Users or Operators that have access rights to the Thng.

GET /auth/evrythng/thngs/:thngId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://api.evrythng.com/auth/evrythng/thngs/UBPWKPA3qqtyrPe7QQm9hrrf'

const thngId = 'UBPWKPA3qqtyrPe7QQm9hrrf';

evrythng.api({
  url: `/auth/evrythng/thngs/${thngId}`,
  apiKey,
}).then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "thngId": "UBPWKPA3qqtyrPe7QQm9hrrf",
  "thngApiKey": "PEjcPTFS8CrCZenEg1234ialpodqSCiM7weR5Q..."
}

Delete Device API Key

This revokes access for a given Device API key. Can be done by Application Users or Operator that have access rights to the Thng.

DELETE /auth/evrythng/thngs/:thngId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://api.evrythng.com/auth/evrythng/thngs/UBPWKPA3qqtyrPe7QQm9hrrf'

const thngId = 'UBPWKPA3qqtyrPe7QQm9hrrf';

evrythng.api({
  url: `/auth/evrythng/thngs/${thngId}`,
  method: 'DELETE',
  apiKey,
}).then(() => console.log('Deleted!'));

HTTP/1.1 200 OK

Using Evrythng.js in a Device

To make it easier for Javascript developers to write embedded device applications, we created the Device scope. Remember that conceptually a device is a Thng. Therefore the Device scope has direct access to everything related to the Thng (actions, properties, locations) - see API Key Scopes and Permissions for more information.

Example: evrythng.js

const device = new evrythng.Device({ apiKey });

const payload = {
  customFields: { foo: 'bar' },
};

device.update(payload).then(console.log);

// create
const payload = [
  { key: 'temperature', value: 30 },
];
device.property().create(payload)
  .then(console.log);

// read
device.property('temperature').read()
  .then(console.log);

// update
device.property('temperature').update(52);
device.property('status').update(true);

// bulk update
const payload = { temperature: 52, status: true };
device.property().update(payload);

const payload = [
  { value: 52, timestamp: 1430228888000 },
  { value: 70, timestamp: 1430228900000 },
];
device.property('temperature').update(payload);

See Properties for more examples on using the property resource.

// create
const payload = { type 'scans' };
device.action('scans').create(payload)
  .then(console.log);

// read
device.action('all').read()
  .then(console.log);

See Actions for more examples on using the /actions resource.