withthegrid
API docs by Redocly

Asset Monitoring Platform API (12)

Download OpenAPI specification:

API support: info@withthegrid.com URL: https://withthegrid.com/

Getting started

Introduction

This document provides information on how to access the withthegrid application programmatically.

Programmatic access to the application requires a machine account. Almost everything a user can do in the user interface of the application, can also be done with a machine account. To obtain one, contact us at info@withthegrid.com. Our programmatic interface is a REST JSON API that is accessible through HTTPS. Select in the top bar whether you want to see the documentation for cURL or the Javascript fetch API.

Environment types

There are two types of environments in our application: monitoring environments and connectivity environments.

In monitoring environments, you store geospatial and other static information on infrastructural assets. You can create condition reports on the condition of these assets, resulting in measurement time series. Reports on asset can be manually created or by connecting an (IoT) device. The condition of the assets is monitored based on the condition reports and issues are automatically created when anomalies are detected.

In connectivity environments, developers of devices and external systems can:

  • manage the provisioning of their devices by means of HTTPS webhooks or client certificates (through CoAP over DTLS or HTTPS)
  • define event handlers in TypeScript that parse incoming payloads into condition reports, return instructions to devices (including FOTA) and monitor device health.
  • monitor activity of your devices
  • Generate claim tokens to share with the customer so they can securely claim the devices in their monitoring environment.

Rights & Routes

To interact with the API you can make HTTP requests to the routes in the left-hand menu. Most of these need authentication. Obtain a JSON webtoken from the Login route. The following rights exist for the monitoring environments:

Right Description
READ View (except audit trail)
STATIC Modify static data
ISSUES Manage issues
AUDIT_TRAIL View audit trail
USERS Manage users
EXPORT Export data
SENSORS Manage devices
REPORTS Manage condition reports
THRESHOLDS View measurement issue triggers
ENVIRONMENT_ADMIN Update configuration of the environment

For the connectivity environments there is only one right: ENVIRONMENT_ADMIN.

Headers

All requests need a header specifying the version of the api that is being used by the client for example: Api-Version: 4

As the route documentation will show, the request body and its response are almost always JSON encoded (with corresponding Content-Type: application/json header).

Schemas

Some objects in requests or responses are used multiple times. Those are extracted as models and listed separately under the schemas section.

Hashids

Almost all objects are identified by their hashId. This is an alphanumeric string uniquely identifying that object within its own object type. So the same hashId can occur for a Command and a PinGroup, but they identify different objects.

Form fields

In some object types, users can store custom data. The fields that can be used to store data in these objects are defined in a field configuration. The UI renders this field configuration as a form.

The following objects support these form fields:

Object with field Configured in
edges monitoring environment under fieldConfigurations.edges for fields
grids monitoring environment under fieldConfigurations.grids for fields
pin groups monitoring environment under fieldConfigurations.pinGroups for fields and device type under pinGroupFieldConfigurations for deviceFields.
nodes monitoring environment under fieldConfigurations.nodes for fields
pin monitoring environment under fieldConfigurations.pins for fields and device type under channels[].pinFieldConfigurations for deviceFields.
reports manual report type and device report type for fields
commands command type for fields
devices device type for fields

The name of an edge, grid, pin group, node and pin objects is defined as the value of the first field in the field configuration. At least one key is therefore required in these fields properties.

User defined code

User defined code Location of the code editor in the ui where commented templates can be found
form field Everywhere where form fields can be defined. For example in the "Monitoring environment" settings, under "Form fields". Click on a property and press "Show advanced options". The 5 UDFs can be viewed using the code editor at the bottom.
device supplier certificate identifier In the "Connectivity environment" under "Device authentication", "Client certificate access". Click on a certificate and press "Edit the identifier" to reach the code editor.
device supplier webhook identifier In the "Connectivity environment" under "Device authentication", "Webhook access". Click on a webhook and press "Edit the identifier" to reach the code editor.
device type eventHandler In the "Connectivity environment" under "Device types". Click on a device type and press "Edit the event handler" to reach the code editor.
device condition report parser In the "Connectivity environment" under "Report types". Click on a report type and press "Edit the parser" to reach the code editor.

Login

machineLogin

Acquire a JSON web token that can be used to perform authenticated requests. The jwt expiration is typically 30 days.

header Parameters
Api-Version
required
integer
Example: 5
Request Body schema: text/json
assertion
required
string

Is provided when you create a machine account (also called an API account)

Responses

Request samples

Content type
text/json
{
  • "assertion": "12as:7d6a4123"
}

Response samples

Content type
text/json
{
  • "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpcCI6InJvYkB3aXRodGhlZ3JpZC5jb20iLCJpA9qiOjE1Nzc3MTA5NjksImV4cCI6MTU4MDMwMjk2OSwiaXNzIjoid2l0aHRoZWdyaWQifQ.7PbwwsWU7x63Pd-J_KZQL22r185GfiufixyXQGOyQs8",
  • "user": {
    },
  • "environment": {
    },
  • "environmentRights": [
    ],
  • "userEnvironmentSettings": {
    }
}

Command

add

Add a command that should be sent to a specific device

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: SENSORS

Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
objectType
required
string
Enum: "device" "pinGroup"
objectHashIds
required
Array of strings [ 1 .. 40 ] items
commandTypeHashId
required
string
fields
required
object

How form fields should be sent to the server when creating them.

startAt
string or null <date-time>

Timestamp the device should execute the command. The system tries to share the command with the device before that time. If null, the device should execute it at time of receival + command.delay. It depends on the commandType whether startAt can be null

delay
number <float>

In seconds. Only relevant when startAt is null. The command should then be executed by the device at time of receival + delay

endAt
string or null <date-time>

Timestamp the device should stop execution of the command.

channelIndices
Array of numbers <float> <= 60 items [ items <float > ]
Default: []

The device channels for which this command is relevant. See commandType.channelSelect for allowed values.

email
required
Array of strings <email> [ items <email > ]

An email will be sent to all provided email addresses when the command is executed by the device

Responses

Request samples

Content type
text/json
{
  • "objectType": "device",
  • "objectHashIds": [
    ],
  • "commandTypeHashId": "x18a92",
  • "fields": {
    },
  • "startAt": "2019-12-31T15:23Z",
  • "delay": 0.1,
  • "endAt": null,
  • "channelIndices": [ ],
  • "email": [ ]
}

deleteMulti

Delete multiple commands. Will return an array showing which commands were deleted or not.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: SENSORS

Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings <= 30 items

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ]
}

Response samples

Content type
text/json
[
  • {
    }
]

find

Search through commands

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/command/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a command. Will raise an error if the command cannot be canceled because the device has already executed it or because the device will not be reached in time to let it know that it should ignore the command.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: SENSORS

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: ga9741s
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/command/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific command identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: ga9741s
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/command/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "command": {
    },
  • "commandType": {
    },
  • "createdByUserName": "John Doe"
}

Command-type

add

Create a command type that can be sent to devices

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
untranslatedString (string) or translations (object) (stringOrTranslations)
start
string
Default: "optional"
Enum: "required" "optional" "disabled"

'required': user must provide command.startAt. 'optional': user can provide command.startAt or a delay for the command to start after it is sent to the device. 'disabled': user cannot provide command.startAt nor a delay.

end
string
Default: "disabled"
Enum: "required" "optional" "disabled"

'required': user must provide command.endAt. 'optional': user can provide command.endAt. 'disabled': user cannot provide command.endAt.

required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects <= 50 items

See the chapter on open fields on how to use this

channelSelect
string
Default: "off"
Enum: "single" "multiple" "off"

When creating a command of this type, the user can then optionally choose one (in case of 'single') or more channelIndices (in case of 'multiple') for which this command is relevant. If 'off' is chosen, the user cannot specify channelIndices

environmentAccess
string
Default: "full"
Enum: "full" "read" "none"

'full': end-users can view, create and delete commands of this type. 'read': end-users can view but not create and delete commands of this type. 'none': end-users cannot view, create or delete commands of this type.

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "start": "required",
  • "end": "required",
  • "fieldConfigurations": [
    ],
  • "channelSelect": "single",
  • "environmentAccess": "full"
}

Response samples

Content type
text/json
{
  • "hashId": "x18a92"
}

find

Search through command types

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/command-type/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a command type.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: x18a92
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/command-type/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific command type identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: x18a92
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/command-type/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "commandType": {
    }
}

update

Update a command type.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: x18a92
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
untranslatedString (string) or translations (object) (stringOrTranslations)
start
string
Enum: "required" "optional" "disabled"

'required': user must provide command.startAt. 'optional': user can provide command.startAt or a delay for the command to start after it is sent to the device. 'disabled': user cannot provide command.startAt nor a delay.

end
string
Enum: "required" "optional" "disabled"

'required': user must provide command.endAt. 'optional': user can provide command.endAt. 'disabled': user cannot provide command.endAt.

Array of objects (updatableFieldConfigurations) <= 50 items

See the chapter on open fields on how to use this

channelSelect
string
Enum: "single" "multiple" "off"

When creating a command of this type, the user can then optionally choose one (in case of 'single') or more channelIndices (in case of 'multiple') for which this command is relevant. If 'off' is chosen, the user cannot specify channelIndices

environmentAccess
string
Default: "full"
Enum: "full" "read" "none"

'full': end-users can view, create and delete commands of this type. 'read': end-users can view but not create and delete commands of this type. 'none': end-users cannot view, create or delete commands of this type.

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "start": "required",
  • "end": "required",
  • "fieldConfigurations": [
    ],
  • "channelSelect": "single",
  • "environmentAccess": "full"
}

Connectivity-threshold

set

Creates or updates a connectivity threshold.

Rights

  • Monitoring environment: THRESHOLDS
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
object or null

Responses

Request samples

Content type
text/json
{
  • "connectivityThreshold": {
    }
}

find

Returns all found connectivity thresholds for an environment.

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/connectivity-threshold/find \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

Device

addWithPsk

Add a new pre-shared key (PSK) device.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
supplierDeviceIdentifier
required
string

Should be unique within the connectivity environment

deviceTypeHashId
required
string
psk
required
string <= 512 characters
pskIdentity
required
string <= 255 characters

Responses

Request samples

Content type
text/json
{
  • "supplierDeviceIdentifier": "390044000351352237353037",
  • "deviceTypeHashId": "wasd2",
  • "psk": "cuXodopvJGoiKpuOcZ6pw/3euyP+yld5",
  • "pskIdentity": "=d37d7&&dhdkf2"
}

Response samples

Content type
text/json
{
  • "hashId": "j1iha9"
}

find

Search through devices

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

claim

Add one or more devices to this monitoring environment by providing their claim tokens. This invalidates the claim token

Rights

  • Monitoring environment: SENSORS
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
claimTokens
required
Array of strings [ 1 .. 30 ] items

Responses

Request samples

Content type
text/json
{
  • "claimTokens": [
    ]
}

Response samples

Content type
text/json
{
  • "devices": [
    ]
}

