EVRYTHNG Developer Hub

Welcome! Here's where you'll find what you need to start working with EVRYTHNG as quickly as possible. There are comprehensive guides, documentation, and support if you get stuck. We encourage you to dive in and explore.

Create Free Account Read Documentation Get Support

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

  • Can I filter the actions by Thng?
  • How do I filter the Thngs by product?
  • I want to see the products that are named 'x'?
  • How about 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.

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.

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

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

JobLogEntry

jobId, type

Location

timestamp

LogEntry

app, logLevel, timestamp

Place

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);

Filters