Skip to content

Insight API Specification v1.0.1

Access functions, data and configuration for the ProGlove Insight Platform

The OpenAPIv3 Specification File for this API can be downloaded here

Authentication

  • API Key (EndpointAuthorizer)
    • Parameter Name: Authorization, in: header. Use the IdToken supplied by the Authorization response (see Authentication) as the value of the authorization header."

Events calls

CORS support

Code samples

OPTIONS /{customer_id}/events/export/tasks/{task} HTTP/1.1

OPTIONS /{customer_id}/events/export/tasks/{task}

Enable CORS

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

List of Events

Code samples

GET /{customer_id}/events HTTP/1.1

Accept: application/json

GET /{customer_id}/events

Lists events. By default, it gets events from the last 24 hours.

Parameters

Name In Type Required Description
customer_id path number true none
start_time_millis query number false Start time filtering. If not specified, default is one day before now. In milliseconds since the epoch.
end_time_millis query number false End time filtering. If not specified, default is now. In milliseconds since the epoch.
next_token query string false Used to get the next page of events, if one exists.
next_key query string false DEPRECATED. Used to get the next page of events, if one exists. Alternative to next_token.
limit query number false The maximum number of events to render. Default (and max possible value) is 500.
gateway_id query string false The gateway id for which to retrieve events. Only events which contain this id will be returned. Please note that if this parameter is used, no pagination will occur.

Example responses

