Skip to content

Api rest documentation

Scout's data visualization features can be accessed in the website through standard login authentication. If you want to add data to the platform you must create an app token.

An app token is an alternative authentication method to Username / Password. This authentication system is tied to an account and allows you to perform read / write operations on the entities contained in that account, mainly assets, devices, gateways and metrics.

App token creation from website

Go to projects section and click on the project you want to create an app app_token_1_projects.png

On the top menu click on Apps app_token_2_apps.png

Click on "Add app" button app_token_3_add_app.png

Add a name to your app app_token_4_name.png

Click on copy and close app_token_5_copy.png

With this, your api token will be copied to the clipboard, we recommend to store it on a file as it will be needed to authenticate your API requests.

App token creation from api

If you want to create an app token from the API you must make a POST request to the endpoint /api/v2/accounts/{accountId}/keys with the following parameters:

  • accountId: id of the account you want to create the app
  • Authentication header: Bearer JSON Web Token obtained from the login endpoint
  • the following body: 
        {
        "app": {
            "name": "string"
        }
    }
  • the call will return the following body: 
    {
  "key": {
    "app": {
      "id": "<UUID>",
      "name": "string"
    },
    "id": "<UUID>",
    "secret": "string"
  }
}
    Here we want the "secret" field, which contains the app token needed to perforn the API requests

Swagger overview

Our documentation provides a swagger page that allows the users to perform requests and see the resulting output. To access the documentation go to the following URL: https://scout.circutor.com/api/v2/docs/index.html

The first thing you will see is a list of endpoints swagger_1_overview.png

When clicking on an endpoint you will see a list of the fields that the endpoint requires swagger_2_endpoints.png

In order to execute the request, click on Try it out, fill the required fields and click execute. If the request goes correctly you will see the response body with te result swagger_3_results.png

Swagger use case example

With our app token we can use the endpoints listed in the Swagger documentation and start making requests to the API.

In this example we will show you how to add metrics to an asset and retrieve them.

Retrieve asset information

Go to the endpoint GET /api/v2/assets, add your token on the field X-API-KEY, set recursive to true and execute the request, you will get the all the asses on the account. Copy the asset id in which you want to add metrics

Insert metrics

Go to the endpoint POST /api/v2/assets/{assetId}/metricsv3/raw/batch

Add your X-API-KEY and the assetID of the previous step, then add the metrics in the body section, e.g. 

{
  "metrics": [
    {
      "data": {
        "P_CON_TOT_ENERGY": 113.5,
        "V_AN": 22
      },
      "ts": "2024-10-23T15:00:00+00:00"
    }
  ]
}

Click execute and check the response body has status "OK" example_2_post.png

Retrieve metrics

Go to the endpoint GET /api/v2/assets/{assetId}/metricsv3/raw add your X-API-KEY, assetID, from, to and vars, e.g.: example_2_get.png

Click execute and the response should have the metrics you added