delete

Delete one or more devices. If a device is claimed by a monitoring environment, it cannot be deleted.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings [ 1 .. 30 ] items

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ]
}

get

Get a specific device identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: j1iha9
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "device": {
    },
  • "deviceType": null,
  • "environmentName": "My monitoring environment",
  • "environmentHashId": "f1a4w1",
  • "pinGroup": {
    }
}

update

Update a device.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: j1iha9
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

Responses

Request samples

Content type
text/json
{
  • "fields": { }
}

Response samples

Content type
text/json
{
  • "device": {
    }
}

getClaimToken

Get claim tokens for one or more devices. These claim tokens can be used in a monitoring environment to claim these devices. This request invalidates older claim tokens for these devices. Suppliers cannot acquire a claim token for devices that have already been claimed by a monitoring environment. Users in a monitoring environment cannot acquire a claim token for devices that are linked to a pin group.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: SENSORS

Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
deviceHashIds
required
Array of strings [ 1 .. 30 ] items

Responses

Request samples

Content type
text/json
{
  • "deviceHashIds": [
    ]
}

Response samples

Content type
text/json
{
  • "claimTokens": [
    ]
}

getConnectivityCounters

Gets the device connectivity counters values and their key names

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: dao97
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device/device/{hashId}/connectivity-counters \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
[
  • {
    }
]

link

Connect a device to a pin group (and its channels to the pin group's pins. Future condition reports from this device will also be available on this pin group. A claim token for this device will be invalidated

Rights

  • Monitoring environment: SENSORS
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: j1iha9
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
pinGroupHashId
required
string
required
Array of objects <= 60 items

Responses

Request samples

Content type
text/json
{
  • "pinGroupHashId": "dao97",
  • "channelMapping": [
    ]
}

Response samples

Content type
text/json
{
  • "device": {
    },
  • "deviceType": null,
  • "measurementCycle": null,
  • "nextReportBefore": "2019-12-31T15:25Z"
}

unclaim

Remove one or more devices from this monitoring environment. Only use this if you want to return the device to the supplier

Rights

  • Monitoring environment: SENSORS
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings [ 1 .. 30 ] items

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ]
}

unlink

Disconnect a device from a pin group. Future condition reports from this device will no longer be registered on the pin group it was connected to.

Rights

  • Monitoring environment: SENSORS
Authorizations:
jwt-token
path Parameters
deviceHashId
required
string
Example: j1iha9
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X POST https://api.withthegrid.com/device/{deviceHashId}/unlink \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}' \

Device-connectivity-counter-key

add

Add a counter to the connectivity environment that can be used to count device connectivity events.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string

Responses

Request samples

Content type
text/json
{
  • "name": "My counter"
}

Response samples

Content type
text/json
{
  • "hashId": "l74xg825"
}

find

Search through device connectivity counter keys.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device-connectivity-counter-key/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a device connectivity counter key from a connectivity environment.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l74xg825
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/device-connectivity-counter-key/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific device connectivity counter key by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l74xg825
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device-connectivity-counter-key/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "hashId": "l74xg825",
  • "name": "My counter"
}

update

Update the properties of a device connectivity counter key.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l74xg825
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string

Responses

Request samples

Content type
text/json
{
  • "name": "My counter"
}

Device-type

add

Add a new device type.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
untranslatedString (string) or translations (object) (stringOrTranslations)
eventHandler
required
string <= 1000000 characters

A javascript function that handles events. See the chapter "User defined code

required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects <= 50 items

See the chapter on open fields on how to use this

required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects <= 50 items

Defines deviceFields on the location (pinGroup) the device is connected to. Can be used in report type functions. See the chapter on open fields on how to use this

required
Array of objects <= 60 items
Array of objects <= 5 items
commandTypeHashIds
required
Array of strings <= 60 items

The hashIds of the command types a user can schedule for this device

identifierFieldKey
string or null

Value from form field with this key will be displayed as device identifier instead of hashId

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "eventHandler": "[omitted]",
  • "fieldConfigurations": [
    ],
  • "pinGroupFieldConfigurations": [
    ],
  • "channels": [
    ],
  • "charts": [
    ],
  • "commandTypeHashIds": [
    ],
  • "identifierFieldKey": "deviceFormFieldKey"
}

Response samples

Content type
text/json
{
  • "hashId": "wasd2",
  • "subscriptionHashId": "string"
}

find

Search through device types within a supplier, or within devices registered by client

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device-type/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a device type. All devices of this device type do no longer get access to the application!

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: wasd2
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/device-type/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific device type identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: wasd2
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/device-type/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "deviceType": null,
  • "eventHandler": "[omitted]",
  • "commandTypes": [
    ],
  • "subscriptionHashId": "string",
  • "chartQuantities": [
    ]
}

update

Update the settings of a device type.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: wasd2
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
untranslatedString (string) or translations (object) (stringOrTranslations)
eventHandler
string <= 1000000 characters

A javascript function that handles events. See the chapter "User defined code"

Array of objects (updatableFieldConfigurations) <= 50 items

See the chapter on open fields on how to use this

Array of objects (updatableFieldConfigurations) <= 50 items

See the chapter on open fields on how to use this

Array of objects <= 60 items

All measurements are registered on a channel. When a device is installed at a location (pinGroup), its channels are connected to the ports (pins) of the location (pinGroup). Be careful when altering channels that it does still make sense for already installed devices and historic condition reports. It is therefore not allowed to delete channels (therefore it is required that the array is not shorter than the existing channel array).

Array of objects <= 5 items
commandTypeHashIds
Array of strings <= 60 items

The hashIds of the command types a user can schedule for this device

identifierFieldKey
string or null

Value from form field with this key will be displayed as device identifier instead of hashId

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "eventHandler": "string",
  • "fieldConfigurations": [
    ],
  • "pinGroupFieldConfigurations": [
    ],
  • "channels": [
    ],
  • "charts": [
    ],
  • "commandTypeHashIds": [
    ],
  • "identifierFieldKey": "deviceFormFieldKey"
}

Environment

add

Create a monitoring environment

Authorizations:
jwt-token
header Parameters
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string <= 255 characters

Responses

Request samples

Content type
text/json
{
  • "name": "My monitoring environment"
}

Response samples

Content type
text/json
{
  • "environment": {
    },
  • "environmentRights": [
    ],
  • "userEnvironmentSettings": {
    }
}

delete

Delete a monitoring environment. No user can access it afterwards.

Rights

  • Monitoring environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/environment/ \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

find

Search through monitoring environments. Not useful for machine accounts, as they only have access to a single monitoring environment

Authorizations:
jwt-token
query Parameters
object
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/environment/ \
  -H 'Accept: text/json' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

update

Rights

  • Monitoring environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string
Array of objects (mapLayer) [ 1 .. 30 ] items
object

See the chapter on open fields on how to use this. A minimum of 1 element should be present in each field configuration array

locale
string
Enum: "en" "nl"

Locale code

defaultGraphRange
string
allowAutoCloseThresholdIssues
boolean
issueAutoClosingTriggerAmount
integer
issueAutoClosingTriggerUnitType
string
measurementsExpirationDays
integer [ 1 .. 9999 ]
measurementsRetentionPolicyRange
string or null

Period to keep measurements in the database. If null, they are kept forever.

enforceTwoFactorAuthentication
boolean

Describes if users need to have two factor authentication enabled in order to access this environment.

logo
string or null

Layout should be "data:;base64,", see https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL. Null clears the logo

object or null
allowAutoCloseConnectivityIssues
boolean
defaultLandingPage
string
defaultLandingPageHashId
string or null

Responses

Request samples

Content type
text/json
{
  • "name": "My monitoring environment",
  • "mapLayers": [],
  • "fieldConfigurations": {
    },
  • "locale": "en",
  • "defaultGraphRange": "30d",
  • "allowAutoCloseThresholdIssues": true,
  • "issueAutoClosingTriggerAmount": 0,
  • "issueAutoClosingTriggerUnitType": "string",
  • "measurementsExpirationDays": 365,
  • "measurementsRetentionPolicyRange": "string",
  • "enforceTwoFactorAuthentication": false,
  • "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "theme": {
    },
  • "allowAutoCloseConnectivityIssues": false,
  • "defaultLandingPage": "map",
  • "defaultLandingPageHashId": "string"
}

Response samples

Content type
text/json
{
  • "environment": {
    }
}

get

Get a specific monitoring environment identified by its hashId

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: f1a4w1
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/environment/{hashId} \
  -H 'Accept: text/json' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "environment": {
    },
  • "environmentRights": [
    ],
  • "userEnvironmentSettings": {
    }
}

Graph

addEdge

Create an edge

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
object
fields
required
object

How form fields should be sent to the server when creating them.

properties
any

deprecated

mapLayer
string
photo

Responses

Request samples

Content type
text/json
{
  • "geometry": {
    },
  • "fields": {
    },
  • "properties": null,
  • "mapLayer": "string",
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
}

Response samples

Content type
text/json
{
  • "hashId": "ka08d",
  • "edge": {
    }
}

findEdge

Search through edges

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/edge \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

addPinGrid

Create a pin grid

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
fields
required
object

How form fields should be sent to the server when creating them.

photo
pinHashIds
Array of strings <= 90 items
Default: []

Determines the set (and the order) of the pins in the grid

Responses

Request samples

Content type
text/json
{
  • "fields": {
    },
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "pinHashIds": [ ]
}

Response samples

Content type
text/json
{
  • "hashId": "naud51",
  • "grid": {
    }
}

addPinGroupGrid

Create a pin group grid

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
fields
required
object

How form fields should be sent to the server when creating them.

photo
pinGroupHashIds
Array of strings <= 90 items
Default: []

Determines the set (and the order) of the pin groups in the grid

Responses

Request samples

Content type
text/json
{
  • "fields": {
    },
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "pinGroupHashIds": [ ]
}

Response samples

Content type
text/json
{
  • "hashId": "naud51",
  • "grid": {
    }
}

addPinGroup

Create a pin group

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
symbolKey
required
string
required
object or null
fields
required
object

How form fields should be sent to the server when creating them.

mapLayer
string

If not provided, the first available one is chosen

photo
gridHashIds
Array of strings <= 30 items

PinGroups will be added at the end of the list in a grid

gridName
string

Ensures the pinGroup is part of a grid with the provided name. If multiple grids exist with the same name, one is chosen at random

Responses

Request samples

Content type
text/json
{
  • "symbolKey": "cp-pole",
  • "geometry": {
    },
  • "fields": {
    },
  • "mapLayer": "string",
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "gridHashIds": [
    ],
  • "gridName": "string"
}

Response samples

Content type
text/json
{
  • "hashId": "dao97",
  • "pinGroup": {
    }
}

findPinGroup

Search through pin groups

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin-group \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

addPin

Create a pin within a pin group

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
pinGroupHashId
required
string
Example: dao97
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
fields
required
object

How form fields should be sent to the server when creating them.

