Documentation Powered by ReDoc

Sensorbucket API (1.2.0-rc1)

Download OpenAPI specification:Download

Tim van Osch: info@pollex.nl URL: https://sensorbucket.nl License: EUPLv1.2

SensorBucket processes data from different sources and devices into a single standardized format. An applications connected to SensorBucket, can use all devices SensorBucket supports.

Missing a device or source? SensorBucket is designed to be scalable and extendable. Create your own worker that receives data from an AMQP source, process said data and output in the expected worker output format.

Find out more at: https://developer.sensorbucket.nl/

Developed and designed by Provincie Zeeland and Pollex'

Authentication

CookieSession

When a user is logged in a session cookie will be set which authenticates the user.

Security Scheme Type API Key
Cookie parameter name: SID

APIKey

An API Key given through the Authorization header will authenticate an organisation

Security Scheme Type HTTP
HTTP Authorization Scheme Bearer

Devices

List devices

Fetch a list of devices.

Devices can be filtered on three items: properties, distance from a location or a bounding box.

  • Filtering on properties filters devices on whether their property attribute is a superset of the given JSON object value
  • Distance from location filtering requires a latitude, longitude and distance (in meters). All devices within that range will be returned
  • Bounding box requires a North,East,South and West point. All devices within that box will be returned.

The filters distance from location and bounding box are mutually exclusive. The location distance filter will take precedence.

Authorizations:
CookieSessionAPIKey
query Parameters
properties
string
Example: properties={ "eui": "1122334455667788" }

Used to filter devices by its properties. This filters devices on whether their property contains the provided value. The value must be a JSON string and depending on your client should be URL Escaped

north
number <double>
Example: north=3.6175560329103202

Used to filter devices within a bounding box

west
number <double>
Example: west=51.518796779610035

Used to filter devices within a bounding box

east
number <double>
Example: east=51.47912508218688

Used to filter devices within a bounding box

south
number <double>
Example: south=3.655955445579366

Used to filter devices within a bounding box

latitude
number <double>
Example: latitude=51.496227862014685

Used to filter devices within a distance from a point

longitude
number <double>
Example: longitude=3.615071953647924

Used to filter devices within a distance from a point

distance
integer
Example: distance=1000

Used to filter devices within a distance from a point. The distance is given in meters.

cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

id
Array of integers <int64>

Filter by Device IDs

sensor_group
Array of integers <int64>

Filter by device group

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Create device

Create a new device.

Depending on the type of device and the network it is registered on. The device might need specific properties to be set.
For example: A LoRaWAN device often requires a dev_eui property to be set. The system will match incoming traffic against that property.

Authorizations:
CookieSessionAPIKey
Request Body schema: application/json
code
required
string
description
string
latitude
number <double>
longitude
number <double>
location_description
string
properties
object

Responses

Request samples

Content type
application/json
{
  • "code": "mfm1000",
  • "description": "Grasfield pipe 24",
  • "latitude": 1.2345,
  • "longitude": 1.2345,
  • "location_description": "Description of location",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "message": "created device",
  • "data": {
    }
}

Get device

Get the device with the given identifier.

The returned device will also include the full model of the sensors attached to that device.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer <int64>

The numeric ID of the device

Responses

Response samples

Content type
application/json
{
  • "message": "Fetched device",
  • "data": {
    }
}

Update device properties

Update a some properties of the device with the given identifier.

The request body should contain one or more modifiable properties of the Device.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer <int64>

The numeric ID of the device

Request Body schema: application/json
description
integer
latitude
number <double>
longitude
number <double>
location_description
string
properties
object

Responses

Request samples

Content type
application/json
{
  • "description": 1,
  • "latitude": 1.2345,
  • "longitude": 1.2345,
  • "location_description": "Description of location",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Updated device properties"
}

List sensors device

List all sensors related to the device with the provided identifier

Authorizations:
CookieSessionAPIKey
path Parameters
device_id
required
integer

The identifier of the device

query Parameters
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Create sensor for device

Create a new sensor for the device with the given identifier.

