Developer Hub

Welcome to the EVRYTHNG Developer Hub! Here you will find all the information you need to create your EVRYTHNG apps and integrations. We have conceptual guides, walkthroughs, and tutorials as well as a complete API reference.

Featured Pages

Most API endpoints support filtering to retrieve or edit only a subset of resources that match a certain criteria, such as:

  • Filtering actions by Thng ID.
  • Filtering Thngs by product ID.
  • Find products that are named 'x'.
  • Find places tagged 'ACME Inc'.

Note

Please note that any update or delete operations using filters are limited to 500 resources. If more than 500 resources match the specified filter, an error will be returned and no resource will be modified.

To modify a large number of resources, paginate them and carry out the desired operation on each page of items. This can be achieved using the SDKs.

Explicit ID-based Filtering

Many API endpoints allows to explicitly send the IDs of certain resources that should be returned. This is particularly useful when one wants to edit in bulk a set of resources (e.g. update the name of a few Thngs). To explicitly select a few Thngs, one should use the ?ids=X, where X is a list of (existing) URL-encoded comma-separated resource IDs. For example, if one wants to update the name of multiple products by id one could use the following request:

PUT /products?ids=:productId1,:productId2,:productId3
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ProductDocument (subset)
curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://api.evrythng.com/products?ids%3DU2E9hmyCVg8atpRwwXgTqcrt%2CUFEsATFh63PhhqwaRhEdeAek%2CUFcMeG6e5gwhWGSsE4gccKfk' \
  -d '{
    "name": "Updated name"
  }'
const productUpdate = {
  name: "Updated name"
};

user.product().update(productUpdate, {
  params: {
    ids: 'U2E9hmyCVg8atpRwwXgTqcrt,UFEsATFh63PhhqwaRhEdeAek,UFcMeG6e5gwhWGSsE4gccKfk'
  }
}).then(console.log);
Iterator<PVector<Thng>> iterator = apiManager.thngService().iterator()
    .filter("name=Original name").execute();

Note

The filter query string must be URL-encoded.

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

[
  {
    "id": "U2E9hmyCVg8atpRwwXgTqcrt",
    "name": "Updated name",
    ...
  }, {
    "id": "UFEsATFh63PhhqwaRhEdeAek",
    "name": "Updated name",
    ...
  }, {
    "id": "UFcMeG6e5gwhWGSsE4gccKfk",
    "name": "Updated name",
    ...
  }
]

Query-based Filtering

Filters are used to retrieve or bulk edit multiple resources that match a particular filter. You can therefore append ?filter=X to the endpoint URL when doing a GET, PUT, or DELETE operation (where X is a query). Note that the ?filter is mutually exclusive with ?ids where a list of existing resource IDs must be given.

Note

Filters that include multiple conditions (e.g: name=test&tags=device) are evaluated from left to right, so name is matched, then the resulting results are filtered for tags.

Query Structure

Our queries are of the form X AND Y AND Z only, and we do not support the OR operator. Other operators supported are:

Operator
Description
Encoded Format

&

And

%26

,

Lists

%2C

..

Ranges (inclusive)

..

*

Ending wildcard (starts with)

*

=

Equal

%3D

<

Less

%3C

<=

Less or equal

%3C%3D

>

Greater

%3E

>=

Greater or equal

%3E%3D

!

Not. Inverts another filter clause. For example, to find resources without the 'test' tag:

filter=!tags=test

!

Simple Field Filtering Examples

You can search for any field of a given Thng or product.

Most API endpoints support the ?filter=X query parameter that allows to limit the results returned by a query to only the resources that match a certain criteria set (defined by the query X). See the following examples:

  • /thngs?filter=name%3Dtv
    Find all Thngs named tv

  • /products?filter=name%3Dmilk%2Cegg
    Find all products named milk OR egg

  • /thngs?filter=name%3Dsensor*
    Find all Thngs whose name start with sensor

  • /thngs?filter=tags%3DUK
    Find all Thngs that contain the tag UK

  • /thngs?filter=tags%3DUK%2Cshipped
    Find all Thngs that contain the tags UK OR shipped

  • /thngs?filter=tags%3DUK%26tags%3Dshipped
    Find all Thngs that contain the tag UK AND shipped

  • /actions/all?filter=timestamp%3E1477323564350
    Find all actions created after 1477323564350 (timestamp is larger than 1477323564350)

  • /actions/all?filter=timestamp%3D1477323564350..1478871333924
    Find all actions by timestamp created after 1477323564350 and before 1478871333924 (inclusive).


Available Fields

Depending on the resource being filtered, a discrete set of filter fields are available. These are described for each resource in the table below, and alongside the document models for each in the API Reference section.

Resource
Available Fields

Account

name

Action

timestamp, identifiers.<key>, tags, type, user, context.city, context.countryCode, thng, product, collection.

ActionType

name

Application

name, project

Application User

email, firstName, lastName

Batch

createdAt, identifiers.<key>, name, tags

Collection

collections, identifiers.<key>, name, tags

File

name, tags

Location

timestamp

LogEntry

app, logLevel, timestamp

Place

name, identifiers.<key>, tags

Product

name, identifiers.<key>, tags

Project

identifiers.<key>, name, tags

Property

timestamp

Task

batch, status, type

Thng

collections, createdAt, identifiers.<key>, name, product, tags

Filtering in evrythng.js

Filtering in evrythng.js works the same way as parameters, with some additional helpers:

// Simple string - same as the REST API
user.product().read({
  params: {
    filter: 'name=Actuator,Sensor&tags=shipped'
  }
}).then(console.log);

// Object notation
user.product().read({
  params: {
    filter: {
      name: 'Actuator,Sensor',
      tags: 'shipped'
    }
  }
}).then(console.log);