typeKey
string or null
edgeHashId
string or null
pinGridsHashIds
Array of strings or null <= 30 items

Responses

Request samples

Content type
text/json
{
  • "fields": {
    },
  • "typeKey": "string",
  • "edgeHashId": "ka08d",
  • "pinGridsHashIds": [
    ]
}

Response samples

Content type
text/json
{
  • "pin": {
    },
  • "grids": [
    ]
}

deleteEdge

Delete an edge.

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: ka08d
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/graph/edge/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

getEdge

Get a specific edge identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: ka08d
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/edge/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "edge": {
    },
  • "pins": [
    ],
  • "pinGroups": [
    ],
  • "measurementCycles": [ ],
  • "nextReportBefore": [
    ],
  • "thresholds": [
    ],
  • "photo": "https://api.amp.withthegrid.com/file/yr969d..."
}

updateEdge

Updates a specific edge

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: ka08d
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

mapLayer
string
object
photo
string or null

Layout should be "data:;base64,", see https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL. Null clears the photo

Responses

Request samples

Content type
text/json
{
  • "fields": { },
  • "mapLayer": "string",
  • "geometry": {
    },
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
}

Response samples

Content type
text/json
{
  • "edge": {
    }
}

deleteGrid

Delete a grid.

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: naud51
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/graph/grid/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

deletePinGroup

Delete a pin group.

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: dao97
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/graph/pin-group/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

getPinGroup

Get a specific pin group identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: dao97
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin-group/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "pinGroup": {
    },
  • "pins": [
    ],
  • "edges": [
    ],
  • "device": {
    },
  • "deviceType": null,
  • "channelMapping": [
    ],
  • "measurementCycle": null,
  • "thresholds": [
    ],
  • "photo": "https://api.amp.withthegrid.com/file/yr969d...",
  • "nextReportBefore": "2019-12-31T15:25Z",
  • "grids": [
    ]
}

updatePinGroup

Updates a specific pin group

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: dao97
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
symbolKey
string
object or null
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

mapLayer
string
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

photo
string or null

Layout should be "data:;base64,", see https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL. Null clears the photo

gridHashIds
Array of strings <= 30 items

PinGroups will be added at the end of the list in a grid

gridName
string

Ensures the pinGroup is part of a grid with the provided name. If multiple grids exist with the same name, one is chosen at random

deviceTypeDashboardIndex
integer

The index of the device type dashboard for graphs

Responses

Request samples

Content type
text/json
{
  • "symbolKey": "cp-rect",
  • "geometry": {
    },
  • "fields": { },
  • "mapLayer": "string",
  • "deviceFields": { },
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "gridHashIds": [
    ],
  • "gridName": "string",
  • "deviceTypeDashboardIndex": 0
}

Response samples

Content type
text/json
{
  • "pinGroup": {
    },
  • "grids": [
    ]
}

deletePin

Delete a pin.

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: e13d57
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/graph/pin/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

getPin

Get a specific pin identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: e13d57
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "pin": {
    },
  • "edges": [
    ],
  • "thresholds": [
    ]
}

updatePin

Updates a specific pin

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: e13d57
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

edgeHashId
string or null
pinGridsHashIds
Array of strings <= 30 items

Responses

Request samples

Content type
text/json
{
  • "fields": { },
  • "edgeHashId": "ka08d",
  • "pinGridsHashIds": [
    ]
}

Response samples

Content type
text/json
{
  • "pin": {
    },
  • "grids": [
    ]
}

find

Search through pinGroups, edges and pinGroup-grids

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

updateLocations

Updates the geometries of one or more nodes, pin groups and or edges

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
Array (<= 30 items)
Any of
type
required
string
Value: "pinGroup"
hashId
required
string
required
object or null

Responses

Request samples

Content type
text/json
[
  • {
    }
]

findGrid

Search through grids

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/grid \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

findPin

Search through pins

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

getPinGrid

Get a specific grid of type pin identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: naud51
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin-grid/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "grid": {
    },
  • "pins": [
    ],
  • "photo": "https://api.amp.withthegrid.com/file/yr969d..."
}

updatePinGrid

Updates a specific grid of type pin

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: naud51
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

photo
string or null

Layout should be "data:;base64,", see https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL. Null clears the photo

pinHashIds
Array of strings <= 90 items

Determines the set (and the order) of the pins in the grid

Responses

Request samples

Content type
text/json
{
  • "fields": { },
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "pinHashIds": [
    ]
}

Response samples

Content type
text/json
{
  • "grid": {
    },
  • "pins": [
    ]
}

getPinGroupGrid

Get a specific grid of type pinGroup identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: naud51
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin-group-grid/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "grid": {
    },
  • "pinGroups": [
    ],
  • "lastReports": [
    ],
  • "notificationLevel": 0,
  • "photo": "https://api.amp.withthegrid.com/file/yr969d..."
}

updatePinGroupGrid

Updates a specific grid

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: naud51
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

photo
string or null

Layout should be "data:;base64,", see https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL. Null clears the photo

pinGroupHashIds
Array of strings <= 10000 items

Determines the set (and the order) of the pin groups in the grid

Responses

Request samples

Content type
text/json
{
  • "fields": { },
  • "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "pinGroupHashIds": [
    ]
}

Response samples

Content type
text/json
{
  • "grid": {
    },
  • "pinGroups": [
    ],
  • "lastReports": [
    ]
}

getPinGroupPerformance

Get the performance of a device linked to a specific pin group identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: dao97
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin-group/{hashId}/performance \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
[
  • {
    }
]

getPinQuantities

Get a specific pin quantities by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
pinHashId
required
string
Example: e13d57
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/pin-quantities/{pinHashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "rows": [
    ]
}

getTile

Get a mapbox vector tile of the edges, nodes and pin groups within the provided bounding box.

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
x
required
integer
Example: 4207
y
required
integer
Example: 2693
z
required
integer
Example: 13
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/graph/tiles/{z}/{x}/{y} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
null

setNotification

Subscribe to or unsubscribe from new issues created on pin groups in this specific grid

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: naud51
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
level
required
number or null <float>
Enum: 0 1 2

Subscribe to every issue created on a pin group in this grid (0), when the issue gets serious (1) or when the issue gets critical (2). If you do not want to receive any notifications, set to null

Responses

Request samples

Content type
text/json
{
  • "level": 0
}

updatePinGroups

Updates pin groups

Rights

  • Monitoring environment: STATIC
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings <= 30 items
object

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ],
  • "mapLayer": {
    }
}

Import

generateTemplate

Generates an import template

Rights

  • Monitoring environment: IMPORT
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
pinGroupHashIds
required
Array of strings [ 0 .. 200 ] items

A list of location hashIds

pinGroupGridHashIds
required
Array of strings [ 0 .. 10 ] items

A list of location group hashIds

reportTypeHashIds
required
Array of strings [ 1 .. 5 ] items

A list of report type hashIds

Responses

Request samples

Content type
text/json
{
  • "pinGroupHashIds": [
    ],
  • "pinGroupGridHashIds": [
    ],
  • "reportTypeHashIds": [
    ]
}

Response samples

Content type
text/json
{}

add

Uploads an import file

Rights

  • Monitoring environment: IMPORT
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
dataUrl
required
name
string

The filename including extension

Responses

Request samples

Content type
text/json
{
  • "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "name": "red-dot.png"
}

Response samples

Content type
text/json
{
  • "importRequest": {
    },
  • "createdByUserName": "John Doe"
}

find

Search through imports within a monitoring environment

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: USERS

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/import/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Deletes an import

Rights

  • Monitoring environment: IMPORT
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: 5x2znek

The hashId of the import to be deleted

header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/import/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Issue

add

Create an issue

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
assignedUserHashId
string or null
pinGroupHashId
required
string
pinHashIds
required
Array of strings <= 1000 items

When empty, all pins are affected

required
(object or null) or (object or null)
title
required
string <= 255 characters
level
required
number <float>
Enum: 0 1 2
comment
required
string <= 65536 characters
Array of objects (fileToServer) <= 5 items
Default: []
labelHashIds
Array of strings <= 10 items
Default: []
doNotAutoClose
boolean
Default: false

Responses

Request samples

Content type
text/json
{
  • "assignedUserHashId": "string",
  • "pinGroupHashId": [
    ],
  • "pinHashIds": [
    ],
  • "automation": null,
  • "title": "Temperature is too high",
  • "level": 0,
  • "comment": "This looks serious.",
  • "files": [ ],
  • "labelHashIds": [
    ],
  • "doNotAutoClose": false
}

Response samples

Content type
text/json
{
  • "hashId": "c19aid",
  • "mentionedUsers": [
    ]
}

deleteMulti

Delete multiple issues. Will return an array showing which issues were deleted or not.

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings [ 2 .. 30 ] items

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ]
}

Response samples

Content type
text/json
[
  • {
    }
]

find

Search through issues

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/issue/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

addComment

Add a comment to a specific issue

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: a9hhi0

Identifies the issue to comment on

header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
comment
required
string <= 65536 characters
Array of objects (fileToServer) <= 5 items
Default: []
closeIssue
boolean
Default: false

Responses

Request samples

Content type
text/json
{
  • "comment": "This looks serious.",
  • "files": [ ],
  • "closeIssue": false
}

Response samples

Content type
text/json
{
  • "newComments": [
    ],
  • "mentionedUsers": [
    ]
}

addCommentMulti

Comment on multiple issues. Will return an array showing which issues were commented on or not.

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings [ 2 .. 30 ] items

The issues to comment on

comment
required
string <= 65536 characters
Array of objects (fileToServer) <= 5 items
Default: []
closeIssue
boolean
Default: false

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ],
  • "comment": "This looks serious.",
  • "files": [ ],
  • "closeIssue": false
}

Response samples

Content type
text/json
[
  • {
    },
  • {
    }
]

delete

Delete an issue.

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: c19aid
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/issue/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific issue identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: c19aid
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/issue/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "issue": {
    },
  • "userName": "John Doe",
  • "assignedUserName": null,
  • "mentionedUsers": [
    ],
  • "pinGroup": {
    },
  • "pins": [
    ],
  • "automation": {
    },
  • "labels": [
    ],
  • "comments": [
    ],
  • "subscribed": false
}

update

Change the settings of a specific issue

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: c19aid
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
title
string <= 255 characters
pinGroupHashId
string
pinHashIds
Array of strings <= 1000 items

When empty, all pins are affected

(object or null) or (object or null)
assignedUserHashId
string or null
labelHashIds
Array of strings <= 10 items
closed
boolean
level
number <float>
Enum: 0 1 2
doNotAutoClose
boolean

Responses

Request samples

Content type
text/json
{
  • "title": "Temperature is too high",
  • "pinGroupHashId": "string",
  • "pinHashIds": [
    ],
  • "automation": {
    },
  • "assignedUserHashId": "string",
  • "labelHashIds": [
    ],
  • "closed": true,
  • "level": 0,
  • "doNotAutoClose": true
}

Response samples