A device can not have sensors with either a duplicate code or duplicate external_id field. As this would result in conflicts while matching incoming messages to devices and sensors.

Authorizations:
CookieSessionAPIKey
path Parameters
device_id
required
integer

The identifier of the device

Request Body schema: application/json
code
required
string
description
string
external_id
required
string
brand
string
properties
object
archive_time
integer

Responses

Request samples

Content type
application/json
{
  • "code": "S123",
  • "description": "Pressure sensor at 5 meters depth",
  • "external_id": "5",
  • "brand": "sensor brand ABC",
  • "properties": {
    },
  • "archive_time": 7
}

Response samples

Content type
application/json
{
  • "message": "Created new sensor for device"
}

Delete sensor

Delete a sensor from the system.

Since a sensor can only be related to one and only one device at a time, the sensor will be deleted from the system completely

Authorizations:
CookieSessionAPIKey
path Parameters
device_id
required
integer

The identifier of the device

sensor_code
required
string

The code of the sensor

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted sensor from device"
}

List sensors

List all sensors.

Authorizations:
CookieSessionAPIKey
query Parameters
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

List sensor groups

Fetch a list of sensor groups.

Authorizations:
CookieSessionAPIKey
query Parameters
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Create sensor group

Create a new sensor group.

Authorizations:
CookieSessionAPIKey
Request Body schema: application/json
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "message": "created sensor group",
  • "data": {
    }
}

Get sensor group

Get the sensor group with the given identifier.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer <int64>

The numeric ID of the sensor group

Responses

Response samples

Content type
application/json
{
  • "message": "Fetched sensor group",
  • "data": {
    }
}

Update sensor group

Update a some properties of the sensor group with the given identifier.

The request body should contain one or more modifiable properties of the sensor group.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer

The numeric ID of the sensor group

Request Body schema: application/json
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "message": "Updated Sensor Group properties"
}

Delete sensor group

Delete a sensor group

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer

The id of the sensor group

Responses

Response samples

Content type
application/json
{
  • "message": "sensor group deleted"
}

Add sensor to a sensor group

Add a sensor by its ID to a sensor group by its ID

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer

The identifier of the Sensor Group

Request Body schema: application/json
sensor_id
integer

id of the sensor to add

Responses

Request samples

Content type
application/json
{
  • "sensor_id": 5
}

Response samples

Content type
application/json
{
  • "message": "Added sensor to sensor group"
}

Delete sensor from sensor group

Delete a sensor from a sensor group

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
integer

The identifier of the sensor group

sensor_id
required
integer

The id of the sensor

Responses

Response samples

Content type
application/json
{
  • "message": "Deleted sensor from sensor group"
}

Pipelines

List pipelines

List pipelines. By default only state=active pipelines are returned. By providing the query parameter inactive only the inactive pipelines will be returned.

Pipelines can be filtered by providing one or more steps. This query parameter can be repeated to include more steps. When multiple steps are given, pipelines containing one of the given steps will be returned.

Authorizations:
CookieSessionAPIKey
query Parameters
inactive
boolean

Only show inactive pipelines

step
Array of strings
Example: step=thethingsnetwork&step=multiflexmeter

Only show pipelines that include at least one of these steps

cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Create pipeline

Create a new pipeline.

A pipeline determines which workers, in which order the incoming data will be processed by.

A pipeline step is used as routing key in the Message Queue. This might be changed in future releases.

Note: currently there are no validations in place on whether a worker for the provided step actually exists.

Authorizations:
CookieSessionAPIKey
Request Body schema: application/json
description
string
steps
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "Pipeline for Multiflexmeter Groundwater devices",
  • "steps": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Created pipeline",
  • "data": {
    }
}

Get pipeline

Get the pipeline with the given identifier.

This endpoint by default returns a 404 Not Found for inactive pipelines. To get an inactive pipeline, provide the status=inactive query parameter.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the pipeline

query Parameters
status
Array of strings
Example: status=active&status=inactive

The status of the pipeline. Use inactive to view inactive pipelines instead of getting a 404 error

Responses

Response samples