200 Response

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "class": "event",
      "type": "scan",
      "created": 1557220259,
      "scan_code": "1234567890",
      "scan_duration": 2.34,
      "scan_decode_symbology": "QR_CODE",
      "device_id": "M2MR141204452",
      "device_battery": 93,
      "device_firmware": "0.0.1",
      "device_temperature": 93,
      "gateway_id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
      "gateway_usecase": "Picking",
      "gateway_station": "Station3",
      "metrics_worker_steps": 1
    }
  ],
  "links": {
    "next": "/gateways?next_token=11234"
  },
  "metadata": {
    "description": "string",
    "size": 23,
    "filters": [
      {
        "name": "start_time_millis",
        "value": 1557220259000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK The list of events. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Enumerated Values
Property Value
class device
class event
class gateway
class job_config
class device_config
class event
type scan

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Export events to file

Code samples

GET /{customer_id}/events/export HTTP/1.1

Accept: application/json

GET /{customer_id}/events/export

Exports multiple events. By default, it gets events from today. Returns a shortlived URL to download the created file.

Parameters

Name In Type Required Description
customer_id path string true none
start_time_millis query number false Start time filtering. If not specified, default is one day before now. In milliseconds since the epoch.
end_time_millis query number false End time filtering. If not specified, default is now. In milliseconds since the epoch.

Example responses

201 Response

{
  "download_link": "string"
}

Responses

Status Meaning Description Schema
201 Created A link to a list of events. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» download_link string true none A short lived link to retrieve the created file

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
201 Access-Control-Allow-Origin string none
201 Access-Control-Allow-Methods string none
201 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Trigger an asynchronous export of events

Code samples

POST /{customer_id}/events/export/tasks HTTP/1.1

Accept: application/json

POST /{customer_id}/events/export/tasks

Exports multiple events. By default, it gets events from today. Returns a shortlived URL to download the created file.

Parameters

Name In Type Required Description
customer_id path string true none
start_time_millis query number false Start time filtering. If not specified, default is one day before now. In milliseconds since the epoch.
end_time_millis query number false End time filtering. If not specified, default is now. In milliseconds since the epoch.

Example responses

202 Response

{
  "task": "97d67fdc-34b8-4c39-bba4-d8ef13907a2f",
  "requested": "2021-01-21T07:24:29.858633"
}

Responses

Status Meaning Description Schema
202 Accepted Export processing in background. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 202

Name Type Required Restrictions Description
» task string true none The id of the associated export task for reference.
» requested string(date-time) true none Timestamp of accepting the task

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
202 Access-Control-Allow-Origin string none
202 Access-Control-Allow-Methods string none
202 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Retrieve previously triggered event export results

Code samples

GET /{customer_id}/events/export/tasks/{task} HTTP/1.1

Accept: application/json

GET /{customer_id}/events/export/tasks/{task}

Retrieve the status of an asynchronous run event export tasks. If the export has finished successfully and the result is still available a shortlived URL to download the created file is part of the response.

Parameters

Name In Type Required Description
task path string true none

Example responses

200 Response

{
  "task": "97d67fdc-34b8-4c39-bba4-d8ef13907a2f",
  "completed": true,
  "status": "SUCCESSFUL",
  "download_link": "string"
}

Responses

Status Meaning Description Schema
200 OK Status of the export task. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» task string true none The id of the associated export task for reference.
» completed boolean true none Whether the task has finished processing (simplification of the status field, ignoring the outcome)
» status string true none The status of the requested export task. If SUCCESSFUL the task completed with exporting the requested events. If PENDING the client should back off and try again later.
» download_link string false none A short lived (currently 5 minutes) link to retrieve the created file. This is only part of the response if the export has finished successfully. To recreate the link the endpoint needs to be called again.
Enumerated Values
Property Value
status SUCCESSFUL
status FAILED
status PENDING

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Connectivity devices calls

CORS support

Code samples

OPTIONS /{customer_id}/create-provisioning-package HTTP/1.1

OPTIONS /{customer_id}/create-provisioning-package

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

List of Connectivity devices (gateways).

Code samples

GET /{customer_id}/gateways HTTP/1.1

Accept: application/json

GET /{customer_id}/gateways

Parameters

Name In Type Required Description
next_token query string false Used to get the next page of Connectivity devices (gateways), if one exists.
limit query string false The maximum number of Connectivity devices (gateways) to render. Default (and max possible value) is 500.
customer_id path string true none

Example responses

200 Response

{
  "items": [
    {
      "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
      "model": "Samsung Galaxy S8",
      "manufacturer": "Proglove",
      "class": "gateway",
      "type": "stationary",
      "firmware": "0.0.1",
      "created": 0,
      "last_updated": 0,
      "usecase": "Picking",
      "station": "Station3",
      "thing_name": "Gateway1",
      "name": "Gateway1",
      "connectivity_status": "NOT_REGISTERED"
    }
  ],
  "links": {
    "next": "/gateways?next_token=11234"
  },
  "metadata": {
    "description": "string",
    "size": 23,
    "filters": [
      {
        "name": "start_time_millis",
        "value": 1557220259000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK List of Connectivity devices (gateways). Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Enumerated Values
Property Value
class gateway
type stationary
type mobile
connectivity_status NOT_REGISTERED
connectivity_status REGISTERING
connectivity_status ACTIVE
connectivity_status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Creates a new Connectivity device (gateway).

Code samples

POST /{customer_id}/gateways HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/gateways

Body parameter

{
  "usecase": "Picking",
  "station": "Station3",
  "name": "Gateway1"
}

Parameters

Name In Type Required Description
body body object false none
» usecase body string true Connectivity device (gateway) usecase.
» station body string true Connectivity device (gateway) station name.
» name body string true Connectivity device's (gateway's) displayed name.
customer_id path string true none

Example responses

201 Response

{
  "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "model": "Samsung Galaxy S8",
  "manufacturer": "Proglove",
  "class": "gateway",
  "type": "stationary",
  "firmware": "0.0.1",
  "created": 0,
  "last_updated": 0,
  "usecase": "Picking",
  "station": "Station3",
  "thing_name": "Gateway1",
  "name": "Gateway1",
  "connectivity_status": "NOT_REGISTERED"
}

Responses

Status Meaning Description Schema
201 Created The newly created gateway. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Gateway not found. Inline
409 Conflict Gateway already exists. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 201

A connectivity device which transmits data to the backend.

Name Type Required Restrictions Description
» id string true none Unique identifier for Connectivity device (Insight Mobile, Gateway).
» model string false none Connectivity device (gateway) model.
» manufacturer string false none Connectivity device (gateway) manufacturer.
» class string false none none
» type string false none Connectivity device (gateway) type.
» firmware string false none Connectivity device (gateway) firmware.
» created number false none Time of Connectivity device's (gateway's) creation in milliseconds since the epoch.
» last_updated number false none Time of Connectivity device's (gateway's) last update in milliseconds since the epoch.
» usecase string true none Connectivity device (gateway) usecase.
» station string true none Connectivity device (gateway) station name.
» thing_name string false none Connectivity device's (gateway's) internal ID.
» name string true none Connectivity device's (gateway's) displayed name.
» connectivity_status string false none Connectivity state of the gateway.

- NOT_REGISTERED: after a gateway was created
- REGISTERING: registration file can be downloaded
- ACTIVE: a message has been sent from the Connectivity Device to Backend within the last 2 hours
- INACTIVE: for more than 2 hours the backend has not received any message anymore
and backend has already received scans from connectivity device before
Enumerated Values
Property Value
class gateway
type stationary
type mobile
connectivity_status NOT_REGISTERED
connectivity_status REGISTERING
connectivity_status ACTIVE
connectivity_status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 409

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
201 Access-Control-Allow-Origin string none
201 Access-Control-Allow-Methods string none
201 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
409 Access-Control-Allow-Origin string none
409 Access-Control-Allow-Methods string none
409 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Create a set of Connectivity devices (gateways).

Code samples

POST /{customer_id}/gateways/bulk-create HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/gateways/bulk-create

Body parameter

{
  "gateways": [
    {
      "usecase": "Picking",
      "station": "Station3",
      "name": "Gateway1"
    }
  ]
}

Parameters

Name In Type Required Description
body body object true none
» gateways body [object] true none
»» usecase body string true Connectivity device (gateway) usecase.
»» station body string true Connectivity device (gateway) station name.
»» name body string true Connectivity device's (gateway's) displayed name.
customer_id path string true none

Example responses

201 Response

[
  {
    "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
    "model": "Samsung Galaxy S8",
    "manufacturer": "Proglove",
    "class": "gateway",
    "type": "stationary",
    "firmware": "0.0.1",
    "created": 0,
    "last_updated": 0,
    "usecase": "Picking",
    "station": "Station3",
    "thing_name": "Gateway1",
    "name": "Gateway1",
    "connectivity_status": "NOT_REGISTERED"
  }
]

Responses

Status Meaning Description Schema
201 Created A list of created gateways. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Gateway not found. Inline
409 Conflict Gateway already exists. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» id string true none Unique identifier for Connectivity device (Insight Mobile, Gateway).
» model string false none Connectivity device (gateway) model.
» manufacturer string false none Connectivity device (gateway) manufacturer.
» class string false none none
» type string false none Connectivity device (gateway) type.
» firmware string false none Connectivity device (gateway) firmware.
» created number false none Time of Connectivity device's (gateway's) creation in milliseconds since the epoch.
» last_updated number false none Time of Connectivity device's (gateway's) last update in milliseconds since the epoch.
» usecase string true none Connectivity device (gateway) usecase.
» station string true none Connectivity device (gateway) station name.
» thing_name string false none Connectivity device's (gateway's) internal ID.
» name string true none Connectivity device's (gateway's) displayed name.
» connectivity_status string false none Connectivity state of the gateway.

- NOT_REGISTERED: after a gateway was created
- REGISTERING: registration file can be downloaded
- ACTIVE: a message has been sent from the Connectivity Device to Backend within the last 2 hours
- INACTIVE: for more than 2 hours the backend has not received any message anymore
and backend has already received scans from connectivity device before
Enumerated Values
Property Value
class gateway
type stationary
type mobile
connectivity_status NOT_REGISTERED
connectivity_status REGISTERING
connectivity_status ACTIVE
connectivity_status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 409

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
201 Access-Control-Allow-Origin string none
201 Access-Control-Allow-Methods string none
201 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
409 Access-Control-Allow-Origin string none
409 Access-Control-Allow-Methods string none
409 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Prepare Connectivity device's (gateways's) setup

Code samples

POST /{customer_id}/gateways/{gateway_id}/prepare-provisioning HTTP/1.1

Accept: application/json