Content type
text/json
{
  • "newComment": {
    },
  • "newCommentUserName": "John Doe",
  • "newCommentMentionedUsers": [
    ]
}

setSubscription

Subscribe to or unsubscribe from a specific issue

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: c19aid
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
subscribed
required
boolean

Responses

Request samples

Content type
text/json
{
  • "subscribed": true
}

setSubscriptionMulti

Subscribe or unsubscribe multiple issues. Will return an array showing which issues were (un)subscribed or not.

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings [ 2 .. 30 ] items

The issues to (un)subscribe

subscribed
required
boolean

True to subscribe, false to unsubscribe

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ],
  • "subscribed": true
}

Response samples

Content type
text/json
[
  • {
    },
  • {
    }
]

updateMulti

Update multiple issues. Will return an array showing which issues were updated or not.

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
hashIds
required
Array of strings [ 2 .. 30 ] items

The issues to update

closed
boolean

Marks the issues as done

assignedUserHashId
string or null

The new assignee for the issues

labelHashIds
Array of strings <= 10 items

The labels to add to the issues (existing labels are kept)

Responses

Request samples

Content type
text/json
{
  • "hashIds": [
    ],
  • "closed": false,
  • "assignedUserHashId": "b45zo0",
  • "labelHashIds": [
    ]
}

Response samples

Content type
text/json
[
  • {
    },
  • {
    }
]

Issue-comment

delete

Delete a comment on an issue (if it is yours).

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: a9hhi0
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/issue-comment/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

update

Update a comment on an issue (if it is yours)

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: a9hhi0
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
comment
required
string <= 65536 characters

Responses

Request samples

Content type
text/json
{
  • "comment": "This looks serious."
}

Response samples

Content type
text/json
[
  • {
    }
]

Label

add

Create a label

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string <= 255 characters
color
required
string^#[a-fA-F\d]{6}$

A hex color string. #, followed by six hexadecimal characters

Responses

Request samples

Content type
text/json
{
  • "name": "Fix this month",
  • "color": "#ff0000"
}

Response samples

Content type
text/json
{
  • "hashId": "u98a24"
}

find

Search through labels

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/label/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a label.

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: u98a24
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/label/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

update

Rights

  • Monitoring environment: ISSUES
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: u98a24
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string <= 255 characters
color
string^#[a-fA-F\d]{6}$

A hex color string. #, followed by six hexadecimal characters

Responses

Request samples

Content type
text/json
{
  • "name": "string",
  • "color": "#ff0000"
}

get

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: xd2rd4
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/label/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "hashId": "xd2rd4",
  • "name": "My label",
  • "color": "#ff0000"
}

Measurement

find

Search through measurements

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/measurement/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

Measurement-filter

add

Add a measurement filter

Rights

  • Monitoring environment: REPORTS
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string <= 100 characters
description
required
string <= 255 characters
required
string or object
includePinsWithoutReports
boolean
Default: true
reportTypeHashIds
required
Array of strings <= 20 items
gridHashId
string
pinGroupHashIds
Array of strings [ 1 .. 50 ] items
quantityHashIds
required
Array of strings [ 1 .. 64 ] items
fieldKeys
required
Array of strings <= 20 items
pinFieldKeys
Array of strings <= 30 items
edgeFieldKeys
Array of strings <= 30 items

Responses

Request samples

Content type
text/json
{
  • "name": "North",
  • "description": "Temperatures in the North",
  • "period": "lastMonth",
  • "includePinsWithoutReports": true,
  • "reportTypeHashIds": [
    ],
  • "gridHashId": "string",
  • "pinGroupHashIds": [
    ],
  • "quantityHashIds": [
    ],
  • "fieldKeys": [
    ],
  • "pinFieldKeys": [
    ],
  • "edgeFieldKeys": [
    ]
}

Response samples

Content type
text/json
{
  • "hashId": "k8gh3"
}

find

Search through measurement filters

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/measurement-filter/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a measurement filter.

Rights

  • Monitoring environment: REPORTS
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: k8gh3
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/measurement-filter/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific measurement filter identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: k8gh3
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/measurement-filter/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "measurementFilter": {
    },
  • "reportTypes": [
    ],
  • "grid": {
    },
  • "pinGroups": [
    ],
  • "quantities": [
    ],
  • "fieldKeys": [
    ],
  • "pinFieldKeys": [
    ],
  • "edgeFieldKeys": [
    ]
}

update

Rights

  • Monitoring environment: REPORTS
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: k8gh3
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string <= 100 characters
description
string <= 255 characters
string or object
includePinsWithoutReports
boolean
reportTypeHashIds
Array of strings <= 20 items
gridHashId
string
pinGroupHashIds
Array of strings [ 1 .. 50 ] items
quantityHashIds
Array of strings [ 1 .. 64 ] items
fieldKeys
Array of strings <= 20 items
pinFieldKeys
Array of strings <= 30 items
edgeFieldKeys
Array of strings <= 30 items

Responses

Request samples

Content type
text/json
{
  • "name": "South",
  • "description": "string",
  • "period": "lastMonth",
  • "includePinsWithoutReports": true,
  • "reportTypeHashIds": [
    ],
  • "gridHashId": "string",
  • "pinGroupHashIds": [
    ],
  • "quantityHashIds": [
    ],
  • "fieldKeys": [
    ],
  • "pinFieldKeys": [
    ],
  • "edgeFieldKeys": [
    ]
}

Measurement-threshold

find

Search through measurement thresholds on environment and pin level

Rights

  • Monitoring environment: THRESHOLDS
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/measurement-threshold/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

set

Sets issue triggers (thresholds) on a specific quantity on a specific port (pin). If a measurement outside these limits is registered, an issue is automatically created (if there isn't a relevant one open yet)

Rights

  • Monitoring environment: THRESHOLDS
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
Any of
pinHashId
required
string
quantityHashId
required
string
required
object or null

Responses

Request samples

Content type
text/json
[ ]

Response samples

Content type
text/json
{
  • "hashId": "tap192"
}

Periodic-command

add

Add one or more command(s) and its/their periodic schedules

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: SENSORS

Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
object
required
string or object
start
string or null <date-time>
end
string or null <date-time>

Responses

Request samples

Content type
text/json
{
  • "command": {
    },
  • "period": "hourly",
  • "start": "2019-12-31T15:23Z",
  • "end": "2019-12-31T15:23Z"
}

find

Search through periodic commands

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/periodic-command/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a periodic command

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l74mzwwe
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/periodic-command/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific periodic command by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l74xg825
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/periodic-command/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "hashId": "l74mzwwe",
  • "commandHashId": "ga9741s",
  • "deviceHashId": "j1iha9",
  • "period": "hourly",
  • "nextPlanned": "2019-12-31T15:23Z",
  • "start": "2019-12-31T15:23Z",
  • "end": "2019-12-31T15:23Z",
  • "deletedAt": "2019-12-31T15:23Z"
}

update

Update the periodic schedule of a periodic command.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l74xg825
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
string or object

Responses

Request samples

Content type
text/json
{
  • "period": "hourly"
}

Quantity

add

Add a quantity

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
untranslatedString (string) or translations (object) (stringOrTranslations)
color
string^#[a-fA-F\d]{6}$
Default: "#ff00ff"

A hex color string. #, followed by six hexadecimal characters

unit
string or null

Will be displayed with an SI-prefix (eg. k or M) if relevant

defaultOrderOfMagnitude
integer [ -128 .. 127 ]

Defines default order of magnitude to be selected at manual report form

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

issueDelayS
integer or null [ 0 .. 2147483647 ]

Defines the time in seconds that needs to pass before an issue is created

issueDelayCount
integer or null [ 0 .. 2147483647 ]

Defines the number of measurements that need to be out of bounds before an issue is created

issueDelayIntervalType
string
Default: "atLeast"
Enum: "atLeast" "within"

Defines the type of interval for the issue delay. At least means that the issue will be created if at least issueDelayS seconds have passed since the first offending measurement was received and issueDelayCount measurements have been out of bounds. Within means that the issue will be created if there are issueDelayCount measurements out of bounds within issueDelayS seconds.

boolean or boolean
Default: true

Will reset the issue counting when a good measurement is received

disableSiPrefixes
boolean
Default: false

Will disable SI-prefixes for this quantity if true

deviceQuantityHashIds
Array of strings <= 30 items

Device quantities, linked to this quantity

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "color": "#ff0000",
  • "unit": "K",
  • "defaultOrderOfMagnitude": 3,
  • "defaultCriticallyLowThreshold": {
    },
  • "defaultLowThreshold": {
    },
  • "defaultHighThreshold": {
    },
  • "defaultCriticallyHighThreshold": {
    },
  • "issueDelayS": 2147483647,
  • "issueDelayCount": 2147483647,
  • "issueDelayIntervalType": "atLeast",
  • "issueDelayResetCount": true,
  • "disableSiPrefixes": true,
  • "deviceQuantityHashIds": [
    ]
}

Response samples

Content type
text/json
{
  • "hashId": "sajia1"
}

delete

Delete a quantity.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: sajia1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/quantity/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific quantity identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: sajia1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/quantity/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "reportTypes": [
    ],
  • "quantity": {
    },
  • "linkedSupplierQuantities": [
    ]
}

update

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: ENVIRONMENT_ADMIN

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: sajia1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
untranslatedString (string) or translations (object) (stringOrTranslations)
color
string^#[a-fA-F\d]{6}$

A hex color string. #, followed by six hexadecimal characters

unit
string or null

Will be displayed with an SI-prefix (eg. k or M) if relevant

defaultOrderOfMagnitude
integer [ -128 .. 127 ]

Defines default order of magnitude to be selected at manual report form

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

issueDelayCount
integer or null [ 0 .. 2147483647 ]

Defines the number of measurements that need to be out of bounds before an issue is created

issueDelayS
integer or null [ 0 .. 2147483647 ]

Defines the time in seconds that needs to pass before an issue is created

issueDelayIntervalType
string
Default: "atLeast"
Enum: "atLeast" "within"

Defines the type of interval for the issue delay. At least means that the issue will be created if at least issueDelayS seconds have passed since the first offending measurement was received and issueDelayCount measurements have been out of bounds. Within means that the issue will be created if there are issueDelayCount measurements out of bounds within issueDelayS seconds.

boolean or boolean
Default: true

Will reset the issue counting when a good measurement is received

disableSiPrefixes
boolean

Will disable SI-prefixes for this quantity

deviceQuantityHashIds
Array of strings <= 30 items

Device quantities, linked to this quantity

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "color": "#ff0000",
  • "unit": "K",
  • "defaultOrderOfMagnitude": 3,
  • "defaultCriticallyLowThreshold": {
    },
  • "defaultLowThreshold": {
    },
  • "defaultHighThreshold": {
    },
  • "defaultCriticallyHighThreshold": {
    },
  • "issueDelayCount": 2147483647,
  • "issueDelayS": 2147483647,
  • "issueDelayIntervalType": "atLeast",
  • "issueDelayResetCount": true,
  • "disableSiPrefixes": true,
  • "deviceQuantityHashIds": [
    ]
}