Content type
application/json
{
  • "message": "Fetched pipeline",
  • "data": {
    }
}

Update pipeline

Update some properties of the pipeline with the given identifier.

Setting an invalid state or making an invalid state transition will result in an error.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the pipeline

Request Body schema: application/json
description
string
steps
Array of strings
status
string

Used to change a pipeline from inactive to active or vice-versa. Moving from active to inactive can also be achieve by DELETEing the pipeline resource.

Responses

Request samples

Content type
application/json
{
  • "description": "Pipeline for Multiflexmeter Groundwater devices",
  • "steps": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "message": "Updated pipeline",
  • "data": {
    }
}

Disable pipeline

Disables a pipeline by setting its status to inactive.

Inactive pipelines will - by default - not appear in the ListPipelines and GetPipeline endpoints, unless the status=inactive query parameter is given on that endpoint.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the pipeline

Responses

Response samples

Content type
application/json
{
  • "message": "Disabled pipeline"
}

Measurements

Query measurements

Query a list of measurements.

This endpoint is used to get all measurements that correspond with the given filters.

It is commonly required to get a single stream of measurements from a single sensor. This can be accomplished by finding the corresponding datastream ID and using that in the datastream filter.

Most query parameters can be repeated to get an OR combination of filters. For example, providing the datastream parameter twice will return measurements for either datastreams.

Authorizations:
CookieSessionAPIKey
query Parameters
start
required
string <date-time>
Example: start=2022-01-01T00:00:00Z
end
required
string <date-time>
Example: end=2022-12-31T23:59:59Z
device_id
string
datastream
string
sensor_code
string
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

List all datastreams

List all datastreams.

A sensor can produce one or more timeseries of measurements. Such a unique timeserie is called a datastream.

For example: A Particulate Matter sensor might return count the number of particles smaller than 2.5 μg/cm2, 5 μg/cm2 and 10 μg/cm2. this is one sensor producing three datastreams.

Another example would be a worker which processes raw incoming values into meaningful data. An underwater pressure sensor might supply its measurement in milli Amperes, but the worker converts it to watercolumn in meters. The sensor now has two datastreams. Presusre in millivolt and watercolumn in meters.

Authorizations:
CookieSessionAPIKey
query Parameters
sensor
Array of integers <int64>

only return datastreams that are produced by the given sensor identifier

cursor
string

The cursor for the current page

limit
integer <int64>

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Get datastream

Get the datastream with the given identifier.

The returned datastream will also include the full model of the sensors attached to that datastream.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the datastream

Responses

Response samples

Content type
application/json
{
  • "message": "Fetched datastream",
  • "data": {
    }
}

Process uplink message

Push an uplink message to the HTTP Importer for processing.

The request body and content-type can be anything the workers (defined by the pipeline steps) in the pipeline expect.

As this process is asynchronuous, any processing error will not be returned in the response. Only if the HTTP Importer is unable to push the message to the Message Queue, will an error be returned.

Authorizations:
CookieSessionAPIKey
path Parameters
pipeline_id
required
string <uuid>
Example: c4d4fabd-9109-40cd-88b0-be40ca1745f7

The UUID of the pipeline

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Tracing

List traces

Lists traces that match the provided filter.

Authorizations:
CookieSessionAPIKey
query Parameters
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

tracing_id
Array of strings <uuid>
Example: tracing_id=a59d28c8-2a0f-4e89-9f49-6942f1c04342
device_id
integer <int64>
Example: device_id=5
status
integer
Example: status=2
duration_greater_than
integer
Example: duration_greater_than=5
duration_smaller_than
integer
Example: duration_smaller_than=10

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

List ingresses

Lists ingresses that match the provided filter.

Authorizations:
CookieSessionAPIKey
query Parameters
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Tenants

Retrieves tenants

Lists Tenants

Authorizations:
CookieSessionAPIKey
query Parameters
name
integer <int64>

Filter on specific name of a tenant

state
integer <int64>
Example: state=1

Filter on soecific state of a tenant

is_member
boolean

Only show tenants that this user is a member of

cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Add a User to a Tenant as member