POST /{customer_id}/gateways/{gateway_id}/prepare-provisioning

Generates the Connectivity device's (gateways's) certificate and produces an identifier to be transmitted to the Connectivity device (gateway), for example via barcode. Can be called only once. Use a POST method to avoid browser caching

Parameters

Name In Type Required Description
customer_id path string true none
gateway_id path string(format) true Gateway ID (UUID).

Example responses

200 Response

{
  "registration_path": "string",
  "token": "1BuWYYmmCO7K4baxJxB2KGJM11FCb1Ckdr5rR36LzDQ"
}

Responses

Status Meaning Description Schema
200 OK Information required to provision a Connectivity device (gateway). Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied or gateway does not exist. Inline
404 Not Found Gateway not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» registration_path string true none Endpoint to call when connecting the Connectivity device (gateway).
» token string true none Short lived token that is used to authorize calls from Connectivity devices (gateways) to retrieve their certificate.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Single Connectivity device's (gateway's) details

Code samples

GET /{customer_id}/gateways/{gateway_id} HTTP/1.1

Accept: application/json

GET /{customer_id}/gateways/{gateway_id}

Gets a single Connectivity device's information.

Parameters

Name In Type Required Description
customer_id path string true none
gateway_id path string true Gateway ID (the thing name).

Example responses

200 Response

{
  "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "model": "Samsung Galaxy S8",
  "manufacturer": "Proglove",
  "class": "gateway",
  "type": "stationary",
  "firmware": "0.0.1",
  "created": 0,
  "last_updated": 0,
  "usecase": "Picking",
  "station": "Station3",
  "thing_name": "Gateway1",
  "name": "Gateway1",
  "connectivity_status": "NOT_REGISTERED"
}

Responses

Status Meaning Description Schema
200 OK The requested gateway. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Gateway not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A connectivity device which transmits data to the backend.

Name Type Required Restrictions Description
» id string true none Unique identifier for Connectivity device (Insight Mobile, Gateway).
» model string false none Connectivity device (gateway) model.
» manufacturer string false none Connectivity device (gateway) manufacturer.
» class string false none none
» type string false none Connectivity device (gateway) type.
» firmware string false none Connectivity device (gateway) firmware.
» created number false none Time of Connectivity device's (gateway's) creation in milliseconds since the epoch.
» last_updated number false none Time of Connectivity device's (gateway's) last update in milliseconds since the epoch.
» usecase string true none Connectivity device (gateway) usecase.
» station string true none Connectivity device (gateway) station name.
» thing_name string false none Connectivity device's (gateway's) internal ID.
» name string true none Connectivity device's (gateway's) displayed name.
» connectivity_status string false none Connectivity state of the gateway.

- NOT_REGISTERED: after a gateway was created
- REGISTERING: registration file can be downloaded
- ACTIVE: a message has been sent from the Connectivity Device to Backend within the last 2 hours
- INACTIVE: for more than 2 hours the backend has not received any message anymore
and backend has already received scans from connectivity device before
Enumerated Values
Property Value
class gateway
type stationary
type mobile
connectivity_status NOT_REGISTERED
connectivity_status REGISTERING
connectivity_status ACTIVE
connectivity_status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Updates Connectivity device's (gateway's) attributes.

Code samples

PATCH /{customer_id}/gateways/{gateway_id} HTTP/1.1

Content-Type: application/json
Accept: application/json

PATCH /{customer_id}/gateways/{gateway_id}

Body parameter

{
  "usecase": "Picking",
  "station": "Station3",
  "name": "Gateway1"
}

Parameters

Name In Type Required Description
body body object true none
» usecase body string false Connectivity device (gateway) usecase.
» station body string false Connectivity device (gateway) station name.
» name body string false Connectivity device's (gateway's) displayed name.
customer_id path string true none
gateway_id path string true Gateway ID (the thing name).

Example responses

200 Response

{
  "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "model": "Samsung Galaxy S8",
  "manufacturer": "Proglove",
  "class": "gateway",
  "type": "stationary",
  "firmware": "0.0.1",
  "created": 0,
  "last_updated": 0,
  "usecase": "Picking",
  "station": "Station3",
  "thing_name": "Gateway1",
  "name": "Gateway1",
  "connectivity_status": "NOT_REGISTERED"
}

Responses

Status Meaning Description Schema
200 OK The updated gateway. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Gateway not found. Inline
409 Conflict Concurrent modification. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A connectivity device which transmits data to the backend.

Name Type Required Restrictions Description
» id string true none Unique identifier for Connectivity device (Insight Mobile, Gateway).
» model string false none Connectivity device (gateway) model.
» manufacturer string false none Connectivity device (gateway) manufacturer.
» class string false none none
» type string false none Connectivity device (gateway) type.
» firmware string false none Connectivity device (gateway) firmware.
» created number false none Time of Connectivity device's (gateway's) creation in milliseconds since the epoch.
» last_updated number false none Time of Connectivity device's (gateway's) last update in milliseconds since the epoch.
» usecase string true none Connectivity device (gateway) usecase.
» station string true none Connectivity device (gateway) station name.
» thing_name string false none Connectivity device's (gateway's) internal ID.
» name string true none Connectivity device's (gateway's) displayed name.
» connectivity_status string false none Connectivity state of the gateway.

- NOT_REGISTERED: after a gateway was created
- REGISTERING: registration file can be downloaded
- ACTIVE: a message has been sent from the Connectivity Device to Backend within the last 2 hours
- INACTIVE: for more than 2 hours the backend has not received any message anymore
and backend has already received scans from connectivity device before
Enumerated Values
Property Value
class gateway
type stationary
type mobile
connectivity_status NOT_REGISTERED
connectivity_status REGISTERING
connectivity_status ACTIVE
connectivity_status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 409

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
409 Access-Control-Allow-Origin string none
409 Access-Control-Allow-Methods string none
409 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Finishes connecting the Connectivity device (gateway)

Code samples

POST /provisioning HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /provisioning

Gets the Connectivity device's (gateway's) certificate. Can be called only once. Use a POST method to avoid browser caching issues. Called by the connectivity device to download certificates and finish the connection process. Usually triggered after scanning the provisioning barcode.