find

Search through quantities

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/quantity/quantities \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

Report

add

Rights

  • Monitoring environment: REPORTS
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
generatedAt
string <date-time>

The timestamp of the report itself. If not provided, the timestamp of the most recent measurement is taken. If no measurements are present, the existing generatedAt of the report is used.

required
Array of objects <= 1000 items
reportTypeHashId
required
string
pinGroupHashId
required
string
fields
object

How form fields should be sent to the server when creating them.

Responses

Request samples

Content type
text/json
{
  • "generatedAt": "2019-12-31T15:23Z",
  • "measurements": [
    ],
  • "reportTypeHashId": "l19a7s",
  • "pinGroupHashId": "dao97",
  • "fields": {
    }
}

Response samples

Content type
text/json
{
  • "hashId": "qoa978",
  • "fields": {
    }
}

find

Search through reports

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/report/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": null
}

delete

Delete a report.

Rights

  • Monitoring environment: REPORTS
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: qoa978
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/report/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific report identified by its hashId

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: qoa978
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/report/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "hashId": "qoa978",
  • "observations": [
    ],
  • "deviceType": null,
  • "deviceHashId": "j1iha9",
  • "fields": {
    },
  • "type": null,
  • "quantities": [
    ],
  • "pinGroupHashId": "dao97",
  • "userName": null,
  • "generatedAt": "2019-12-31T15:23Z",
  • "createdAt": "2019-12-31T15:23Z"
}

update

Rights

  • Monitoring environment: REPORTS
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: qoa978
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
generatedAt
string <date-time>

The timestamp of the report itself. If not provided, the timestamp of the most recent measurement is taken. If no measurements are present, the existing generatedAt of the report is used.

Array of objects <= 1000 items
object or (Array of objects or objects) (fieldsToServerUpdate)

How form fields should be sent to the server when updating them.

Responses

Request samples

Content type
text/json
{
  • "generatedAt": "2019-12-31T15:23Z",
  • "measurements": [
    ],
  • "fields": { }
}

Response samples

Content type
text/json
{
  • "fields": {
    }
}

getIdByTimeseriesPoint

Get a specific report identified by the data of a single time-series point

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
pinHashId
required
string
Example: e13d57
quantityHashId
required
string
Example: sajia1
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/report/{pinHashId}/{quantityHashId}/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "hashId": "qoa978"
}

Report-type

add

Add a report type for human reports.

Rights

  • Monitoring environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string
required
object

See the chapter on open fields on how to use this

required
Array of objects or objects <= 60 items

Responses

Request samples

Content type
text/json
{
  • "name": "Temperature",
  • "fieldConfigurations": {
    },
  • "quantities": [
    ]
}

Response samples

Content type
text/json
{
  • "hashId": "l19a7s"
}

find

Search through report types

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/report-type/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a report type.

Rights

  • Monitoring environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l19a7s
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/report-type/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific report type identified by its hashId. For report types of type 'human', quantities that used to be in the report type but are now deleted from it are not included. Report types of type 'device' do not contain any quantities.

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l19a7s
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/report-type/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "reportType": {
    },
  • "quantities": [
    ]
}

update

Update a report type for human reports.

Rights

  • Monitoring environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l19a7s
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string
object

See the chapter on open fields on how to use this

Array of objects or objects <= 60 items

Responses

Request samples

Content type
text/json
{
  • "name": "Temperature",
  • "fieldConfigurations": {
    },
  • "quantities": [
    ]
}

Settings

addExport

Request the creation of a zip file containing a data export

Rights

  • Monitoring environment: EXPORT
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
object or object or object or object or object
delimiter
required
string
Enum: "," ";"
rowDelimiter
required
string
Enum: "\n" "\r\n"

Responses

Request samples

Content type
text/json
{
  • "content": {
    },
  • "delimiter": ",",
  • "rowDelimiter": "\n"
}

Response samples

Content type
text/json
{
  • "hashId": "maay1"
}

findExportRequest

Search through export requests

Rights

  • Monitoring environment: EXPORT
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/settings/export \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{}

cancelExport

Cancel a running export request

Rights

  • Monitoring environment: EXPORT
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: maay1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X POST https://api.withthegrid.com/settings/export/{hashId}/cancel \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}' \

findLog

Search the audit log

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: AUDIT_TRAIL

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/settings/log \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

get

Get information about the logged in user

Authorizations:
jwt-token
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/settings/ \
  -H 'Accept: text/json' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "environment": {
    },
  • "environmentRights": [
    ],
  • "userEnvironmentSettings": {
    },
  • "user": {
    }
}

update

Update the settings of this user

Authorizations:
jwt-token
header Parameters
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string <= 255 characters
password
string >= 8 characters
locale
string
Enum: "en" "nl"

Locale code

timezone
string
phone
string or null
company
string or null

Responses

Request samples

Content type
text/json
{
  • "name": "Jane Doe",
  • "password": "stringst",
  • "locale": "en",
  • "timezone": "string",
  • "phone": "string",
  • "company": "string"
}

getExport

Get an export request by its hash ID

Rights

  • Monitoring environment: EXPORT
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: maay1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/settings/export/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{}

updateUserEnvironmentSettings

Update the environment settings of this user

Rights

  • Monitoring environment: READ
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
notificationLevel
number or null <float>
Enum: 0 1 2

The user is subscribed to every issue created on locations in this environment (0), when the issue gets serious (1) or when the issue gets critical (2). If null, the user is not automatically subscribed to new issues.

defaultAnalyticsPanelHashId
string or null
defaultLandingPage
string or null
object or null
object or null

Responses

Request samples

Content type
text/json
{
  • "notificationLevel": 0,
  • "defaultAnalyticsPanelHashId": "7usgt",
  • "defaultLandingPage": "map",
  • "settings": {
    },
  • "autosaveSettings": {
    }
}

Subscription

add

Subscribe to alerts on objects (currently all of supplier type)

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
objectType
required
string
Enum: "supplierReportType" "deviceType" "supplierWebhook" "supplierCertificate"
objectHashId
required
string

Responses

Request samples

Content type
text/json
{
  • "objectType": "deviceType",
  • "objectHashId": "wasd2"
}

Response samples

Content type
text/json
{
  • "hashId": "dfa1p"
}

find

Search through connectivity environments. Not useful for machine accounts, as they only have access to a single connectivity environment

Authorizations:
jwt-token
query Parameters
object
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/subscription/ \
  -H 'Accept: text/json' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a subscription.

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: l19a7s
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/subscription/{hashId} \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Supplier

add

Create a connectivity environment to connect external systems and individual IoT devices to our application, which can be used in one or more monitoring environments

Authorizations:
jwt-token
header Parameters
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string

Responses

Request samples

Content type
text/json
{
  • "name": "My connectivity environment"
}

Response samples

Content type
text/json
{
  • "supplier": {
    },
  • "supplierRights": [
    ]
}

delete

Delete a connectivity environment. No user can access it afterwards.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/supplier/ \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

find

Search through connectivity environments. Not useful for machine accounts, as they only have access to a single connectivity environment

Authorizations:
jwt-token
query Parameters
object
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier/ \
  -H 'Accept: text/json' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

update

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string
enforceTwoFactorAuthentication
boolean

Describes if users need to have two factor authentication enabled in order to access this environment.

logo
string or null

[object Object]. Null clears the logo

object or null

Responses

Request samples

Content type
text/json
{
  • "name": "My connectivity environment",
  • "enforceTwoFactorAuthentication": false,
  • "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "theme": {
    }
}

get

Get a specific connectivity environment identified by its hashId

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: f1a4w1
header Parameters
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier/{hashId} \
  -H 'Accept: text/json' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "supplier": {
    },
  • "supplierRights": [
    ]
}

Supplier-activity

find

Search through activity in the connectivity environment

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-activity/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

get

Get a specific activity in the connectivity environment

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: 2ad91p
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-activity/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "device": {
    },
  • "deviceType": null,
  • "activity": {
    }
}

Supplier-certificate

add

Add a certificate to the connectivity environment that can be used to create device client certificates.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
csr
required
string

A Base64 encoded PKCS#10 certificate signing request

identifier
required
string <= 1000000 characters

A javascript function that returns deviceType and identifier. See the chapter "User defined code"

Responses

Request samples

Content type
text/json
{
  • "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIHhMIGHAgEAMCUxEjAQBgNVBAoMCWRldmVsb3BlcjEPMA0GA1UEAwwGeGQycmQ0\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEyHDE7farWQdLw/HDgOcbt9BU8ba6\nfEvEY79Z47ozYQ6LAt6wYEW/4Aq4Eir1kSCw/DtououtnpaQokZQkGYf2aAAMAoG\nCCqGSM49BAMCA0kAMEYCIQCHf/bilJwxF+7V/0mifsXK4U0PUHDe0YNBorb2dBzc\nKAIhAK59odu1i8oxIJg237EOLKbf0k/Rhub/CKPrsQ50t0lK\n-----END CERTIFICATE REQUEST-----",
  • "identifier": "function (command) {\n return JSON.stringify({\n hashId: command.hashId,\n commandTypeHashId: command.commandTypeHashId,\n startAt: command.startAt,\n endAt: command.endAt,\n settings: command.settings,\n });\n}"
}

Response samples

Content type
text/json
{
  • "hashId": "v19a12",
  • "certificate": "-----BEGIN CERTIFICATE-----\nMIIBNzCB3gIBATAKBggqhkjOPQQDAjAkMREwDwYDVQQKDAhzdXBwbGllcjEPMA0G\nA1UEAwwGeGQycmQ0MB4XDTIwMDIyNDEzNTQwOVoXDTIxMDIyMzEzNTQwOVowLDEP\nMA0GA1UECgwGZGV2aWNlMRkwFwYDVQQDDBB1bnFpZSBpZGVudGlmaWVyMFkwEwYH\nKoZIzj0CAQYIKoZIzj0DAQcDQgAEUPyQwLuDlKw7CA41ADhxXRvD3n9ZFF0XCeI9\nOAgRIgl2mGmnO31wX1DD4weZoB2pswCBrC39FpyHgIz6LK10PzAKBggqhkjOPQQD\nAgNIADBFAiEAyz0Ha4eFfebqSoES4vxguipSHmR/zN8KjEEie7xpqo8CICFS5NWG\niaT6xhGfChGbQjpmQQYYabau8Ons8F2JNyLu\n-----END CERTIFICATE-----\n",
  • "subscriptionHashId": "string"
}

find

Search through certificates

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-certificate/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a certificate from a connectivity environment. When the certificate has been removed, access to the application by devices with a device certificate signed by this intermediate certificate is rejected.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: v19a12
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/supplier-certificate/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific certificate identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: f1a4w1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-certificate/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "certificate": {
    },
  • "identifier": "function (command) {\n return JSON.stringify({\n hashId: command.hashId,\n commandTypeHashId: command.commandTypeHashId,\n startAt: command.startAt,\n endAt: command.endAt,\n settings: command.settings,\n });\n}",
  • "subscriptionHashId": "string"
}