Adds a user with the specific ID to the given Tenant as a member with the given permissions

Authorizations:
CookieSessionAPIKey
path Parameters
tenant_id
required
integer

The identifier of the tenant

Request Body schema: application/json
user_id
required
string
permissions
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "User added to Tenant"
}

Removes a member from a tenant

Removes a member by the given user id from a tenant

Authorizations:
CookieSessionAPIKey
path Parameters
tenant_id
required
integer <int64>

The identifier of the tenant

user_id
required
string

The identifier of the user

Responses

Response samples

Content type
application/json
{
  • "message": "Member removed from tenant"
}

Update a tenant member's permissions

Update a tenant member's permissions

Authorizations:
CookieSessionAPIKey
path Parameters
tenant_id
required
integer <int64>

The identifier of the tenant

user_id
required
string

The identifier of the user

Request Body schema: application/json
permissions
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Member removed from tenant"
}

Workers

List workers

Lists traces that match the provided filter.

Authorizations:
CookieSessionAPIKey
query Parameters
cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

id
Array of strings

Filter by Pipeline IDs

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Create Worker

Create a new worker

Authorizations:
CookieSessionAPIKey
Request Body schema: application/json
name
required
string
description
string
user_code
required
string <base64>

base64 encoded user code

state
string
Enum: "enabled" "disabled"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "user_code": "string",
  • "state": "enabled"
}

Response samples

Content type
application/json
{
  • "message": "created user worker",
  • "data": {
    }
}

Get worker

Get the worker with the given identifier.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the worker

Responses

Response samples

Content type
application/json
{
  • "message": "Fetched worker",
  • "data": {
    }
}

Update worker properties

Update a some properties of the worker with the given identifier.

The request body should contain one or more modifiable properties of the Worker.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the worker

Request Body schema: application/json
name
string
description
string
state
string
Enum: "enabled" "disabled"
user_code
string <base64>

base64 encoded user code

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "state": "enabled",
  • "user_code": "string"
}

Response samples

Content type
application/json
{
  • "message": "Updated worker properties"
}

Get the User Code for a Worker

Get the worker with the given identifier.

Authorizations:
CookieSessionAPIKey
path Parameters
id
required
string <uuid>

The UUID of the worker

Responses

Response samples

Content type
application/json
{
  • "message": "Fetched worker",
  • "data": "string"
}

APIKeys

List API Keys

Lists API Keys

Authorizations:
CookieSessionAPIKey
query Parameters
tenant_id
integer <int64>

The id of the tenant from which to retrieve API keys

cursor
string

The cursor for the current page

limit
integer

The maximum amount of items per page. Not applicable if cursor parameter is given. System limits are in place.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "page_size": 0,
  • "total_count": 0,
  • "data": [
    ]
}

Creates a new API key for the given Tenant

Create an API key for a tenant with an expiration date. Permissions for the API key within that organisation must be set

Authorizations:
CookieSessionAPIKey
Request Body schema: application/json
name
required
string
tenant_id
required
integer <int64>
permissions
Array of strings
expiration_date
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "Device Beheerder",
  • "tenant_id": 19,
  • "permissions": [
    ],
  • "expiration_date": "2023-05-17T15:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "api_key": "MjU5MzE1NDgwMjE2NTMwMTEyODo2MjY2MDdkMGViY2Q5MGRhMTRkZWE4NGY4MjEzYjRiNw"
}

Get an API Key by ID

Get an API Key by ID

Authorizations:
CookieSessionAPIKey
path Parameters
api_key_id
required
integer <int64>

The identifier of the API key

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Provincie Zeeland",
  • "tenant_id": 19,
  • "tenant_name": "Provincie Zeeland",
  • "expiration_date": "2023-05-17T15:00:00.000Z",
  • "created": "2022-05-17T15:00:00.000Z"
}

Revokes an API key

Revokes an API key so that it can't be used anymore

Authorizations:
CookieSessionAPIKey
path Parameters
api_key_id
required
integer <int64>

The identifier of the API key

Responses

Response samples

Content type
application/json
{
  • "message": "API key has been revoked"
}