Body parameter

{
  "token": "1BuWYYmmCO7K4baxJxB2KGJM11FCb1Ckdr5rR36LzDQ"
}

Parameters

Name In Type Required Description
body body object true none
» token body string true Short lived token that is used to authorize calls from Connectivity devices (gateways) to retrieve their certificate.

Example responses

200 Response

{
  "mqtt_endpoint": "string",
  "mqtt_topic_prefix": "string",
  "certificate_common_name": "string",
  "gateway": {
    "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
    "model": "Samsung Galaxy S8",
    "manufacturer": "Proglove",
    "class": "gateway",
    "type": "stationary",
    "firmware": "0.0.1",
    "created": 0,
    "last_updated": 0,
    "usecase": "Picking",
    "station": "Station3",
    "thing_name": "Gateway1",
    "name": "Gateway1",
    "connectivity_status": "NOT_REGISTERED"
  },
  "pkcs12": "MIINYQIBAzCCDScGCSqGSIb3DQEHAaCCDRgEgg0UMIINED"
}

Responses

Status Meaning Description Schema
200 OK Returns the certificate, the certificate common name, and the connected Connectivity device (gateway). Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied or gateway does not exist. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» mqtt_endpoint string false none Address of the MQTT endpoint to which the Connectivity device (gateway) should connect
» mqtt_topic_prefix string false none The device should publish mqtt messages under the topic {mqtt_topic_prefix}/gateway/{gateway_id}.
» certificate_common_name string true none The common name of the certificate.
» gateway object true none Connectivity device (gateway) information.
»» id string true none Unique identifier for Connectivity device (Insight Mobile, Gateway).
»» model string false none Connectivity device (gateway) model.
»» manufacturer string false none Connectivity device (gateway) manufacturer.
»» class string false none none
»» type string false none Connectivity device (gateway) type.
»» firmware string false none Connectivity device (gateway) firmware.
»» created number false none Time of Connectivity device's (gateway's) creation in milliseconds since the epoch.
»» last_updated number false none Time of Connectivity device's (gateway's) last update in milliseconds since the epoch.
»» usecase string true none Connectivity device (gateway) usecase.
»» station string true none Connectivity device (gateway) station name.
»» thing_name string false none Connectivity device's (gateway's) internal ID.
»» name string true none Connectivity device's (gateway's) displayed name.
»» connectivity_status string false none Connectivity state of the gateway.

- NOT_REGISTERED: after a gateway was created
- REGISTERING: registration file can be downloaded
- ACTIVE: a message has been sent from the Connectivity Device to Backend within the last 2 hours
- INACTIVE: for more than 2 hours the backend has not received any message anymore
and backend has already received scans from connectivity device before
» pkcs12 string true none The entire certificate.
Enumerated Values
Property Value
class gateway
type stationary
type mobile
connectivity_status NOT_REGISTERED
connectivity_status REGISTERING
connectivity_status ACTIVE
connectivity_status INACTIVE

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Connecting multiple devices

Code samples

POST /{customer_id}/create-provisioning-package HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/create-provisioning-package

Provisions multiple Connectivity devices (gateways), and gets the download URLs of provisioning packages for each connectivity device. We use a POST method to avoid browser caching issues.

Body parameter

{
  "gateways": [
    {}
  ],
  "wifi": {
    "ssid": "string",
    "password": "string",
    "authentication_type": "string"
  }
}

Parameters

Name In Type Required Description
body body object true none
» gateways body [anyOf] true none
»» gateway_id body string false Unique identifier of a Connectivity device (gateway).
»» gateway_name body string false Connectivity device's (gateway's) displayed name.
»» anonymous body object false none
»» anonymous body object false none
» wifi body object false WiFi credentials.
»» ssid body string false none
»» password body string false none
»» authentication_type body string false none
customer_id path string true none

Example responses

200 Response