update

Update the properties of a certificate.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: v19a12
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
identifier
string <= 1000000 characters

A javascript function that returns deviceType and identifier. See the chapter "User defined code"

Responses

Request samples

Content type
text/json
{
  • "identifier": "string"
}

Supplier-credential

add

Add a credential to the connectivity environment that can be used to authenticate requests.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string
secret
required
string

Responses

Request samples

Content type
text/json
{
  • "name": "My credential",
  • "secret": "iamsecret"
}

Response samples

Content type
text/json
{
  • "hashId": "w5dshc"
}

find

Search through credentials.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-credential/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a credential from a connectivity environment.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: w5dshc
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/supplier-credential/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific credential identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: w5dshc
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-credential/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "credential": {
    }
}

update

Update the properties of a certificate.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: w5dshc
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string
secret
string

Responses

Request samples

Content type
text/json
{
  • "name": "My credential",
  • "secret": "iamsecret"
}

Supplier-report-type

add

Create a report type that devices can send in

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
required
untranslatedString (string) or translations (object) (stringOrTranslations)
required
object

See the chapter on open fields on how to use this

parser
required
string <= 1000000 characters

A javascript function that parses an incoming report. See the chapter "User defined code"

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "fieldConfigurations": {
    },
  • "parser": "[omitted]"
}

Response samples

Content type
text/json
{
  • "hashId": "y124as",
  • "subscriptionHashId": "string"
}

find

Search through device report types

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-report-type/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

delete

Delete a device report type.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: y124as
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/supplier-report-type/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific device report type identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: y124as
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-report-type/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "reportType": {
    },
  • "parser": "[omitted]",
  • "subscriptionHashId": "string"
}

update

Update a device report type.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: y124as
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
untranslatedString (string) or translations (object) (stringOrTranslations)
object

See the chapter on open fields on how to use this

parser
string <= 1000000 characters

A javascript function that parses an incoming report. See the chapter "User defined code"

retryFailedSince
string <date-time>

If supplied, all incoming reports of this type that failed to decode since the provided date will be reparsed.

Responses

Request samples

Content type
text/json
{
  • "name": "untranslated string",
  • "fieldConfigurations": {
    },
  • "parser": "[omitted]",
  • "retryFailedSince": "2019-08-24T14:15:22Z"
}

Supplier-webhook

add

Add a webhook to the connectivity environment.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string <= 255 characters
identifier
required
string <= 1000000 characters

A javascript function that returns deviceType and identifier. See the chapter "User defined code"

Responses

Request samples

Content type
text/json
{
  • "name": "My webhook",
  • "identifier": "function (command) {\n return JSON.stringify({\n hashId: command.hashId,\n commandTypeHashId: command.commandTypeHashId,\n startAt: command.startAt,\n endAt: command.endAt,\n settings: command.settings,\n });\n}"
}

Response samples

Content type
text/json
{}

find

Search through webhooks

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-webhook/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{}

delete

Delete a webhook from a connectivity environment.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: z812a63
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X DELETE https://api.withthegrid.com/supplier-webhook/{hashId} \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

get

Get a specific webhook identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: f1a4w1
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/supplier-webhook/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "webhook": {
    },
  • "identifier": "function (command) {\n return JSON.stringify({\n hashId: command.hashId,\n commandTypeHashId: command.commandTypeHashId,\n startAt: command.startAt,\n endAt: command.endAt,\n settings: command.settings,\n });\n}",
  • "url": "https://api.amp.withthegrid.com/iot?s=f1a4w1?t=asd193gaf11234",
  • "subscriptionHashId": "string"
}

update

Update the properties of a webhook.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN
Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: v19a12
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
string
identifier
string <= 1000000 characters

A javascript function that returns deviceType and identifier. See the chapter "User defined code"

Responses

Request samples

Content type
text/json
{
  • "name": "My webhook",
  • "identifier": "string"
}

User

add

Add a user to a monitoring environment or a connectivity environment.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: USERS

Authorizations:
jwt-token
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
name
required
string <= 255 characters
email
required
string <email>
rights
required
Array of strings <= 12 items
Items Enum: "READ" "STATIC" "ISSUES" "AUDIT_TRAIL" "USERS" "EXPORT" "SENSORS" "REPORTS" "THRESHOLDS" "IMPORT" "ENVIRONMENT_ADMIN" "ADMIN"

See the getting started section about rights

Responses

Request samples

Content type
text/json
{
  • "name": "John Doe",
  • "email": "info@acme.com",
  • "rights": [
    ]
}

Response samples

Content type
text/json
{
  • "hashId": "b45zo0"
}

find

Search through users within a monitoring environment or a connectivity environment

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: READ

Authorizations:
jwt-token
query Parameters
object
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/user/ \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "nextPageOffset": null,
  • "rows": [
    ]
}

get

Get a specific user identified by its hashId

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: USERS

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: b45zo0
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5

Responses

Request samples 


# You can also use wget
curl -X GET https://api.withthegrid.com/user/{hashId} \
  -H 'Accept: text/json' \
  -H 'Environment-Hash-Id: yourAssetEnvironmentHashId' \
  -H 'Api-Version: 5' \
  -H 'Authorization: Bearer {access-token}'

Response samples

Content type
text/json
{
  • "user": {
    },
  • "rights": [
    ],
  • "notificationLevel": 0,
  • "isSsoLinkedToThisEnvironment": false
}

update

Update the rights of a user for this monitoring environment or connectivity environment.

Rights

  • Connectivity environment: ENVIRONMENT_ADMIN

  • Monitoring environment: USERS

Authorizations:
jwt-token
path Parameters
hashId
required
string
Example: b45zo0
header Parameters
Environment-Hash-Id
required
string
Example: yourAssetEnvironmentHashId
Api-Version
required
integer
Example: 5
Request Body schema: text/json
rights
required
Array of strings <= 12 items
Items Enum: "READ" "STATIC" "ISSUES" "AUDIT_TRAIL" "USERS" "EXPORT" "SENSORS" "REPORTS" "THRESHOLDS" "IMPORT" "ENVIRONMENT_ADMIN" "ADMIN"

See the getting started section about rights

Responses

Request samples

Content type
text/json
{
  • "rights": [
    ]
}

Schemas

analyticsQuery

source
required
string
required
Array of objects or objects or objects or objects <= 60 items
object
object
offset
string
Array of objects <= 60 items
rowsPerPage
number <float> [ 10 .. 100 ]
Default: 20
{
  • "source": "pinGroup",
  • "columns": [
    ],
  • "filter": {
    },
  • "limitBy": {
    },
  • "offset": "string",
  • "sort": [ ],
  • "rowsPerPage": 20
}

command

hashId
required
string
deviceHashId
required
string
commandTypeHashId
required
string
fields
required
object

How form fields are returned by the server.

pinGroupHashId
required
string or null
userHashId
required
string or null
periodHashId
required
string or null
startAt
required
string or null <date-time>

Timestamp the device should execute the command. The system tries to share the command with the device before that time. If null, the device should execute it at time of receival + command.delay

delay
required
number <float>

In seconds. Only relevant when startAt is null. The command should then be executed by the device at time of receival + delay

endAt
required
string or null <date-time>

Timestamp the device should stop execution of the command.

channelIndices
required
Array of numbers <float> <= 60 items [ items <float > ]

The device channels for which this command is relevant. See commandType.channelSelect for allowed values.

email
Array of strings or null <email> <= 30 items [ items <email > ]
createdAt
string <date-time>
deletedAt
string or null <date-time>
sentAt
required
string or null <date-time>
{
  • "hashId": "ga9741s",
  • "deviceHashId": "j1iha9",
  • "commandTypeHashId": "x18a92",
  • "fields": { },
  • "pinGroupHashId": "dao97",
  • "userHashId": "b45zo0",
  • "periodHashId": "l74mzwwe",
  • "startAt": "2019-12-31T15:23Z",
  • "delay": 0,
  • "endAt": null,
  • "channelIndices": [
    ],
  • "email": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "sentAt": "2019-12-31T15:23Z"
}

commandPeriod

hashId
required
string
commandHashId
required
string
deviceHashId
required
string
required
string or object
nextPlanned
required
string <date-time>
start
required
string <date-time>
end
string or null <date-time>
deletedAt
string or null <date-time>
{
  • "hashId": "l74mzwwe",
  • "commandHashId": "ga9741s",
  • "deviceHashId": "j1iha9",
  • "period": "hourly",
  • "nextPlanned": "2019-12-31T15:23Z",
  • "start": "2019-12-31T15:23Z",
  • "end": "2019-12-31T15:23Z",
  • "deletedAt": "2019-12-31T15:23Z"
}

commandType

hashId
required
string
required
untranslatedString (string) or translations (object) (stringOrTranslations)
start
required
string
Enum: "required" "optional" "disabled"

'required': user must provide command.startAt. 'optional': user can provide command.startAt or a delay for the command to start after it is sent to the device. 'disabled': user cannot provide command.startAt nor a delay.

end
required
string
Enum: "required" "optional" "disabled"

'required': user must provide command.endAt. 'optional': user can provide command.endAt. 'disabled': user cannot provide command.endAt.

required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects <= 50 items

See the chapter on open fields on how to use this

channelSelect
required
string
Enum: "single" "multiple" "off"

When creating a command of this type, the user can then optionally choose one (in case of 'single') or more channelIndices (in case of 'multiple') for which this command is relevant. If 'off' is chosen, the user cannot specify channelIndices

environmentAccess
required
string
Enum: "full" "read" "none"

'full': end-users can view, create and delete commands of this type. 'read': end-users can view but not create and delete commands of this type. 'none': end-users cannot view, create or delete commands of this type.

{
  • "hashId": "x18a92",
  • "name": "untranslated string",
  • "start": "required",
  • "end": "disabled",
  • "fieldConfigurations": [
    ],
  • "channelSelect": "off",
  • "environmentAccess": "none"
}

device

hashId
required
string
supplierHashId
required
string
supplierDeviceIdentifier
required
string <= 255 characters

Should be unique within the connectivity environment

deviceTypeHashId
required
string
environmentHashId
string or null
fields
required
object

How form fields are returned by the server.

measurementCycle
any or null
nextReportBefore
required
string or null <date-time>
lastOnlineAt
required
string or null <date-time>
validated
required
boolean
userFacingIdentifier
string or null

A value of field, specified as identifierFieldKey

{
  • "hashId": "j1iha9",
  • "supplierHashId": "f1a4w1",
  • "supplierDeviceIdentifier": "390044000351352237353037",
  • "deviceTypeHashId": "wasd2",
  • "environmentHashId": "f1a4w1",
  • "fields": { },
  • "measurementCycle": null,
  • "nextReportBefore": "2019-12-31T15:25Z",
  • "lastOnlineAt": "2019-12-31T15:23Z",
  • "validated": true,
  • "userFacingIdentifier": "Field value"
}

