Data API V1.0

Click on the following link to open the Saveris Data API documentation.

The DATA API provides RESTful calls to an interface to retrieve data about HCCP or monitoring information. It is designed for developers who want to interact with the data programmatically.

The API is built using the OpenAPI 3.0.0 specification and follows the REST architectural style. It uses JSON for data exchange and supports standard HTTP response codes for successful and unsuccessful requests.

API Details

API Version: 1.0
License: Apache 2.0

For the terms of service, please visit Testo's website.

Base URL

The URL for this API is: https://data-api.REGION.ENV.savr.saveris.net/v1

The REGION and ENV in the URL should be replaced with the specific region and environment you are using. There are two environments available: "i" for integration and testing, and "p" for production. Furthermore we have three regions: "eu" for europe, "am" for america and "ap" for the apac region.

Security

The Data API uses Bearer token authentication. You should acquire a token and use it to authenticate your requests.

To get a token you need to authenticate using a /token endpoint of the Data API. Here you will just need to send your username and password in the body and you will receive the idToken.

API Endpoints

The API has several endpoints:

asynchronous /measurements: This endpoint supports the POST, GET and OPTIONS methods to retrieve a list of your measurements in a specific timeframe.
asynchronous /alarms: This endpoint supports the POST, GET and OPTIONS methods to retrieve a list of alarms in a timeframe.
asynchronous /tasks: This endpoint supports the POST, GET and OPTIONS methods to retrieve a list of all executed tasks items in a given timeframe.
/devices/properties: This endpoint supports the GET and OPTIONS methods to retrieve a list of your devices, sensors and channels including their properties.
/devices/status: This endpoint supports the GET and OPTIONS methods to retrieve a list of your devices, sensors and their status. This includes battery level and wifi level.
/tenants: This endpoint supports the GET and OPTIONS methods to retrieve a list of the tenants you are connected to.
/equipments: This endpoint supports the GET and OPTIONS methods to retrieve a list of all equipment.

Endpoints with the Asynchronous tag are asynchronous and have a special request flow to them (see section below).

Get data from asynchronous endpoints

Request Flow

Authenticate yourself against the API.
Send a POST request to /endpoint with optional parameters like the timeframe you are interested in and get a UUID of the request.
The user can now check the request status and results using the /endpoint/request_uuid API endpoint.
When the request status is Completed, the user gets the data urls to the dataset.
Download the dataset from the data URLs.

Requesting data

To request data, send a POST request to https://data-api.REGION.ENV.savr.saveris.net/v1/endpoint with the Authorization header set to Bearer IdToken obtained in the /v1/token endpoint (see Security section). The response will include a RequestUUID field, which you will use to check the status of your request:

{
   "Status": "Submitted",
   "RequestUUID: ": "your-random-uuid"
}

Checking request status and retrieving the dataset

To check the status of your request and retrieve the data, send a GET request to https://data-api.REGION.ENV.savr.saveris.net/v1/endpoint/your-random-uuid with the Authorization header set to Bearer IdToken obtained in the authentication step. The response will contain the status of your request:

{
   "Status": "In progress",
   "DataURLs: ": []
}

Once the data is ready, the response will include a pre-signed U

{
   "Status": "Completed",
   "DataURLs: ": ["your-pre-signed-url", "your-pre-signed-url",...]
}

Download your data directly from the pre-signed URL returned by the API.

Get REST calls on the endpoints

To get a list of the needed items, send a GET request to the specific endpoint. The API will return a JSON object containing an array of the items objects. Here is an example for the /equipments endpoint:

Request:

GET /equipments

Response:

{
  "equipments": [
    {
      "tenant_uuid": "string",
      "equipment_uuid": "string",
      "equipment_title": "string",
      "area_uuid": "string",
      "area_title": "string",
      "equipment_type_title": "string",
      "equipment_type_uuid": "string",
      "processed_at": "string",
      "last_modified_at": "string",
      "is_active": "string",
      "equipment_parts": [
        {
          "equipment_parts_uuid": "string",
          "equipment_parts_title": "string",
          "equipment_parts_purpose_title": "string",
          "equipment_parts_purpose_uuid": "string",
          "alarm_configurations": [
            {
              "limit_values_uuid": "string",
              "door_contact_delay_in_ms": "number",
              "alarm_delay": "number",
              "display_unit": "string",
              "measuring_rate": "number",
              "lower_violation": "number",
              "lower_warning": "number",
              "upper_violation": "number",
              "upper_warning": "number",
              "valid_from_time": "number",
              "valid_until_time": "number"
            }
          ]
        }
      ]
    }
  ]
}

CORS support

The API supports CORS (Cross-Origin Resource Sharing) to allow cross-domain communication. To enable CORS, the server returns the appropriate headers in the response.

Error Handling

The API uses standard HTTP status codes to indicate success or failure of an API request. In case of an error, the API will return a JSON object containing a status and a message property describing the error.

For example:

{
  "status": "Error",
  "message": "Error Message"
}