{
  "gateways": [
    {
      "gateway_id": "string",
      "package_url": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of provisioning package URLs. Inline
400 Bad Request Bad request. Inline
401 Unauthorized No authentication header found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Information required to create provisioning packages.

Name Type Required Restrictions Description
» gateways [object] true none none
»» gateway_id string false none none
»» package_url string false none none

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Asset Handling

CORS support

Code samples

OPTIONS /{customer_id}/generate-download-url HTTP/1.1

OPTIONS /{customer_id}/generate-download-url

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

Job Config calls

CORS support

Code samples

OPTIONS /{customer_id}/job-analysis HTTP/1.1

OPTIONS /{customer_id}/job-analysis

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

List of job configurations.

Code samples

GET /{customer_id}/job-configs HTTP/1.1

Accept: application/json

GET /{customer_id}/job-configs

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

200 Response

{
  "items": [
    {
      "job_config_id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
      "job_name": "Packing job 1",
      "created": 0,
      "last_updated": 0,
      "start_barcode": "1234",
      "end_barcode": "5678",
      "gateway_ids": [
        "string"
      ],
      "class": "jobconfig",
      "version": 0
    }
  ],
  "links": {
    "next": "/gateways?next_token=11234"
  },
  "metadata": {
    "description": "string",
    "size": 23,
    "filters": [
      {
        "name": "start_time_millis",
        "value": 1557220259000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK List of job configurations. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
200 ETag integer none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Creates a new job configuration.

Code samples

POST /{customer_id}/job-configs HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/job-configs

Body parameter

{
  "job_name": "Packing job 1",
  "start_barcode": "1234",
  "end_barcode": "5678",
  "gateway_ids": [
    "string"
  ]
}

Parameters

Name In Type Required Description
body body object true none
» job_name body string true The unique name of the job configuration.
» start_barcode body string true The string that the start barcode begins with. This marks the start of the job.
» end_barcode body string true The string that the end barcode begins with. This marks the end of the job.
» gateway_ids body [string] true The array of gateway ids (strings) that this job is associated with.
customer_id path string true none

Example responses

201 Response

{
  "job_config_id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "job_name": "Packing job 1",
  "created": 0,
  "last_updated": 0,
  "start_barcode": "1234",
  "end_barcode": "5678",
  "gateway_ids": [
    "string"
  ],
  "class": "jobconfig",
  "version": 0
}

Responses

Status Meaning Description Schema
201 Created The newly created job configuration. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 201

A configuration for a job, including start and end barcode.

Name Type Required Restrictions Description
» job_config_id string true none Unique identifier for the job configuration.
» job_name string true none Unique name of job.
» created number true none Time at which the job configuration was created in milliseconds since the epoch.
» last_updated number true none Time at which job configuration was last updated in milliseconds since the epoch.
» start_barcode string true none The string that the start barcode begins with. This marks the start of the job.
» end_barcode string true none The string that the end barcode begins with. This marks the end of the job.
» gateway_ids [string] true none The array of gateway ids (strings) that this job is associated with.
» class string true none none
» version integer true none The version of the job config

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
201 Access-Control-Allow-Origin string none
201 Access-Control-Allow-Methods string none
201 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Get the details of a specific job configuration.

Code samples

GET /{customer_id}/job-configs/{job_config_id} HTTP/1.1

Accept: application/json

GET /{customer_id}/job-configs/{job_config_id}

Parameters

Name In Type Required Description
customer_id path string true none
job_config_id path string(format) true Job ID (UUID).

Example responses

200 Response

{
  "job_config_id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "job_name": "Packing job 1",
  "created": 0,
  "last_updated": 0,
  "start_barcode": "1234",
  "end_barcode": "5678",
  "gateway_ids": [
    "string"
  ],
  "class": "jobconfig",
  "version": 0
}

Responses

Status Meaning Description Schema
200 OK The requested job configuration. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Job not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A configuration for a job, including start and end barcode.

Name Type Required Restrictions Description
» job_config_id string true none Unique identifier for the job configuration.
» job_name string true none Unique name of job.
» created number true none Time at which the job configuration was created in milliseconds since the epoch.
» last_updated number true none Time at which job configuration was last updated in milliseconds since the epoch.
» start_barcode string true none The string that the start barcode begins with. This marks the start of the job.
» end_barcode string true none The string that the end barcode begins with. This marks the end of the job.
» gateway_ids [string] true none The array of gateway ids (strings) that this job is associated with.
» class string true none none
» version integer true none The version of the job config

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Delete a job configuration.

Code samples

DELETE /{customer_id}/job-configs/{job_config_id} HTTP/1.1

Accept: application/json

DELETE /{customer_id}/job-configs/{job_config_id}

Parameters

Name In Type Required Description
customer_id path string true none
job_config_id path string(format) true Job ID (UUID).

Example responses

401 Response

{
  "title": "Unauthorized",
  "details": "No Authorization header was provided"
}

Responses

Status Meaning Description Schema
204 No Content Confirmation that the job config has been deleted. None
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Job not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
204 Access-Control-Allow-Origin string none
204 Access-Control-Allow-Methods string none
204 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Executes a job analysis

Code samples

POST /{customer_id}/job-analysis HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/job-analysis

Runs a job analysis for the specific job config and specified timeframe. This is a proof-of-concept and is currently done on the fly, which may change.

Body parameter

{
  "job_config_id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "start_time": 1557220259000,
  "end_time": 155722026000
}

Parameters

Name In Type Required Description
body body object true none
» job_config_id body string true Unique identifier for the job configuration.
» start_time body number true Start time of the job analysis as milliseconds since the unix epoch..
» end_time body number true End time of the job analysis as milliseconds since the unix epoch.
customer_id path string true none

Example responses

200 Response

{
  "results": [
    {
      "gateway_id": "string",
      "jobs": [
        {
          "start_time": 1557220259000,
          "end_time": 1557220260000,
          "start_event_id": "string",
          "end_event_id": "string"
        }
      ]
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK The result of the job analysis. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Response wrapper of a job analysis.

Name Type Required Restrictions Description
» results [object] false none The array of jobs per gateway.
»» gateway_id string false none none
»» jobs [object] false none An array of jobs associated with the gateway.
»»» start_time number false none Start time of the job in milliseconds since the epoch.
»»» end_time number false none End time of the job in milliseconds since the epoch.
»»» start_event_id string false none The id of the event that marks the start of a job.
»»» end_event_id string false none The id of the event that marks the end of a job.

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Roles calls

CORS support

Code samples

OPTIONS /{customer_id}/roles HTTP/1.1

OPTIONS /{customer_id}/roles

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none
next_token query string false Used to get the next page of events, if one exists.
next_key query string false Used to get the next page of events, if one exists. Alternative to next_token.

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

Get information about roles.

Code samples

GET /{customer_id}/roles HTTP/1.1

Accept: application/json

GET /{customer_id}/roles

Parameters

Name In Type Required Description
customer_id path string true none
next_token query string false Used to get the next page of events, if one exists.
next_key query string false Used to get the next page of events, if one exists. Alternative to next_token.

Example responses

200 Response

{
  "items": [
    {
      "description": "string",
      "name": "ADMIN_ROLE",
      "permissions": [
        "gateways.create"
      ]
    }
  ],
  "links": {
    "next": "/gateways?next_token=11234"
  },
  "metadata": {
    "description": "string",
    "size": 23,
    "filters": [
      {
        "name": "start_time_millis",
        "value": 1557220259000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK List of roles. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Enumerated Values
Property Value
name ADMIN_ROLE
name USER_ROLE

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

User calls

CORS support

Code samples

OPTIONS /{customer_id}/users/{user_id} HTTP/1.1

OPTIONS /{customer_id}/users/{user_id}

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none
user_id path string true none

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

logged-in user info

Code samples

GET /{customer_id}/me HTTP/1.1

Accept: application/json

GET /{customer_id}/me

Gets information about itself.

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

200 Response

{
  "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "first_name": "Example",
  "last_name": "User",
  "email": "example@proglove.de",
  "created": 155722026000,
  "last_updated": 155722026000,
  "language": "English",
  "roles": [
    "ADMIN_ROLE"
  ],
  "permissions": [
    "event.read"
  ],
  "consent_general_terms": {
    "version": "1.2.3",
    "timestamp": 1585727114123
  },
  "consent_privacy_policy": {
    "version": "1.2.3",
    "timestamp": 1585727114123
  }
}

Responses

Status Meaning Description Schema
200 OK Information about the user. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A user that can log into and useqq the cloud platform.

Name Type Required Restrictions Description
» id string(uuid) true none The unique user ID of the user.
» first_name string false none The first name of the user.
» last_name string false none The last name of the user.
» email string true none The email address associated with the user.
» created number true none The time the user was created in milliseconds since the epoch.
» last_updated number true none The time the user was last updated n milliseconds since the epoch.
» language string false none none
» roles [string] true none none
» permissions [string] false none none
» consent_general_terms object¦null false none none
»» version string false none Semantic version number (semver) of the document to which the user
consented.
»» timestamp number false none number of milliseconds since the unix epoch of the consent
event (UTC time.)
» consent_privacy_policy object¦null false none none
»» version string false none Semantic version number (semver) of the document to which the user
consented.
»» timestamp number false none number of milliseconds since the unix epoch of the consent
event (UTC time.)

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Creates a new user

Code samples

POST /{customer_id}/users HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/users

Creates a new user given a first name, last name, role, and email address.

Body parameter

{
  "first_name": "John",
  "last_name": "Doe",
  "role": "USER_ROLE",
  "email": "john.doe@example.com"
}

Parameters

Name In Type Required Description
body body object true none
» first_name body string true First name of the new user.
» last_name body string true Last name of the new user.
» role body string true Role of the new user.
» email body string true Email address associated with the new user.
customer_id path string true none

Enumerated Values

Parameter Value
» role USER_ROLE
» role ADMIN_ROLE

Example responses

200 Response

{
  "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "first_name": "Example",
  "last_name": "User",
  "email": "example@proglove.de",
  "created": 155722026000,
  "last_updated": 155722026000,
  "language": "English",
  "roles": [
    "ADMIN_ROLE"
  ],
  "permissions": [
    "event.read"
  ],
  "consent_general_terms": {
    "version": "1.2.3",
    "timestamp": 1585727114123
  },
  "consent_privacy_policy": {
    "version": "1.2.3",
    "timestamp": 1585727114123
  }
}

Responses

Status Meaning Description Schema
200 OK The newly created user. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
409 Conflict User with email already exists. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A user that can log into and useqq the cloud platform.

Name Type Required Restrictions Description
» id string(uuid) true none The unique user ID of the user.
» first_name string false none The first name of the user.
» last_name string false none The last name of the user.
» email string true none The email address associated with the user.
» created number true none The time the user was created in milliseconds since the epoch.
» last_updated number true none The time the user was last updated n milliseconds since the epoch.
» language string false none none
» roles [string] true none none
» permissions [string] false none none
» consent_general_terms object¦null false none none
»» version string false none Semantic version number (semver) of the document to which the user
consented.
»» timestamp number false none number of milliseconds since the unix epoch of the consent
event (UTC time.)
» consent_privacy_policy object¦null false none none
»» version string false none Semantic version number (semver) of the document to which the user
consented.
»» timestamp number false none number of milliseconds since the unix epoch of the consent
event (UTC time.)

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 409

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
409 Access-Control-Allow-Origin string none
409 Access-Control-Allow-Methods string none
409 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

List of users

Code samples

GET /{customer_id}/users HTTP/1.1

Accept: application/json

GET /{customer_id}/users

Gets a list of all users.

Parameters

Name In Type Required Description
next_token query string false Used to get the next page of events, if one exists.
next_key query string false Used to get the next page of events, if one exists. Alternative to next_token.
customer_id path string true none

Example responses

200 Response

{
  "items": [
    {
      "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
      "first_name": "Example",
      "last_name": "User",
      "email": "example@proglove.de",
      "created": 155722026000,
      "last_updated": 155722026000,
      "language": "English",
      "roles": [
        "ADMIN_ROLE"
      ],
      "permissions": [
        "event.read"
      ],
      "consent_general_terms": {
        "version": "1.2.3",
        "timestamp": 1585727114123
      },
      "consent_privacy_policy": {
        "version": "1.2.3",
        "timestamp": 1585727114123
      }
    }
  ],
  "links": {
    "next": "/gateways?next_token=11234"
  },
  "metadata": {
    "description": "string",
    "size": 23,
    "filters": [
      {
        "name": "start_time_millis",
        "value": 1557220259000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK All the users associated with this customer. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Gets the user's details

Code samples

GET /{customer_id}/users/{user_id} HTTP/1.1

Accept: application/json

GET /{customer_id}/users/{user_id}

Gets information about a specific user.

Parameters

Name In Type Required Description
customer_id path string true none
user_id path string true none

Example responses

200 Response

{
  "id": "919ebc9d-9788-4f08-93db-e238c5eaa69a",
  "first_name": "Example",
  "last_name": "User",
  "email": "example@proglove.de",
  "created": 155722026000,
  "last_updated": 155722026000,
  "language": "English",
  "roles": [
    "ADMIN_ROLE"
  ],
  "permissions": [
    "event.read"
  ],
  "consent_general_terms": {
    "version": "1.2.3",
    "timestamp": 1585727114123
  },
  "consent_privacy_policy": {
    "version": "1.2.3",
    "timestamp": 1585727114123
  }
}

Responses

Status Meaning Description Schema
200 OK Information about the user. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found User not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A user that can log into and useqq the cloud platform.

Name Type Required Restrictions Description
» id string(uuid) true none The unique user ID of the user.
» first_name string false none The first name of the user.
» last_name string false none The last name of the user.
» email string true none The email address associated with the user.
» created number true none The time the user was created in milliseconds since the epoch.
» last_updated number true none The time the user was last updated n milliseconds since the epoch.
» language string false none none
» roles [string] true none none
» permissions [string] false none none
» consent_general_terms object¦null false none none
»» version string false none Semantic version number (semver) of the document to which the user
consented.
»» timestamp number false none number of milliseconds since the unix epoch of the consent
event (UTC time.)
» consent_privacy_policy object¦null false none none
»» version string false none Semantic version number (semver) of the document to which the user
consented.
»» timestamp number false none number of milliseconds since the unix epoch of the consent
event (UTC time.)

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Deletes user

Code samples

DELETE /{customer_id}/users/{user_id} HTTP/1.1

Accept: application/json

DELETE /{customer_id}/users/{user_id}

Hard deletes the specified user.

Parameters

Name In Type Required Description
customer_id path string true none
user_id path string true none

Example responses

401 Response

{
  "title": "Unauthorized",
  "details": "No Authorization header was provided"
}

Responses

Status Meaning Description Schema
204 No Content The user has been deleted. None
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found User not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
204 Access-Control-Allow-Origin string none
204 Access-Control-Allow-Methods string none
204 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Update user

Code samples

PATCH /{customer_id}/users/{user_id} HTTP/1.1

Accept: application/json

PATCH /{customer_id}/users/{user_id}

Updates the information about a specific user.

Parameters

Name In Type Required Description
customer_id path string true none
user_id path string true none

Example responses

401 Response

{
  "title": "Unauthorized",
  "details": "No Authorization header was provided"
}

Responses

Status Meaning Description Schema
204 No Content Information about the user. None
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found User not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
204 Access-Control-Allow-Origin string none
204 Access-Control-Allow-Methods string none
204 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Consents calls

CORS support

Code samples

OPTIONS /{customer_id}/me/consents HTTP/1.1

OPTIONS /{customer_id}/me/consents

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

Lists all given consents

Code samples

GET /{customer_id}/me/consents HTTP/1.1

Accept: application/json

GET /{customer_id}/me/consents

Retrieves all given consents, can be filtered by type via query.

Parameters

Name In Type Required Description
type query string false The type of consents to retrieve the versions.
customer_id path string true none

Enumerated Values

Parameter Value
type PRIVACY_POLICY
type TERMS_AND_CONDITIONS_AGREEMENT
type CONNECTED_POLICY

Example responses

200 Response

{
  "privacy_policy": {
    "versions": [
      {
        "version": "1.2.3",
        "agreed_on": 0
      }
    ]
  },
  "terms_and_conditions_agreement": {
    "versions": [
      {
        "version": "1.2.3",
        "agreed_on": 0
      }
    ]
  },
  "connected_policy": {
    "versions": [
      {
        "version": "1.2.3",
        "agreed_on": 0
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK The list of consent versions. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Versions of consented agreements.

Name Type Required Restrictions Description
» privacy_policy object false none none
»» versions [object] true none none
»»» version string true none The version of the document the user agrees with.
»»» agreed_on integer true none none
» terms_and_conditions_agreement object false none none
»» versions [object] true none none
»»» version string true none The version of the document the user agrees with.
»»» agreed_on integer true none none
» connected_policy object false none none
»» versions [object] true none none
»»» version string true none The version of the document the user agrees with.
»»» agreed_on integer true none none

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Code samples

POST /{customer_id}/me/consents HTTP/1.1

Content-Type: application/json
Accept: application/json

POST /{customer_id}/me/consents

Body parameter

{
  "privacy_policy_version": "1.2.3",
  "terms_and_conditions_version": "1.2.3"
}
Name In Type Required Description
body body any true A JSON object containing consent information.
customer_id path string true none

Example responses

400 Response

{
  "title": "Unauthorized",
  "details": "No Authorization header was provided"
}
Status Meaning Description Schema
204 No Content The consent record is saved. None
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
204 Access-Control-Allow-Origin string none
204 Access-Control-Allow-Methods string none
204 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Unauthenticated calls

CORS support

Code samples

OPTIONS /auth-information HTTP/1.1

OPTIONS /auth-information

Enable CORS

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

Gets login information.

Code samples

GET /auth-information?id=string HTTP/1.1

Accept: application/json

GET /auth-information

Parameters

Name In Type Required Description
id query string true none

Example responses

200 Response

{
  "region": "eu-west-1",
  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  "user_pool_client_id": "oc4g1aud3boe65s616n2h5pok",
  "user_pool_id": "eu-west-1_2GTEAXIyw"
}

Responses

Status Meaning Description Schema
200 OK Information to be able to login. Inline
400 Bad Request Malformed request. Inline
404 Not Found Customer details not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» region string true none The AWS region where the user pool is located.
» customer_id string(uuid) true none none
» user_pool_client_id string true none The user pool web client id.
» user_pool_id string true none The user pool id.

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Devices calls

CORS support

Code samples

OPTIONS /{customer_id}/devices/{device_id} HTTP/1.1

OPTIONS /{customer_id}/devices/{device_id}

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none
device_id path string true Scanning device ID (UUID).

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

List of scanners.

Code samples

GET /{customer_id}/devices HTTP/1.1

Accept: application/json

GET /{customer_id}/devices

Parameters

Name In Type Required Description
next_token query string false Used to get the next page of devices, if one exists.
limit query string false The maximum number of devices to render. Default (and max possible value) is 500.
customer_id path string true none

Example responses

200 Response

{
  "items": [
    {
      "id": "M2MR101000000",
      "class": "device",
      "created": 0,
      "last_activity_time": 0,
      "last_updated": 0,
      "battery": 50,
      "firmware": "0.0.1",
      "model": "Mark",
      "manufacturer": "Workaround GmbH",
      "status": "ACTIVE"
    }
  ],
  "links": {
    "next": "/gateways?next_token=11234"
  },
  "metadata": {
    "description": "string",
    "size": 23,
    "filters": [
      {
        "name": "start_time_millis",
        "value": 1557220259000
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK List of devices. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Enumerated Values
Property Value
class device
status ACTIVE
status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Update scanner device data.

Code samples

PUT /{customer_id}/devices/{device_id} HTTP/1.1

Content-Type: application/json
Accept: application/json

PUT /{customer_id}/devices/{device_id}

Body parameter

{
  "status": "ACTIVE"
}

Parameters

Name In Type Required Description
body body object true none
» status body string true Activity status of a device.
customer_id path string true none
device_id path string true Scanning device ID (UUID).

Enumerated Values

Parameter Value
» status ACTIVE
» status INACTIVE

Example responses

200 Response

{
  "id": "M2MR101000000",
  "class": "device",
  "created": 0,
  "last_activity_time": 0,
  "last_updated": 0,
  "battery": 50,
  "firmware": "0.0.1",
  "model": "Mark",
  "manufacturer": "Workaround GmbH",
  "status": "ACTIVE"
}

Responses

Status Meaning Description Schema
200 OK The updated devices. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found Device not found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

A device that is able to scan.

Name Type Required Restrictions Description
» id string false none The serial number of the device.
» class string false none none
» created number false none Time at which the last message was send in milliseconds since the epoch.
» last_activity_time number false none Time at which the last message was send in milliseconds since the epoch.
» last_updated number false none Time at which the device status has been updated in milliseconds since the epoch.
» battery integer false none The battery level of the device.
» firmware string false none The firmware on which the device runs.
» model string false none The device model.
» manufacturer string false none The device manufacturer.
» status string false none The status of the scanning device.
Enumerated Values
Property Value
class device
status ACTIVE
status INACTIVE

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Device Config calls

CORS support

Code samples

OPTIONS /{customer_id}/device-configs/{device_config_id} HTTP/1.1

OPTIONS /{customer_id}/device-configs/{device_config_id}

Enable CORS

Parameters

Name In Type Required Description
customer_id path string true none
device_config_id path string true ID of a device config file.

Example responses

Responses

Status Meaning Description Schema
200 OK Default response for CORS method None

Response Schema

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none

Get lists of device configs metadata.

Code samples

GET /{customer_id}/device-configs HTTP/1.1

Accept: application/json

GET /{customer_id}/device-configs

Parameters

Name In Type Required Description
customer_id path string true none

Example responses

200 Response

{
  "configs": [
    {
      "id": "asrtdgh",
      "class": "device",
      "name": "very important config file.",
      "last_modified": 0,
      "created": 0,
      "file_size": 24
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK List of device configs metadata. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» configs [allOf] true none none

allOf

Name Type Required Restrictions Description
»» anonymous object false none none
»»» id string(uuid) true none none
»»» class string true none none

and

Name Type Required Restrictions Description
»» anonymous object false none none
»»» id string true none ID of a device config set by the client.
»»» name string false none Name of the device config file.
»»» last_modified number true none Time at which the device config is last modified.
»»» created number true none Time at which the device config is created.
»»» file_size number true none The size of the config file in bytes.
Enumerated Values
Property Value
class device
class event
class gateway
class job_config
class device_config

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Create or update a device config file.

Code samples

PUT /{customer_id}/device-configs/{device_config_id} HTTP/1.1

Content-Type: application/octet-stream
Accept: application/json
File-Name: string
Content-Type: string

PUT /{customer_id}/device-configs/{device_config_id}

Body parameter

string

Parameters

Name In Type Required Description
File-Name header string true none
Content-Type header string false none
body body string(binary) false none
customer_id path string true none
device_config_id path string true ID of a device config file.

Example responses

200 Response

{
  "id": "asrtdgh",
  "class": "device",
  "name": "very important config file.",
  "last_modified": 0,
  "created": 0,
  "file_size": 24
}

Responses

Status Meaning Description Schema
200 OK Device config file successfully created. Inline
400 Bad Request Malformed request. Inline
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 200

Metadata of a device config.

Name Type Required Restrictions Description

allOf

Name Type Required Restrictions Description
» anonymous object false none none
»» id string(uuid) true none none
»» class string true none none

and

Name Type Required Restrictions Description
» anonymous object false none none
»» id string true none ID of a device config set by the client.
»» name string false none Name of the device config file.
»» last_modified number true none Time at which the device config is last modified.
»» created number true none Time at which the device config is created.
»» file_size number true none The size of the config file in bytes.
Enumerated Values
Property Value
class device
class event
class gateway
class job_config
class device_config

Status Code 400

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
400 Access-Control-Allow-Origin string none
400 Access-Control-Allow-Methods string none
400 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Get a device config file.

Code samples

GET /{customer_id}/device-configs/{device_config_id} HTTP/1.1

Accept: text/plain

GET /{customer_id}/device-configs/{device_config_id}

Parameters

Name In Type Required Description
customer_id path string true none
device_config_id path string true ID of a device config file.

Example responses

200 Response

"string"

401 Response

{
  "title": "Unauthorized",
  "details": "No Authorization header was provided"
}

Responses

Status Meaning Description Schema
200 OK Device config file. string
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
404 Not Found No device config file found. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 404

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
200 Access-Control-Allow-Origin string none
200 Access-Control-Allow-Methods string none
200 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
404 Access-Control-Allow-Origin string none
404 Access-Control-Allow-Methods string none
404 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none

Delete a device configuration

Code samples

DELETE /{customer_id}/device-configs/{device_config_id} HTTP/1.1

Accept: application/json

DELETE /{customer_id}/device-configs/{device_config_id}

Parameters

Name In Type Required Description
customer_id path string true none
device_config_id path string true ID of a device config file.

Example responses

401 Response

{
  "title": "Unauthorized",
  "details": "No Authorization header was provided"
}

Responses

Status Meaning Description Schema
204 No Content Device configuration file has been deleted None
401 Unauthorized No authentication header found. Inline
403 Forbidden Access denied. Inline
500 Internal Server Error Internal Server Error. Inline

Response Schema

Status Code 401

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 403

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Status Code 500

Name Type Required Restrictions Description
» title string true none The title of the error.
» details string true none Gives more information about the failure reason.

Response Headers

Status Header Type Format Description
204 Access-Control-Allow-Origin string none
204 Access-Control-Allow-Methods string none
204 Access-Control-Allow-Headers string none
401 Access-Control-Allow-Origin string none
401 Access-Control-Allow-Methods string none
401 Access-Control-Allow-Headers string none
403 Access-Control-Allow-Origin string none
403 Access-Control-Allow-Methods string none
403 Access-Control-Allow-Headers string none
500 Access-Control-Allow-Origin string none
500 Access-Control-Allow-Methods string none
500 Access-Control-Allow-Headers string none