deviceConnectivityCounterKey

hashId
required
string
name
required
string [ 0 .. 255 ] characters
{
  • "hashId": "l74xg825",
  • "name": "My counter"
}

deviceType

hashId
required
string
required
untranslatedString (string) or translations (object) (stringOrTranslations)
required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects <= 50 items

See the chapter on open fields on how to use this

required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects <= 50 items

Defines deviceFields on the location (pinGroup) the device is connected to. Can be used in report type functions. See the chapter on open fields on how to use this

required
Array of objects <= 60 items
required
Array of objects <= 5 items
commandTypeHashIds
required
Array of strings <= 60 items

The hashIds of the command types a user can schedule for this device

identifierFieldKey
string or null

Chosen field will serve as an identifier for device instead of hashId

updatedAt
required
string <date-time>
{
  • "hashId": "wasd2",
  • "name": "untranslated string",
  • "fieldConfigurations": [
    ],
  • "pinGroupFieldConfigurations": [
    ],
  • "channels": [
    ],
  • "charts": [
    ],
  • "commandTypeHashIds": [
    ],
  • "identifierFieldKey": "fieldKey",
  • "updatedAt": "2019-12-31T15:23Z"
}

edge

hashId
required
string
object or object
name
required
string
fields
required
object

The field configuration is stored in the fieldConfigurations key of the monitoring environment object

level
required
integer
Enum: 0 1 2

0: no serious or critical open issues, 1: one or more serious open issues and no critical open issues, 2: one or more critical open issues

mapLayer
required
string
mostRecentMeasurementAt
required
string or null <date-time>
deletedAt
required
string or null <date-time>
{
  • "hashId": "ka08d",
  • "geometry": [
    ],
  • "name": "My line",
  • "fields": {
    },
  • "level": 0,
  • "mapLayer": "myLayer",
  • "mostRecentMeasurementAt": null,
  • "deletedAt": null
}

environment

hashId
required
string
name
required
string <= 255 characters
required
Array of objects (mapLayer) [ 1 .. 30 ] items
required
object or null

All pin groups and edges in this monitoring environment are contained in the rectangle described by this linestring. If null, no locations (pinGroups) or lines (edges) are present

required
object

See the chapter on open fields on how to use this

locale
required
string
Enum: "en" "nl"

Locale code

defaultGraphRange
required
string
allowAutoCloseThresholdIssues
boolean
Default: false
issueAutoClosingTriggerAmount
integer
Default: 1
issueAutoClosingTriggerUnitType
string
Default: "count"
measurementsExpirationDays
required
integer [ 1 .. 9999 ]
measurementsRetentionPolicyRange
string or null

Period to keep measurements in the database. If null, they are kept forever.

enforceTwoFactorAuthentication
required
boolean

Determines whether users need to have two factor authentication enabled in order to access this environment.

allowAutoCloseConnectivityIssues
required
boolean
required
object or null (fileFromServer)

Information about a stored file that can be used to download or inline it

object or null
defaultLandingPage
string
Default: "map"
Enum: "map" "analytics"
defaultLandingPageHashId
string or null
expiresAt
required
string or null <date-time>
createdAt
required
string <date-time>
{
  • "hashId": "f1a4w1",
  • "name": "My monitoring environment",
  • "mapLayers": [],
  • "boundingBox": {
    },
  • "fieldConfigurations": {
    },
  • "locale": "en",
  • "defaultGraphRange": "30d",
  • "allowAutoCloseThresholdIssues": false,
  • "issueAutoClosingTriggerAmount": 1,
  • "issueAutoClosingTriggerUnitType": "count",
  • "measurementsExpirationDays": 365,
  • "measurementsRetentionPolicyRange": "string",
  • "enforceTwoFactorAuthentication": false,
  • "allowAutoCloseConnectivityIssues": false,
  • "logo": {},
  • "theme": {
    },
  • "defaultLandingPage": "map",
  • "defaultLandingPageHashId": "string",
  • "expiresAt": null,
  • "createdAt": "2019-12-31T15:23Z"
}

environmentReportType

hashId
required
string
name
required
string
required
object

See the chapter on open fields on how to use this

type
required
string
Enum: "human" "device"
updatedAt
required
string <date-time>
deletedAt
required
string or null <date-time>
{
  • "hashId": "l19a7s",
  • "name": "Temperature and inclination",
  • "fieldConfigurations": {
    },
  • "type": "human",
  • "updatedAt": "2019-12-31T15:23Z",
  • "deletedAt": null
}

exportRequest

hashId
required
string
required
object or object or object or object
delimiter
required
string
Enum: "," ";"
rowDelimiter
required
string
Enum: "\n" "\r\n"
status
required
string
Enum: "waiting" "creating" "available" "cancelled" "timeoutError" "tooManyRowsError" "parsingError" "internalServerError"
percentage
number <float> [ 0 .. 1 ]

Percentage of completion

downloadUrl
string

Only available at status available

createdAt
required
string <date-time>
{}

fieldToServerFull

Any of
Any of
boolean

The values that can be stored in a form field

Example
true

fieldsToServerUpdate

Any of
additional property
(boolean or number or string or (any or null)) or Array of fileToServer (objects) (fieldToServerFull)

The values and files that can be stored in a form field.

{ }

fileFromServer

hashId
required
string
requestorType
required
string
requestorHashId
required
string
url
required
string
signature
required
string
name
required
string or null
mimeType
required
string or null
bytes
required
integer
md5
required
string
crc32
required
string
expiresAt
required
string or null <date-time>
{}

fileToServer

dataUrl
required
name
string

The filename including extension

{
  • "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "name": "red-dot.png"
}

grid

hashId
required
string
typeKey
required
string
Enum: "pinGroup" "pin"
name
required
string
fields
required
object

The field configuration is stored in the fieldConfigurations key of the monitoring environment object

deletedAt
required
string or null <date-time>
{
  • "hashId": "naud51",
  • "typeKey": "pinGroup",
  • "name": "My grid",
  • "fields": {
    },
  • "deletedAt": null
}

issue

hashId
required
string
userHashId
required
string or null
assignedUserHashId
required
string or null
title
required
string
pinGroupHashId
required
string
level
required
integer
Enum: 0 1 2
type
string
Default: "manual"
Enum: "manual" "connectivity" "measurement" "internal_channel"
doNotAutoClose
boolean
Default: false
closedAt
required
string or null <date-time>

If null, the issue is still open

createdAt
required
string <date-time>
updatedAt
required
string <date-time>
deletedAt
string or null <date-time>
{
  • "hashId": "c19aid",
  • "userHashId": "b45zo0",
  • "assignedUserHashId": null,
  • "title": "Temperature is too high",
  • "pinGroupHashId": "dao97",
  • "level": 0,
  • "type": "manual",
  • "doNotAutoClose": false,
  • "closedAt": null,
  • "createdAt": "2019-12-31T15:23Z",
  • "updatedAt": "2019-12-31T15:23Z",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

issueComment

hashId
required
string
userHashId
required
string or null

If null, the comment is created by an automated process

comment
required
string
Array of objects or null (fileFromServer) <= 10 items
Default: []
createdAt
required
string <date-time>
updatedAt
required
string <date-time>
deletedAt
string or null <date-time>
{
  • "hashId": "a9hhi0",
  • "userHashId": "b45zo0",
  • "comment": "This looks serious.",
  • "files": [ ],
  • "createdAt": "2019-12-31T15:23Z",
  • "updatedAt": "2019-12-31T15:23Z",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

label

hashId
required
string
name
required
string <= 255 characters
color
required
string^#[a-fA-F\d]{6}$

A hex color string. #, followed by six hexadecimal characters

createdAt
required
string <date-time>
updatedAt
required
string <date-time>
deletedAt
string or null <date-time>
{
  • "hashId": "u98a24",
  • "name": "Fix this month",
  • "color": "#ff0000",
  • "createdAt": "2019-12-31T15:23Z",
  • "updatedAt": "2019-12-31T15:23Z",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

log

hashId
required
string
userHashId
required
string or null
objectType
required
string or null
objectHashId
required
string or null
subObjectType
required
string or null
subObjectHashId
required
string or null
action
required
string <= 32 characters
required
object or null
createdAt
required
string <date-time>
{
  • "hashId": "op09a",
  • "userHashId": "b45zo0",
  • "objectType": "command",
  • "objectHashId": "ga9741s",
  • "subObjectType": null,
  • "subObjectHashId": null,
  • "action": "delete",
  • "diff": null,
  • "createdAt": "2019-12-31T15:23Z"
}

mapLayer

name
required
string
key
required
string
style
any

If provided, the layer renders from an external source. See https://docs.mapbox.com/mapbox-gl-js/style-spec/ for the Mapbox Style Specification. Only the layers and sources keys are currently supported.

namedStyle
string

If provided, a style predefined by withthegrid is used. Style is ignored if it is also provided.

{}

measurement

generatedAt
required
string <date-time>
channelIndex
required
integer or null

The channel of the installed device. When null, the measurement is not taken by a device but manually entered

channelMeasurementIndex
integer or null

Not null for device measurements. Represents the device channel this measurement is taken from, see the channels key in the device type object.

reportHashId
required
string
pinHashId
required
string or null
orderOfMagnitude
required
integer [ -128 .. 127 ]

The measured value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

significand
required
integer [ -2147483648 .. 2147483647 ]

The measured value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

performance
integer

-1: not compared to thresholds, 0: within thresholds, 1: outside serious thresholds but inside critical thresholds, 2: outside critical thresholds

{
  • "generatedAt": "2019-12-31T15:23Z",
  • "channelIndex": 0,
  • "channelMeasurementIndex": 0,
  • "reportHashId": "qoa978",
  • "pinHashId": "e13d57",
  • "orderOfMagnitude": -3,
  • "significand": -1500,
  • "performance": 0
}

measurementFilter

hashId
required
string
name
required
string <= 100 characters
description
required
string <= 255 characters
required
string or object
includePinsWithoutReports
required
boolean
createdAt
required
string <date-time>
updatedAt
required
string <date-time>
deletedAt
string or null <date-time>
{
  • "hashId": "k8gh3",
  • "name": "North",
  • "description": "Temperatures in the North",
  • "period": "lastMonth",
  • "includePinsWithoutReports": true,
  • "createdAt": "2019-12-31T15:23Z",
  • "updatedAt": "2019-12-31T15:23Z",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

measurementThreshold

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

issueDelayS
integer or null [ 0 .. 2147483647 ]
issueDelayCount
integer or null [ 0 .. 2147483647 ]
issueDelayIntervalType
string
Default: "atLeast"
Enum: "atLeast" "within"
boolean or boolean
Default: true
hashId
required
string
pinHashId
required
string
{
  • "criticallyLow": {
    },
  • "low": {
    },
  • "high": {
    },
  • "criticallyHigh": {
    },
  • "issueDelayS": 2147483647,
  • "issueDelayCount": 2147483647,
  • "issueDelayIntervalType": "atLeast",
  • "issueDelayResetCount": true,
  • "hashId": "tap192",
  • "pinHashId": "e13d57"
}

pin

hashId
required
string
pinGroupHashId
required
string
name
required
string
fields
required
object

The field configuration is stored in the fieldConfigurations key of the monitoring environment object

deviceFields
required
object

The field configuration is stored in the pinFieldConfigurations key of the channel key in the device type object

level
required
integer
Enum: 0 1 2

0: no serious or critical open issues, 1: one or more serious open issues and no critical open issues, 2: one or more critical open issues

edgeHashId
string or null
typeKey
string or null
deletedAt
required
string or null <date-time>
{
  • "hashId": "e13d57",
  • "pinGroupHashId": "dao97",
  • "name": "My port",
  • "fields": {
    },
  • "deviceFields": { },
  • "level": 0,
  • "edgeHashId": "string",
  • "typeKey": "string",
  • "deletedAt": "2019-12-31T15:23Z"
}

pinGroup

hashId
required
string
required
object or null
name
required
string
symbolKey
required
string
deviceFields
required
object

The field configuration is stored in the pinGroupFieldConfigurations key of the device type object

fields
required
object

The field configuration is stored in the fieldConfigurations key of the monitoring environment object

deviceLinkHashId
required
string or null

If null, there is no device installed at this location

level
required
integer
Enum: 0 1 2

0: no serious or critical open issues, 1: one or more serious open issues and no critical open issues, 2: one or more critical open issues

deviceLevel
required
integer
Enum: 0 1 2

0: no serious or critical open issues with the device, 1: one or more serious open issues and no critical open issues with the device, 2: one or more critical open issues with the device

mapLayer
required
string
mostRecentMeasurementAt
required
string or null <date-time>
deviceTypeDashboardIndex
required
integer

The index of the device type dashboard for graphs

deletedAt
required
string or null <date-time>
{
  • "hashId": "dao97",
  • "geometry": {
    },
  • "name": "My location",
  • "symbolKey": "cp-pole",
  • "deviceFields": { },
  • "fields": {
    },
  • "deviceLinkHashId": null,
  • "level": 0,
  • "deviceLevel": 0,
  • "mapLayer": "myLayer",
  • "mostRecentMeasurementAt": null,
  • "deviceTypeDashboardIndex": 0,
  • "deletedAt": null
}

quantity

hashId
required
string
required
untranslatedString (string) or translations (object) (stringOrTranslations)
color
required
string^#[a-fA-F\d]{6}$

A hex color string. #, followed by six hexadecimal characters

unit
string or null <= 10 characters

Will be displayed with an SI-prefix (eg. k or M) if relevant

defaultOrderOfMagnitude
integer [ -128 .. 127 ]

Defines default order of magnitude to be selected at manual report form

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

issueDelayS
integer [ 0 .. 2147483647 ]
issueDelayCount
integer [ 0 .. 2147483647 ]
issueDelayIntervalType
string
Default: "atLeast"
Enum: "atLeast" "within"
boolean or boolean
Default: true
disableSiPrefixes
boolean
Default: false

Will disable SI-prefixes for this quantity if true

{
  • "hashId": "sajia1",
  • "name": "untranslated string",
  • "color": "#ff0000",
  • "unit": "K",
  • "defaultOrderOfMagnitude": -3,
  • "defaultCriticallyLowThreshold": {
    },
  • "defaultLowThreshold": {
    },
  • "defaultHighThreshold": {
    },
  • "defaultCriticallyHighThreshold": {
    },
  • "issueDelayS": 2147483647,
  • "issueDelayCount": 2147483647,
  • "issueDelayIntervalType": "atLeast",
  • "issueDelayResetCount": true,
  • "disableSiPrefixes": true
}

siNumber

orderOfMagnitude
required
integer [ -128 .. 127 ]
significand
required
integer [ -2147483648 .. 2147483647 ]
{
  • "orderOfMagnitude": 0,
  • "significand": 1500
}

stringOrTranslations

Any of
string (untranslatedString)
Example
"untranslated string"

supplier

hashId
required
string
name
required
string
enforceTwoFactorAuthentication
required
boolean

Determines whether users need to have two factor authentication enabled in order to access this environment.

required
object or null (fileFromServer)

Information about a stored file that can be used to download or inline it

object or null
createdAt
required
string <date-time>
{
  • "hashId": "f1a4w1",
  • "name": "My connectivity environment",
  • "enforceTwoFactorAuthentication": false,
  • "logo": {},
  • "theme": {
    },
  • "createdAt": "2019-12-31T15:23Z"
}

supplierCertificate

hashId
required
string
name
required
string
certificate
required
string

A Base64 encoded intermediate certificate. Should be used to create device certificates.

createdAt
required
string <date-time>
{
  • "hashId": "v19a12",
  • "name": "My certificate",
  • "certificate": "-----BEGIN CERTIFICATE-----\n MIIBNzCB3gIBATAKBggqhkjOPQQDAjAkMREwDwYDVQQKDAhzdXBwbGllcjEPMA0G\n A1UEAwwGeGQycmQ0MB4XDTIwMDIyNDEzNTQwOVoXDTIxMDIyMzEzNTQwOVowLDEP\n MA0GA1UECgwGZGV2aWNlMRkwFwYDVQQDDBB1bnFpZSBpZGVudGlmaWVyMFkwEwYH\n KoZIzj0CAQYIKoZIzj0DAQcDQgAEUPyQwLuDlKw7CA41ADhxXRvD3n9ZFF0XCeI9\n OAgRIgl2mGmnO31wX1DD4weZoB2pswCBrC39FpyHgIz6LK10PzAKBggqhkjOPQQD\n AgNIADBFAiEAyz0Ha4eFfebqSoES4vxguipSHmR/zN8KjEEie7xpqo8CICFS5NWG\n iaT6xhGfChGbQjpmQQYYabau8Ons8F2JNyLu\n -----END CERTIFICATE-----\n ",
  • "createdAt": "2019-12-31T15:23Z"
}

supplierCredential

hashId
required
string
name
required
string
{
  • "hashId": "w5dshc",
  • "name": "My credential"
}

supplierReportType

hashId
required
string
required
untranslatedString (string) or translations (object) (stringOrTranslations)
required
object

See the chapter on open fields on how to use this

deletedAt
required
string or null <date-time>
{
  • "hashId": "l19a7s",
  • "name": "untranslated string",
  • "fieldConfigurations": {
    },
  • "deletedAt": null
}

supplierWebhook

hashId
required
string
name
required
string <= 255 characters
createdAt
required
string <date-time>
{
  • "hashId": "z812a63",
  • "name": "My webhook",
  • "createdAt": "2019-12-31T15:23Z"
}

threshold

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

required
object or null (siNumber)

Significant number. Its value is significand * 10 ^ orderOfMagnitude. It has as many significant figures as the significand has (except when the significand is 0, then the number of significant figures is not defined)

issueDelayS
integer or null [ 0 .. 2147483647 ]
issueDelayCount
integer or null [ 0 .. 2147483647 ]
issueDelayIntervalType
string
Default: "atLeast"
Enum: "atLeast" "within"
boolean or boolean
Default: true
{
  • "criticallyLow": {
    },
  • "low": {
    },
  • "high": {
    },
  • "criticallyHigh": {
    },
  • "issueDelayS": 2147483647,
  • "issueDelayCount": 2147483647,
  • "issueDelayIntervalType": "atLeast",
  • "issueDelayResetCount": true
}

translations

en
string
nl
string
{
  • "en": "English string",
  • "nl": "Nederlandse string"
}

untranslatedString

string (untranslatedString)
"untranslated string"

updatableFieldConfigurations

Array (<= 50 items)
existingKey
string^[a-z][a-zA-Z\d]*$
required
object or object or object or object or object or object or object or object or object or object or object or object or object or object

Defines which data can be stored in form fields.

[
  • {
    }
]

user

hashId
required
string
email
required
string or null <email>

Is null for machine accounts

name
required
string <= 255 characters
timezone
required
string

A IANA zone or a fixed-offset name of the form 'UTC+3', or the strings 'utc'.

locale
string
Default: "en"
Enum: "en" "nl"

Locale code

phone
string or null
company
string or null
rights
Array of strings <= 12 items
Items Enum: "READ" "STATIC" "ISSUES" "AUDIT_TRAIL" "USERS" "EXPORT" "SENSORS" "REPORTS" "THRESHOLDS" "IMPORT" "ENVIRONMENT_ADMIN" "ADMIN"

See the getting started section about rights

twoFactorAuthenticationEnabled
required
boolean or null

Is true if user has 2FA enabled

lastFeatureUpdateSeen
required
number <float> [ 0 .. 32767 ]

The last feature update seen

federatedAuthentication
required
boolean
Default: false

Is true if user is authenticated through a federated identity provider

{
  • "hashId": "b45zo0",
  • "email": "info@acme.com",
  • "name": "John Doe",
  • "timezone": "Europe/Amsterdam",
  • "locale": "en",
  • "phone": "string",
  • "company": "string",
  • "rights": [
    ],
  • "twoFactorAuthenticationEnabled": true,
  • "lastFeatureUpdateSeen": 32767,
  • "federatedAuthentication": false
}

userEnvironmentSettings

notificationLevel
required
number or null <float>
Enum: 0 1 2

The user is subscribed to every issue created on locations in this environment (0), when the issue gets serious (1) or when the issue gets critical (2). If null, the user is not automatically subscribed to new issues.

defaultAnalyticsPanelHashId
required
string or null
defaultLandingPage
string or null

The default landing page for this environment and user. If null, the default landing page is the global default for environment.

lastAccessedAt
required
string or null <date-time>
required
object or null
required
object or null
{
  • "notificationLevel": 0,
  • "defaultAnalyticsPanelHashId": "7usgt",
  • "defaultLandingPage": "map",
  • "lastAccessedAt": "2019-12-31T15:23Z",
  • "settings": {
    },
  • "autosaveSettings": {
    }
}

userSubscription

hashId
required
string
objectType
required
string
Enum: "supplierReportType" "deviceType" "supplierWebhook" "supplierCertificate"
objectHashId
required
string
lastNotification
required
string or null <date-time>
alertsSinceLastNotification
required
integer
createdAt
required
string <date-time>
{
  • "hashId": "dfa1p",
  • "objectType": "deviceType",
  • "objectHashId": "wasd2",
  • "lastNotification": "2020-01-31T11:17Z",
  • "alertsSinceLastNotification": 0,
  • "createdAt": "2019-12-31T15:23Z"
}

webRequest

hashId
required
string
incoming
required
boolean
createdAt
required
string <date-time>
required
object
required
object or null
{
  • "hashId": "1a532q",
  • "incoming": true,
  • "createdAt": "2019-12-31T15:23Z",
  • "request": {
    },
  • "response": {
    }
}