NAV
shell

Overview

Introduction

  ____               _ _ _    _        
 |  _ \ _ __ ___  __| (_) | _| |_ ___  
 | |_) | '__/ _ \/ _` | | |/ / __/ _ \ 
 |  __/| | |  __/ (_| | |   <| || (_) |
 |_|   |_|  \___|\__,_|_|_|\_\\__\___/ 

U.S. Region API Endpoint:
https://api.predikto.io

EU Region API Endpoint:
https://eu-api.predikto.io

Predikto provides APIs for the Predikto Enterprise Platform. The APIs enable you to integrate predictive analytics in to your application, and leverage the Predikto Enterprise Platform.

The Predikto API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors.

The REST API Reference documentation contains a comprehensive set of example requests and expected response payloads. You’d be well-advised to familiarize yourself with the API endpoints contained within this document.

Using these Docs

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Testing the API

We recommend the use of a client application for developer testing, as it will make generation of the HMAC authentication signature simpler. The authentication section contains a link to Postman, which is what our developers use internally.

Getting Help

If you run in to problems please contact us via the GitHub issue tracker. Documentation fixes and ideas for improvements are always welcome.

Predikto on Github

We have our own Github account that holds SDKS and utility libraries to get the most out of this API. Predikto Github

Authentication

API calls require HMAC authentication as a header within the request. HMAC is a keyed-hash authentication code that calculates a message authentication code (MAC) involving a cryptographic hash function in combination with a secret cryptographic key.

This authentication scheme protects your data and ensures that your secret keys stay secure.

All requests must be signed using your API Key and your Private API Secret.

Setting HMAC Authentication

In the Predikto REST API, HMAC authentication is set as a header in an HTTP request. The HTTP client signs the request by adding the following HTTP headers:

x-prd-signature: <HMACSignature>
x-prd-key: <APIKey>
x-prd-time: <Unix Timestamp In Seconds>
x-prd-nonce: <NONCE>

Creating the Authorization header

To create the authorization header, include the following attributes:

Each attribute value should be enclosed in double quotes.

Creating the Signature

The signature is a Base64-encoded binary HMAC-SHA256 digest generated from the following elements:

Example StringToSign:

StringToSign = '{"method":\"' + api_method + '\","x-prd-key":\"' 
+ api_key + '\","x-prd-nonce":\"' + nonce + '\","x-prd-time":\"' 
+ current_time + '\"}';

Things to look out for:

Testing with Postman

We recommend you first set up a development environment to test API signing and request/response lifecycle. We use Postman internally to test APIs.

A complete walkthrough on how to configure your environment can be found here: hmac_postman.

Sample Code

We have created an examples repository to help you get started with HMAC authentication. You can find them on the Predikto Github page, or go to them directly for the language of your choice:

Notification Concepts

The Predikto Enterprise Platform issues notifications on a recurring basis. Notifications can be thought of as an abstraction layer above Predictions. Reason being that not all predictions result in a generated notification, as there is business logic and thresholding that filters out predictions, depending on your own unique settings and the models being used.

Data Model

Predikto Maintain (our core user interface application) exposes notifications as a single object, but there are underlying child objects that tie Notifications, Predictions, Models, and raw data together. All of these objects are accessible through the REST API. and returned by a single call to /notifications

Click the image for detailed view… Notifications Data Model

A sample notification document is made available here: Notification JSON

Note that this document represents an entire notification object as stored in the database, and is not accessible by a single API call. Furthermore, it does not map directly in structure to the diagram shown above, but is useful in understanding how the data is stored.

The image above depicts a hierarchical view of the notifications object and its child objects. In detail these are defined as:

Notification Root

The root object of the notification object hierarchy.

Criticality and Impact

{
      "criticality": 3,
      "threshold_windows": {
        "predicted_risk": {
          "color": "#EB7406",
          "level": 2,
          "label": "High"
        }
      },
      "alert_level": 2
}

In determining the alert_level for a notification, both criticality and risk level are taken in to account. Criticality and Risk levels are adjustable within the user interface.

Alert Levels, Risk, and Criticality are also mapped to colors in the user interface and so not covered here.

Workflow

{
  "notification": {
    "reason": "notification",
    "assignee": "bob@foo.com",
    "notification_state": "ACCEPT",
    "is_notification": 1
  }
}

The root notification object contains workflow information regarding this notification. The assignee key will point to a user that has Accepted or Watched this notification and represents the current state.

The is_notification boolean represents whether this prediction met the threshold to be deemed a notification.

Prediction

Prediction Sample

{
  "prediction" : {
    "final_prediction_pr": 0.248,
    "final_prediction": 0,
    "hs_slow_response": 0.9907999999999999,
    "hs_medium_response": 0.9815999999999999,
    "hs_fast_response": 0.998
  }
}

The prediction itself is the value: prediction.final_prediction_pr, which in this case is 24.8%. This value is a calibrated probability, saying that there is a 24.8% chance that the device will experience failure tier_1 in the time range specified by predikto_prediction_start_timestamp and predikto_prediction_end_timestamp.

Note that predikto_prediction_start_timestamp and predikto_prediction_end_timestamp represent the prediction window.

Health Score

Health Score Sample

{
  "prediction" : {
    "final_prediction_pr": 0.248,
    "final_prediction": 0,
    "hs_slow_response": 0.9907999999999999,
    "hs_medium_response": 0.9815999999999999,
    "hs_fast_response": 0.998
  }
}

There are three health score values ongoing, hs_{fast|medium|slow}_response. The different speeds represent how fast the score will respond to changes, so fast HS will improve more quickly when something good happens and decline more quickly when something bad happens, vs slow. The scores nested under prediction are specifically for the tier of this document, in this case “tier_1”, which refers to a specific model or failure type.

Interpretations

Interpretations Sample

{
   "interpretation_confidence": 0.9996,
   "interpretation": 
   [
      {
      "contribution": 0,
      "feature_name": "number_of_stops_sum"
      },
      {
      "contribution": 0,
      "feature_name": "c_eventsum_typed14155"
      },
      {
      "contribution": -0.0198648685,
      "feature_name": "total_load_sum"
      },
      {
      "contribution": -0.0360156413,
      "feature_name": "oil_pressure_avg"
      },
      {
      "contribution": 0.0437197428,
      "feature_name": "current_mean_deviation"
      }
   ]
}

Specific features that contributed to this specific prediction, and their contribution amounts.

This is normally returned as a sorted list, depending on the endpoint used. We sort based on the absolute value of the contribution. Often, the zero-value contributions are removed.

Each of these interpretations points to a Feature. A feature, in-turn, points to a query that can be executed against the raw data.

The additional field, interpretation_confidence shows how confident we are that our interpretation is reliable, from 0 to 1.

Features

Features Sample

{
  "param_name": "fault_code",
  "param_value": "01-3017",
  "pretty_name": "Number of seconds since {{fault_code}} was 01-3017",
  "es_type": "string",
  "feature_name": "fault_code_categorical_time_since_flag_013017"
}

Features are contained in a separate database schema, and are accessible through dedicated endpoints. It contains meta-data and pretty print names for all features used by the models. This gets populated automatically with best guesses for human-readable names at first, and then can be updated by an administrator.

Validation

Validation Sample

{
   "validation": {
      "medium_risk": {
      "docs": [],
      "cnt": 0,
      "issued": 0
      },
      "critical": {
      "docs": [],
      "cnt": 0,
      "issued": 0
      },
      "low_risk": {
      "docs": [],
      "cnt": 0,
      "issued": 1
      },
      "no_risk": {
      "docs": [],
      "cnt": 0,
      "issued": 0
      }
   }
}

The validation portion points to a list of true-positive hits for this notification. The docs array points to document IDs in the database that were accurately predicted by this notification.

Each risk threshold has 3 bits of information stored:

Typically the validation metric with the highest relevance is the one that matches the current risk level of the notification.

Metrics

Import metrics regarding this asset and notification are placed in this object.

Precision and Recall

Example

{
   "metrics": {
      "notification_precision": {
      "any": 0.5245098039215687,
      "current_level": 0.5688622754491018
      },
      "notification_recall": {
      "any": 0.8148148148148148,
      "current_level": 0.7407407407407407
      }
   }
}

It is beyond the scope of this document to explain precision and recall, so we recommend Precision and Recall

any is the metric calculated using all notifications for that model (any level), current_level is the metric calculated using only notifications for that model that are the same level as the notification in that document.

Custom KPIs

Example

{
  "metrics": {
    "days_with_notifications": {
      "any": 0.25882352941176473,
      "current_level": 0.13574660633484162
    },
    "avg_days_until_failure": {
      "any": 38.59668508287293,
      "current_level": 36.07843137254902
    },
    "median_days_until_failure": {
      "any": 24,
      "current_level": 22
    }
  }
}

Custom KPIs will vary, and are defined by customer organizations. KPIs are calculated using any data Predikto consumes or generates.

API Reference

This section details the accessible API endpoints, the required request parameters, and the probable response payload.

Audit

All user actions within the user interface and REST API calls are tracked in a customer-specific audit log.

This log is searchable based on query criteria using this API endpoint.

Audit log data is accessible via REST API and viewable as charts within the user interface.

Fetch Audits

curl https://api.predikto.io/activities?end_point=api.users&request_type=user \
-X GET \
-H "x-prd-api-token: API_TOKEN"

Sample Response:

{
  "took": 1,
  "success": true,
  "status_code": 200,
  "total_count": 2,
  "data": [
    {
      "time_stamp": 1444915550000,
      "user_id": "6karA29BdnK9",
      "_id": "AVBrq6YOaPrJqy48h2gV",
      "full_url": "https://api.predikto.io/users",
      "username": "bob@predikto.com",
      "path": "/users",
      "endpoint": "api.users",
      "customer_id": "6karA29ewdnY9",
      "remote_address": "127.0.0.1",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
      "request_type": "user",
      "debug_id": "ba2af3dc-5843-4472-a74a-597cc1ce96c5",
      "method": "GET"
    }
  ],
  "_links": {
    "self": "https://api.predikto.io/activities?path=users&from=0&end_time=1445016121000&size=200&start_time=1437177600000"
  }
}

GET /activities

Activities are logged whenever a request is made to a protected endpoint in the REST API. This API allows for some dynamic querying, as it exposes many of the audit fields we track.

Parameters are expected to be URL request parameters, for specific fields.

Parameter Description
user_id User ID that made the requests.
method HTTP Method, ie. GET, PUT, POST, DELETE
request_type user OR api. API meaning RESTful call using an API token. User, meaning an authenticated user via a user-interface.
path Request path of resource, prepended with a ’/’, forward-slash
end_point Endpoint request was made to. Prepended with ‘api.’
remote_address Remote IP of request
username Email address of user making the request
from Beginning record to paginate from.
size Size of page results.
start_time Millisecond representation of from-date to query by.
end_time Millisecond representation of max-date to query by.

Fetch Audit Histogram

curl https://api.predikto.io/activities?end_point=api.config&request_type=user \
-X GET \
-H "x-prd-api-token: API_TOKEN"

Sample Response:

{
  "took": 1,
  "success": true,
  "status_code": 200,
  "total_count": 2,
  "data": [
    {
      "doc_count": 3324,
      "key_as_string": "20151014",
      "key": 1444780800000
    },
    {
      "doc_count": 6324,
      "key_as_string": "20151015",
      "key": 1444867200000
    }
  ],
  "_links": {
    "self": "https://api.predikto.io/activities/stat?path=users&from=0&end_time=1445016121000&size=200&start_time=1437177600000"
  }
}

doc_count is the number of requests for a day, where “key_as_string” and “key” signify the day as YYYYMMDD and Milliseconds since unix epoch time respectively.

GET /activities/stat

A Date Histogram reprsentation of an activities query. This API will return a by-day number of requests, given a query.

Parameter Description
user_id User ID that made the requests.
method HTTP Method, ie. GET, PUT, POST, DELETE
request_type user OR api. API meaning RESTful call using an API token. User, meaning an authenticated user via a user-interface.
path Request path of resource, prepended with a ’/’, forward-slash
end_point Endpoint request was made to. Prepended with 'api.’
remote_address Remote IP of request
username Email address of user making the request
from Beginning record to paginate from.
size Size of page results.
start_time Millisecond representation of from-date to query by.
end_time Millisecond representation of max-date to query by.

Notifications

We recommend you read and understand Notification Concepts before attempting to interact with this endpoint.

List Notifications

curl https://api.predikto.io/notifications \
-X POST 
-d '{}'

Sample Response:

{
  "_links": null,
  "status_code": 200,
  "message": null,
  "data": [
    {
      "impact_color": "#C20000",
      "impact_label": "High",
      "tier_name": "tier_18",
      "notification": {
        "assignee": null,
        "is_notification": 1,
        "notification_state": "NEW",
        "reason": "notification"
      },
      "predikto_prediction_end_timestamp": 1492128000000,
      "alert_color": "#EB7406",
      "event_info": {
        "query_terms": [
          {
            "query_type": "wildcard",
            "term": "19*",
            "param_name": "event_3_aa_raw"
          },
          {
            "term": "Electrical Failure",
            "param_name": "fault_type1"
          }
        ],
        "pretty_name": "High Voltage System"
      },
      "predikto_prediction_start_timestamp": 1489536000000,
      "parent_id": "ASSET_1",
      "criticality": 3,
      "time_stamp": 1489536000000,
      "_id": "<NOTIFICATION_ID>",
      "device_id": "ASSET_1",
      "prediction": {
        "hs_fast_response": 0.71,
        "hs_medium_response": 0.7935424477399999,
        "final_prediction": 1,
        "final_prediction_pr": 0.876,
        "hs_slow_response": 0.6171712238700001
      },
      "alert_level": 2,
      "threshold_windows": {
        "predicted_risk": {
          "label": "High",
          "color": "#EB7406",
          "level": 2
        }
      }
    },...]}

By default, returns a sorted list of notifications with issued timestamp descending (newest first).

This endpoint requires a POST body. Providing empty brackets {} will suffice as a default call. For explicit filtering and sorting this endpoint accepts Query DSL expressions.

The variable returned as _id is a unique identifier for this notification. It can be used to Fetch One Notification

Fetch One Notification

curl https://api.predikto.io/notifications/<NOTIFICATION_ID> \
-X GET

GET /notifications/{id}

Parameter Description Required Location
id Notification ID to fetch. path

List Interpretations

curl https://api.predikto.io/notifications/<NOTIFICATION_ID>/lime \
-X GET

Sample Response:

{
  "_links": null,
  "status_code": 200,
  "message": null,
  "data": [
    {
      "contribution": -0.0139475303,
      "param_value": null,
      "type": "double",
      "feature_name": "voltage_mean",
      "pretty_name": "Avg. of voltage",
      "param_name": "voltage"
    }
  ],
  "took": 2,
  "total_count": 1,
  "success": true
}

GET /notifications/<NOTIFICATION_ID>/lime

Returns a list of features that contributed to this notification. The list has zero-value contributions removed entirely, and is sorted by highest contribution amount to lowest. Sorting is based on the absolute value of the contribution value.

It is important to note that the param_name value returned is the name of a column in the parent’s raw data. That is, in this example, you can query the asset (parent) for the values of voltage under Fetch Events for Field by Parent by passing the param_name field: POST /parents/<ASSET_ID>/events/voltage

Notification History

curl https://api.predikto.io/notifications/<NOTIFICATION_ID>/history \
-X POST 
-d '{}'

POST /notifications/<NOTIFICATION_ID>/history

Parameter Description Required Location
id Notification ID path
expression Query DSL body

Returns a history of notifications for this asset.

This endpoint requires a notificaton ID. Using this notification ID, the system retrieves the Asset ID and returns a list of notifications for this asset.

This query accepts a time-range. By default, it returns a notification window of 30 days, even if notifications overlap.

Notification Predictions

curl https://api.predikto.io/notifications/<NOTIFICATION_ID>/predictions \
-X POST 
-d '{}'

Sample Response

{
  "data": [
    {
      "predikto_prediction_end_timestamp": 1474675200000,
      "device_id": "LOCOMOTIVE_1",
      "predikto_prediction_start_timestamp": 1472083200000,
      "tier_name": "tier_75",
      "time_stamp": 1472083200000,
      "parent_id": "TRAIN_1",
      "prediction": {
        "hs_slow_response": 0.98977047619,
        "final_prediction_pr": 0.6688698413,
        "hs_fast_response": 0.986,
        "hs_medium_response": 0.99122285714
      },
      "_id": "1fb83df4b4c146007df59dbf2b03d3f1"
    }, ...
  ]
}

POST /notifications/<NOTIFICATION_ID>/predictions

Parameter Description Required Location
id Notification ID path
expression Query DSL body

Returns a history of predictions for the asset and model tied to this notification.

This endpoint requires a notificaton ID. Using this notification ID, the system retrieves the Asset ID and Model, and then returns a list of predictions for this asset.

The Search API enables you to query all data in your database.

This API makes heavy use of Query DSL Filters and Aggregations, so it is best to familiarize yourself with it before attempting to query.

Querying Events:

curl https://api.predikto.io/search/events
-X POST
-d '{ "expression" : {}}'

This list of endpoints are basic convenience methods around the Query API, allowing you easy access to specific aspects of parents or a parent.

Aspect Description QDSL Support
Events Raw sensor and diagnostic data.

Events: Events are your raw sensor and maintenance data. This path parameter allows you to query the ETLed data in any manner supported by the Query DSL. /search/events

Query Events

curl https://api.predikto.io/search/events \
-X POST 
-d '{ "expression" : {}}'

Sample Response:

{
  "_links": null,
  "total_count": 154628317,
  "status_code": 200,
  "success": true,
  "message": null,
  "took": 1013,
  "data": [
    {
      "_id": "1193f8704a6b0f51bd617c9267616cb3",
      "parent_id": "XX1",
      "time_stamp": 1476960718000,
      "oil_temp": 120.409178733825684,
      "device_id": "YY2"
    },
    {
      "_id": "08ed99b4ecdac22569988fa71097e81a",
      "parent_id": "XX1",
      "time_stamp": 1476928563000,
      "oil_temp": 150.347721703433257,
      "device_id": "YY9",
      "parent_id": "XX2"
    }
  ]
}

POST /search/events

Given an empty expression, returns a randomly selected set of data.

This endpoint accepts filters and aggregations, and extra parameters. By default, it returns only 10 results at a time, unless otherwise specified in the expression.

Analyzing the response

Parents

A Parent object is simply a superset of a Device. This will vary across data-sets, and is unique to the specific data imported.

A typical Asset Hierarchy goes: Parent > Device > Component

The Parents API enables you to query data related to all or specific parents in your database.

This API makes heavy use of Query DSL Filters and Aggregations, so it is best to familiarize yourself with it before attempting to query.

This list of endpoints are basic convenience methods around the Query API, allowing you easy access to specific aspects of parents or a parent.

Aspect Description QDSL Support
Events Raw sensor and diagnostic data.

List Parents

curl https://api.predikto.io/parents \
-X POST \
-d '{}'

Sample Response:

{
    "total_count": 2,
    "success": true,
    "_links": {
        "self": "https://api.predikto.io/parents"
    },
    "took": 3,
    "status_code": 200,
    "data": [
      {
        "time_stamp": 1462910765776,
        "_links": {
          "events": "https://api.predikto.io/parents/3000/events"
        },
        "parent_id": 3000
      },
      {
        "time_stamp": 1462910765776,
        "_links": {
          "events": "https://api.predikto.io/parents/3001/events"
        },
        "parent_id": 3001
      }
    ]
}

POST /parents

Returns a list of all unique parents (by parent_id) and their HATEOS links for fetching more information.

This endpoint does not accept filters or aggregations, as it already provides uniqueness.

Fetch Parent Events

curl https://api.predikto.io/parents/{parent_id}/events \
-X POST 
-d '{}'

Sample Response:

{
  "total_count": 22169,
  "message": null,
  "_links": {
    "events": "https://api.predikto.io/parents/loco_1/events"
  },
  "success": true,
  "data": [
    {
      "predikto_insert_time_stamp": 1451016440000,
      "parent_id": "LOCO_1",
      "time_stamp": 1450663990000,
      "code_text": "door operated with closing override",
      "event": 0,
      "geohash": "bex08r2yq4h9",
      "code": "08SDF",
      "_id": "AVHXUx1njzuVsZPwTvqx",
      "diagnosticfile": 1,
      "vehicle__speed": 226.27627631696748,
      "date_epoch": 16790,
      "file_id": 1,
      "parent_id": "TRAIN_1"
    }
  ]
}

POST /parents/{parent_id}/events

Queries the event (sensors/diagnostic) database for a given parent_id. An empty {} expression will return everything. Otherwise, a Query DSL filter and/or aggregation will be applied.

Parameter Description Required Location
parent_id Parent ID to fetch. path

Fetch Events for Field by Parent

curl https://api.predikto.io/parents/{parent_id}/events/{param_name} \
-X POST
-d '{}'

Sample Response, assuming {param_name} == oil__temperature__inlet:

{
  "total_count": 22169,
  "message": null,
  "_links": {
    "events": "https://api.predikto.io/parents/loco_1/events"
  },
  "success": true,
  "data": [
    {
      "geohash": "bex08r2yq4h9",
      "parent_id": "LOCO_3",
      "time_stamp": 1450656790000,
      "oil__temperature__inlet": 101.03344391516744
    },
    {
      "geohash": "dpx9295bwh93",
      "parent_id": "LOCO_3",
      "time_stamp": 1450856424000,
      "oil__temperature__inlet": 108.61213035877756
    }
  ]
}

POST /parents/{parent_id}/events/{param_name}

Returns event records for a given parent and param_name. An empty {} expression will return everything. Otherwise, a Query DSL filter and/or aggregation will be applied.

Note that specifying a param_name automatically adds the field to the result-set, even if not specified in the query explicitly.

Parameter Description Required Location
parent_id Parent ID to fetch. path
param_name Sensor reading key to filter on. path

Fetch Notifications by Parent

curl https://api.predikto.io/parents/{parent_id}/notifications \
-X POST
-d '{}'

POST /parents/{parent_id}/notifications

Returns notification records for a given parent. An empty {} expression will return everything. Otherwise, a Query DSL filter and/or aggregation should be applied.

Parameter Description Required Location
parent_id Parent ID of notifications. path

Devices

A Device object is simply a child of a Parent. This will vary across data-sets, and is unique to the specific data imported.

A typical Asset Hierarchy goes: Parent > Device > Component

The Devices API enables you to query data related to all or specific parents in your database.

This API makes heavy use of Query DSL Filters and Aggregations, so it is best to familiarize yourself with it before attempting to query.

This list of endpoints are basic convenience methods around the Query API, allowing you easy access to specific aspects of parents or a parent.

Aspect Description QDSL Support
Events Raw sensor and diagnostic data.

List Devices

curl https://api.predikto.io/devices \
-X POST \
-d '{}'

Sample Response:

{
    "total_count": 2,
    "success": true,
    "_links": {
        "self": "https://api.predikto.io/devices"
    },
    "took": 3,
    "status_code": 200,
    "data": [
      {
        "time_stamp": 1462910765776,
        "_links": {
          "events": "https://api.predikto.io/devices/3000/events"
        },
        "device_id": 3000
      },
      {
        "time_stamp": 1462910765776,
        "_links": {
          "events": "https://api.predikto.io/devices/3001/events"
        },
        "device_id": 3001
      }
    ]
}

POST /devices

Returns a list of all unique devices (by device_id) and their HATEOS links for fetching more information.

This endpoint does not accept filters or aggregations, as it already provides uniqueness.

Fetch Device Events

curl https://api.predikto.io/devices/{device_id}/events \
-X POST 
-d '{}'

Sample Response:

{
  "total_count": 22169,
  "message": null,
  "_links": {
    "events": "https://api.predikto.io/devices/loco_1/events"
  },
  "success": true,
  "data": [
    {
      "predikto_insert_time_stamp": 1451016440000,
      "device_id": "LOCO_1",
      "time_stamp": 1450663990000,
      "code_text": "door operated with closing override",
      "event": 0,
      "geohash": "bex08r2yq4h9",
      "code": "08SDF",
      "_id": "AVHXUx1njzuVsZPwTvqx",
      "diagnosticfile": 1,
      "vehicle__speed": 226.27627631696748,
      "date_epoch": 16790,
      "file_id": 1,
      "parent_id": "TRAIN_1"
    }
  ]
}

POST /devices/{device_id}/events

Queries the event (sensors/diagnostic) database for a given device_id. An empty {} expression will return everything. Otherwise, a Query DSL filter and/or aggregation will be applied.

Parameter Description Required Location
device_id Device ID to fetch. path

Fetch Events for Field by Parent

curl https://api.predikto.io/devices/{device_id}/events/{param_name} \
-X POST
-d '{}'

Sample Response, assuming {param_name} == oil__temperature__inlet:

{
  "total_count": 22169,
  "message": null,
  "_links": {
    "events": "https://api.predikto.io/devices/loco_1/events"
  },
  "success": true,
  "data": [
    {
      "geohash": "bex08r2yq4h9",
      "device_id": "LOCO_3",
      "time_stamp": 1450656790000,
      "oil__temperature__inlet": 101.03344391516744
    },
    {
      "geohash": "dpx9295bwh93",
      "device_id": "LOCO_3",
      "time_stamp": 1450856424000,
      "oil__temperature__inlet": 108.61213035877756
    }
  ]
}

POST /devices/{device_id}/events/{param_name}

Returns event records for a given device and param_name. An empty {} expression will return everything. Otherwise, a Query DSL filter and/or aggregation will be applied.

Note that specifying a param_name automatically adds the field to the result-set, even if not specified in the query explicitly.

Parameter Description Required Location
device_id Device ID to fetch. path
param_name Sensor reading key to filter on. path

Fetch Notifications by Device

curl https://api.predikto.io/devices/{device_id}/notifications \
-X POST
-d '{}'

POST /devices/{device_id}/notifications

Returns notification records for a given Device. An empty {} expression will return everything. Otherwise, a Query DSL filter and/or aggregation should be applied.

Parameter Description Required Location
device_id Device ID of notifications. path

Models

We recommend you read and understand Notification Concepts before attempting to interact with this endpoint.

The term “Model” here is referred to as a “Tier” in the Data Model. That is, a machine learning model.

List Models

curl https://api.predikto.io/models \
-X POST 
-d '{}'

POST /models

This endpoint requires a POST body. Providing empty brackets {} will suffice as a default call. For explicit filtering and sorting this endpoint accepts Query DSL expressions.

The variable returned as _id is a unique identifier for this model, but in tier_name is unique and should be used in loading specific models.

Fetch Model By Name

curl https://api.predikto.io/models/<TIER_NAME> \
-X GET

GET /models/{tier_name}

Parameter Description Required Location
tier_name Model name to fetch. path

Settings

Settings determine how much of the user interface and parts of the REST API function for your account. These settings are company-wide and will affect everyone logging in to your account, so please be careful when making changes.

Setting definitions are listed below:

Setting Type Description
LOCKOUT_NUM_FAILED Integer Number of failed login attempts before User account locked.
LOCKOUT_EXPIRY_MINUTES Integer Number of minutes a locked-out user has to wait after LOCKOUT_NUM_FAILED login attempts.
PASSWORD_MAX_AGE_DAYS Integer Number of days before a user is forced to update password.
PASSWORD_MIN_LENGTH Integer Minimum length for passwords.
PASSWORD_MAX_LENGTH Integer Maximum length for passwords.
PASSWORD_ENABLE_COMPLEXITY Boolean Whether to enable password complexity rules.
ADMIN_EMAIL String Who to email if downtime is expected for the system.
ADMIN_NAME String Administrators Name (merely here for email sending)
INVITE_EXPIRE_HOURS Integer Number of hours before automatically expiring a User invite.

Fetch all Settings

curl https://api.predikto.io/settings \
-X GET \
-H "x-prd-api-token: API_TOKEN"

Sample Response:

{
   "status_code": 200,
   "message": null,
   "_links": {
      "self": "https://api.predikto.io/settings"
   },
   "success": true,
   "data": [
      {
         "PASSWORD_MAX_AGE_DAYS": 90,
         "LOCKOUT_EXPIRY_MINUTES": 15,
         "PASSWORD_MIN_LENGTH": 6,
         "PASSWORD_MAX_LENGTH": 32,
         "ADMIN_EMAIL": "bob@acme.com",
         "PASSWORD_ENABLE_COMPLEXITY": true,
         "LOCKOUT_NUM_FAILED": 3,
         "ADMIN_NAME": "Bob Smithy",
         "INVITE_EXPIRE_HOURS": "3"
      }
   ]
}

GET /settings

Please see the beginning of the Settings section for an explanation of each of the items returned.

Update Settings

curl https://api.predikto.io/settings \
-X PUT \
-H "x-prd-api-token: API_TOKEN" \
-H "Content-Type: application/json" \
-d "{ "LOCKOUT_EXPIRY_MINUTES" : 500, "LOCKOUT_NUM_FAILED" : 5 }

Sample Response:

{
  "_links": {
    "self": "https://api.predikto.io/settings"
  },
  "success": true,
  "status_code": 200
}

PUT /settings

This endpoint takes any number of setting key-value pairs and updates their values. You do not have to send all the settings… just the ones you want updated.

Status

System status information and REST API version information.

Fetching System Status

curl https://api.predikto.io/status \
-X GET

Sample Response:

{
  "_links": null,
  "success": true,
  "status_code": 200,
  "data": [
    {
      "message": "You know, for the numbers.",
      "running_on": "DEV",
      "version": "v2",
      "release": "v2.9.0"
    }
  ]
}

GET /status

Returns system status and REST API Version information.

Fetching available routes

curl https://api.predikto.io/routes \
-X GET

Sample Response:

{
  "_links": null,
  "success": true,
  "status_code": 200,
  "data": [
        {
            "methods": "GET,HEAD,OPTIONS",
            "url": "/activities/stat",
            "api": "api.activities_stat"
        },
        {
            "methods": "GET,HEAD,OPTIONS",
            "url": "/reports/notifications",
            "api": "api.notification-list-all"
        }
  ]
}

GET /routes

Returns all RESTful routes available on the system. The result also includes the HTTP Methods supported by the endpoint and any required variables that need to be sent as well.

Users

Only users of your account are visible. Users will be assigned to Roles that grant them access via Permissions.

Before using this endpoint, it is advisable to learn the User model and its relation to Roles, Permissions, and other entities.

User ERD

Example: A User, bob@email.com, is assigned to Role, Adminstrators. Role Administrators has permission name, EDIT_REPORTS, thus allowing the user to edit reports via the UI, or using the REST API.

The User model controls Authentication and Authorization throughout the system. Authorization is composed of a User belonging to n Role(s). Each Role is composed of n Permission(s). A Permission is the smallest atomic object that controls Authorization, or access, to functionality in the system.

Users are constrained by having unique email addresses. Predikto uses Email Address as the unique login user-name for a User. The email address is identified as the username field within the User object.

Fetch All Users

curl https://api.predikto.io/users \
-X GET 

Sample Response:

{
  "_links": {
    "self": "https://api.predikto.io/users"
  },
  "success": true,
  "data": [
    {
      "id": "6karA29BdnK9",
      "username": "roy@predikto.com",
      "created_time": "2015-08-20T15:20:37.314045+00:00",
      "updated_time": "2015-08-20T15:20:37.314045+00:00",
      "customer_id": "6karA29BdnK9",
      "_links": {
        "self": "https://api.predikto.io/users/6karA29BdnK9",
        "collection": "https://api.predikto.io/users"
      },
      "roles": [
        {
          "id": "3OKpx6zxrLYn",
          "role_name": "Administrator",
          "role_description": "Site Admin",
          "created_time": "2015-08-20T18:53:24.697536+00:00",
          "updated_time": "2015-08-20T18:53:24.697536+00:00",
          "customer_id": "6karA29BdnK9",
          "_links": {
            "self": "https://api.predikto.io/roles/3OKpx6zxrLYn",
            "collection": "https://api.predikto.io/roles"
          },
          "permissions": [
            {
                "id": "7R4XDQlxwOok",
                "perm_name": "USER_VIEW",
                "perm_description": "View user and lists of users."
            },
            {
                "id": "r94aDnexWVJk",
                "perm_name": "APITOKEN_VIEW",
                "perm_description": "View available API tokens"
            }
          ]
        }
      ],
      "groups": [
        {
          "id": "3OKpx6zxrLYn",
          "group_name": "Admin Group",
          "group_description": "Default group for administrators",
          "created_time": "2016-08-17T18:50:19.908899+00:00",
          "updated_time": "2016-08-17T22:55:11.072130+00:00",
          "_links": {
            "self": "https://api.predikto.io/groups/3OKpx6zxrLYn",
            "collection": "https://api.predikto.io/groups"
          }
        }
      ]
    }
  ],
  "status_code": 200
}

GET /users

Only users of your account are visible. Users will be assigned to Roles that grant them access via Permissions.

Note that the response envelope returns the entire User object hierarchy, including the nested Roles and Permissions.

The HATEOS links provided in each individual User object _self will return the User by itself.

Fetch User by ID

curl https://api.predikto.io/users/6karA29BdnK9 \
-X GET 
{
  "data": [
     {
        "id": "6karA29BdnK9",
        "username": "roy@predikto.com",
        "created_time": "2015-08-20T15:20:37.314045+00:00",
        "updated_time": "2015-08-20T15:20:37.314045+00:00",
        "customer_id": "6karA29BdnK9",
        "_links": {
           "self": "https://api.predikto.io/users/6karA29BdnK9",
           "collection": "https://api.predikto.io/users"
        },
        "roles": [
           {
              "id": "6karA29BdnK9",
              "role_name": "User",
              "role_description": "General Users of the system with basic access to view dashboards and charts. Limited to no administrative capabilities.",
              "created_time": "2015-08-20T15:21:26.135573+00:00",
              "updated_time": "2015-10-23T18:40:02.546465+00:00",
              "customer_id": "6karA29BdnK9",
              "_links": {
                 "self": "https://api.predikto.io/roles/6karA29BdnK9",
                 "collection": "https://api.predikto.io/roles"
              },
              "permissions": [
                 {
                    "id": "7R4XDQlxwOok",
                    "perm_name": "USER_VIEW",
                    "perm_description": "View user and lists of users."
                 },
                 {
                    "id": "r94aDnexWVJk",
                    "perm_name": "APITOKEN_VIEW",
                    "perm_description": "View available API tokens"
                 }
              ]
           }
        ],
        "profile": [
           {
              "profile_id": 1,
              "profile_key": "first_name",
              "profile_value": "Roy"
           }
          ]
        },
        "groups": [
        {
          "id": "3OKpx6zxrLYn",
          "group_name": "Admin Group",
          "group_description": "Default group for administrators",
          "created_time": "2016-08-17T18:50:19.908899+00:00",
          "updated_time": "2016-08-17T22:55:11.072130+00:00",
          "_links": {
            "self": "https://api.predikto.io/groups/3OKpx6zxrLYn",
            "collection": "https://api.predikto.io/groups"
          }
        }
     ]
  ],
  "message": null,
  "success": true,
  "status_code": 200,
  "_links": null
}

GET /users/{id}

Parameter Description Required Location
id User ID to fetch. path

The embedded collection link provides a convenient method to retrieve all users and navigate the User hierarchies.

Fetch My Profile

curl https://api.predikto.io/whoami \
-X GET

GET /whoami

Returns the user object for the currently logged-in user.

Roles

See the Users section for an explanation of the User-Role data model.

Roles are simply containers for Permissions. Roles are assigned to Users, and users can belong to many Roles concurrently, thus giving them access to different parts of the functionality.

Fetch All Roles

curl https://api.predikto.io/roles \
-X GET

Sample Response:

{
  "_links": {
    "self": "https://api.predikto.io/roles"
  },
  "success": true,
  "data": [
    {
      "id": "3OKpx6zxrLYn",
      "role_name": "Administrator",
      "role_description": "Site Admin",
      "created_time": "2015-08-20T18:53:24.697536+00:00",
      "updated_time": "2015-08-20T18:53:24.697536+00:00",
      "customer_id": "6karA29BdnK9",
      "_links": {
        "self": "https://api.predikto.io/roles/3OKpx6zxrLYn",
        "collection": "https://api.predikto.io/roles"
      },
      "permissions": []
    }
  ],
  "status_code": 200
}

GET /roles

Fetch Role by ID

curl https://api.predikto.io/roles/{id} \
-X GET 
{
  "_links": {
    "self": "https://api.predikto.io/roles"
  },
  "success": true,
  "data": [
    {
      "id": "3OKpx6zxrLYn",
      "role_name": "Administrator",
      "role_description": "Site Admin",
      "created_time": "2015-08-20T18:53:24.697536+00:00",
      "updated_time": "2015-08-20T18:53:24.697536+00:00",
      "customer_id": "6karA29BdnK9",
      "_links": {
        "self": "https://api.predikto.io/roles/3OKpx6zxrLYn",
        "collection": "https://api.predikto.io/roles"
      },
      "permissions": []
    }
  ],
  "status_code": 200
}

GET /roles/{id}

Parameter Description Required Location
id Role ID to fetch. path

Create new Role

curl https://api.predikto.io/roles \
-X POST \
-d "{ "role_name" : "Administrator", "role_description" : "A New Role" }"

{
  "_links": {
    "self": "https://api.predikto.io/roles"
  },
  "success": true,
  "status_code": 201,
  "data": [
    {
      "id": "3OKpx6zxrLYn",
      "role_name": "Administrator",
      "role_description": "A New Role",
      "created_time": "2015-08-20T18:53:24.697536+00:00",
      "updated_time": "2015-08-20T18:53:24.697536+00:00",
      "customer_id": "6karA29BdnK9",
      "_links": {
        "self": "https://api.predikto.io/roles/3OKpx6zxrLYn",
        "collection": "https://api.predikto.io/roles"
      },
      "permissions": []
    }
  ]    
}

POST /roles

Creating a Role successfully will result in a 201 response, with the new Role object embedded in the json response body.

Parameter Description Required Location
name Role name. body
description Role description. body

Update existing Role

curl https://api.predikto.io/roles/{id} \
-X PUT \
-d "{ "role_name" : "On Second Thought" }"

{
  "_links": {
    "self": "https://api.predikto.io/roles"
  },
  "success": true,
  "status_code": 204,
  "data": [
    {
      "id": "3OKpx6zxrLYn",
      "role_name": "On Second Thought",
      "role_description": "A New Role",
      "created_time": "2015-08-20T18:53:24.697536+00:00",
      "updated_time": "2015-08-20T18:53:24.697536+00:00",
      "customer_id": "6karA29BdnK9",
      "_links": {
        "self": "https://api.predikto.io/roles/3OKpx6zxrLYn",
        "collection": "https://api.predikto.io/roles"
      },
      "permissions": []
    }
  ]    
}

PUT /roles/{id}

Attempting to update a role with an ID that doesn’t exist, will result in a 400 - BAD_REQUEST response.

Parameter Description Required Location
id Existing Role ID. path
name Role name. body
description Role description. body

Permissions

See the Users section for an explanation of the User-Role data model.

Permissions can never be created or deleted. They are static to your account, and are assigned to Roles.

A Permission acts as an Authorization flag allowing a User access to functionality not accessible without that Permission.

Fetch all Permissions

curl https://api.predikto.io/roles/permissions \
-X GET

Sample Response:

{
   "status_code": 200,
   "message": null,
   "_links": null,
   "success": true,
   "data": [
      {
         "id": "6karA29BdnK9",
         "perm_name": "USER_CREATE",
         "perm_description": "Create users."
      },
      {
         "id": "3OKpx6zxrLYn",
         "perm_name": "USER_EDIT",
         "perm_description": "Edit users."
      },
      {
         "id": "PdZqBWgB6abv",
         "perm_name": "USER_DELETE",
         "perm_description": "Delete users."
      }
   ]
}

GET /roles/permissions

Query DSL Reference

Example JSON Schema Structure:

{
   "expression": {
      "from": "<INTEGER>",
      "size": "<INTEGER>",
      "query": {
         "filtered": {
            "filter": {
               "bool": {
                  "must": [
                    {
                        "term" : { "<SOME_PARAMETER>" : "<SOME_VALUE>" }
                    }
                  ]
               }
            }
         }
      },
      "aggs": {
         "agg_1": {
            "terms": {
               "field": "<SOME_FIELD>"
            }
         }
      }
   }
}

Predikto provides a full JSON-based Query DSL (domain-specific language) to define queries. The Query DSL is used to build criteria for searching and retrieving data, and event counts.

You can think of the Query DSL as a rich expression language that enables developers to query their data and apply aggregation functions to the output as well.

There are two main concepts to any QDSL request:

Often these two concepts are combined. ie. query all records within a date range that match a specific term, and return the maximum oil pressure reading.

Developers

You can use Chrome Developer Tools to view queries used within the user interface and then alter them to suit your needs. This Article walks you through the configuration.

Supported Endpoints

Not all endpoints support dynamic querying. Only those endpoints that retrieve your data support dynamic querying. That is, data that has been imported, transformed, and formatted support dynamic querying, at the moment. Below, is a list of the currently supported endpoints:

Filters

Filters allow you to define query patterns when conducting queries for exact values or binary yes/no searches.

Boolean Filter

Example Boolean Filter with must and must_not. This example searches for any records for locomotive_id 1123 where the age field is all numbers excluding within 5 through 12.

{
   "expression": {
      "query": {
        "filtered": {
          "filter": {
            "bool": {
              "must": [
                {
                  "term": {
                    "locomotive_id": "1123"
                  }
                }
              ],
              "must_not" : [
                  {
                      "range" : {
                          "age" : {
                              "gte" : 5,
                              "lte" : 12
                          }
                      }
                  }
              ]
            }
          }
        }
      }
  }
}

Boolean filters allow you to combine filters in an AND/OR fashion. Using Boolean filters, you can mix-n-match different kinds of filters to accomplish complex querying patterns.

Boolean filters support must and must_not arrays for equality and exclusion, respectively. When using a boolean filter, a must or must_not has to be included in the request, or it will fail.

Term Filter

Example Term Filter. This example return all records for locomotive_id == 1123.

{
  "expression": {
      "query": {
        "filtered": {
          "filter": {
              "term": {
                "locomotive_id": "1123"
              }
          }
        }
      }
  }
}

When you want to search for data that have fields that contain a specific term, this is the filter to use.

A term filter value must match the exact value in the database to return any data. Wildcard searching is not supported using this Filter.

Terms Filter

Example Terms Filter. This example returns all records for train_depot == GA or FL.

{
  "expression": {
      "query": {
        "filtered": {
          "filter": {
              "terms": {
                "train_depot": ["GA","FL"]
              }
          }
        }
      }
  }
}

Consider a Terms Filter similar to having an IN clause in SQL.

Range Filter

Example Range Filter. This example return all records that contain an age between, and including, 5 and 12.

{
  "expression": {
      "query": {
        "filtered": {
          "filter": {
              "range" : {
                  "age" : {
                      "gte" : 5,
                      "lte" : 12
                  }
              }
          }
        }
      }
  }
}

The Range Filter enables queries across numeric ranges. This filter only works on numeric fields, ie. double, integer, long. Attempting to use this filter on a non-numeric field will fail.

The range filter must contain either a lower or upper bound, using less-than / greater-than parameters:

Type Description
gt greater than
lt less-than
gte greater than or equal-to
lte less-than or equal-to

Date Range Filter

Example Range Filter. This example return all records with a time-stamp between the given milliseconds-since-epoch values.

{
  "expression": {
      "query": {
        "filtered": {
          "filter": {
            "range": 
            {
                "time_stamp": {
                    "lte": 1463457599999, 
                    "gte": 1447563600000
                }
            }
          }
        }
      } 
  }
}

The Date Range Filter uses the same syntax as the above, Range Filter, with some additional options. The important difference is that these options only work on fields that are defined as date in the database. Typically, the standard/universal field time_stamp will be the most queried upon, as it defines the time-stamp of your data record entry.

The Date Range Filter supports Date Math operations as values.

Please see Specifying Date Ranges for alternate date-range search mechanisms.

Wildcard Matching

Example Wildcard Query. Note the use of the QUERY block and absence of the filter block.

{
    "expression" : {
      "query": {
        "filtered": {
          "query": {
            "bool": {
              "must": [
                {
                  "query_string": {
                    "analyze_wildcard": true,
                    "default_operator": "AND",
                    "fields": [
                      "parent_id"
                    ],
                    "query": "*7*"
                  }
                }
              ]
            }
          }
        }
      }
   }
}

Uses a query parser to parse the content and return matching results. This query type accepts many different operators. Complete documentation can be found here

Aggregations

A sample aggregation structure:

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "<AGG_TYPE>" : 
                { "field" : "<SOME_FIELD>" }
          }
      }
    }
}

The Query DSL supports aggregation functions. Aggregations allow you to group data and return computed fields. They can be combined with filters for refining metrics calculations.

The different aggregation types are:

Type Description
Terms A unique value list with counts found for a specified field
Max computed max value for a field
Min computed min value for a field
Count computed count value for a field
Sum computed sum value for a field
Average computed average value for a field
Stats computed max, min, count, sum, standard deviation, and other for a field
Date date histogram for a specific query

Aggregations are encapsulated within an aggs field and must contain an agg_1 field. See the examples below for aggregation-specific requirements…

Terms Aggregation

Sample Terms Aggregation that returns the 3 unique values and counts.

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "terms" : { 
                  "field" : "fault_code",
                  "size" : 3
              }
          }
      }
    }
}

Sample Response:

{
  "total_count": 3,
  "took": 172,
  "success": true,
  "data": [
      {
        "key": "0013",
        "doc_count": 192
      },
      {
        "key": "08",
        "doc_count": 173
      },
      {
        "key": "10",
        "doc_count": 161
      }
  ],
  "status_code": 200
}

Returns unique values for a specified field and their row counts. This is similar to a GROUP BY and COUNT(UNIQUE) SQL query.

Parameter Description Location
field Data field to apply aggregate function body
size Number of unique items to return. Leaving this blank will return 10 unique values. body

Max Value Aggregation

A sample aggregation to retrieve the Max value for a field:

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "max" : { 
                  "field" : "days__in__service"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 1,
  "took": 172,
  "success": true,
  "data": [
    {
      "value": 3175
    }
  ],
  "status_code": 200
}

Retrieves the computed Maximum value for a field.

Parameter Description Location
field Data field to apply aggregate function body

Min Value Aggregation

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "min" : { 
                  "field" : "days__in__service"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 1,
  "took": 173,
  "success": true,
  "data": [
    {
      "value": 3160
    }
  ],
  "status_code": 200
}

Retrieves the computed Minimum value for a field.

Parameter Description Location
field Data field to apply aggregate function body

Value Count Aggregation

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "value_count" : { 
                  "field" : "days__in__service"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 1,
  "took": 173,
  "success": true,
  "data": [
    {
      "value": 3
    }
  ],
  "status_code": 200
}

Retrieves the number of rows in the database that contain the field specified. Similar to COUNT(*) in SQL.

Parameter Description Location
field Data field to apply aggregate function body

Sum Value Aggregation

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "sum" : { 
                  "field" : "days__in__service"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 1,
  "took": 165,
  "success": true,
  "data": [
    {
      "value": 9508.34244114
    }
  ],
  "status_code": 200
}

Retrieves the computed Sum value for a field.

Parameter Description Location
field Data field to apply aggregate function body

Avg Value Aggregation

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "avg" : { 
                  "field" : "days__in__service"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 1,
  "took": 174,
  "success": true,
  "data": [
    {
      "value": 3169.3333333333335
    }
  ],
  "status_code": 200
}

Retrieves the computed Average value for a field.

Parameter Description Location
field Data field to apply aggregate function body

Extended Stats Aggregation

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "extended_stats" : { 
                  "field" : "days__in__service"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 1,
  "took": 167,
  "success": true,
  "data": [
    {
      "sum_of_squares": 30134154,
      "count": 3,
      "variance": 44.22222222263614,
      "min": 3160,
      "max": 3175,
      "avg": 3169.3333333333335,
      "std_deviation_bounds": {
        "lower": 3156.0333751044313,
        "upper": 3182.6332915622356
      },
      "std_deviation": 6.649979114451123,
      "sum": 9508
    }
  ],
  "status_code": 200
}

Retrieves several computed values for a field: count, sum, avg, max, min, variance, sum of squares, and standard deviation.

Parameter Description Location
field Data field to apply aggregate function body

Date Histogram Aggregation

{
    "expression" : {
      "aggs" : {
          "agg_1" : {
              "date_histogram" : { 
                  "field" : "time_stamp",
                  "interval" : "hour"
            }
        }
      }
    }
}

Sample Response:

{
  "total_count": 3,
  "took": 161,
  "success": true,
  "data": [
    [
      {
        "doc_count": 1,
        "key_as_string": "20151204",
        "key": 1449187200000
      },
      {
        "doc_count": 1,
        "key_as_string": "20151217",
        "key": 1450310400000
      },
      {
        "doc_count": 1,
        "key_as_string": "20151219",
        "key": 1450483200000
      }
    ]
  ],
  "status_code": 200
}

Provides a date histogram view by returning row counts grouped by a time-frame. Normally used on the reserve field time_stamp, which is defined as a date field in milliseconds since unix epoch. Note that this aggregation returns results formatted inside of an additional nested JSON array.

The possible time intervals are:

agg_interval Interval
y Year
M Month
w Week
d Day
h Hour
m Minute
s Second
ms Milli-Second
Parameter Description Location
field Data field to apply aggregate function body
interval Date interval to group by body

Specifying Return Fields

{
    "expression" : {
        "_source": {
                "include": [ "fleet_ad_id"],
                "exclude" : ["time_stamp"]
            },
        "size" : 20,
        "query": {
         "filtered": {
            "filter": {
               "bool": {
                  "must": [
                    {
                        "term" : { "foo" : "bar" }
                    }
                  ]
               }
            }
         }
      }}
}

Specifying fields in queries require the use of the _source parameter. The individual fields are passed in as a list of string. Note that these fields are generally added to whatever default fields are already being returned.

Parameter Description Location
include Array of field names to return body
exclude Array of field names to omit in the result-set body

Specifying Date Range

Date range using the Range Filter:

"expression" : {
    "query": {
    "filtered": {
      "filter": {
        "bool": {
          "must": [
            {
              "range": {
                "time_stamp": {
                  "gte": 1448064000000,
                  "lte": 1463672030000
                }
              }
            }
          ]
        }
      }
    }
}

Date Range using query parameters:

curl https://api.predikto.io/endpoint?start_time=1448064000000&end_time=1463672030000 \
-X GET \
-H "x-prd-api-token: API_TOKEN"

Date range queries are acceptable as either Range Filters or within query parameters. All time_stamps must be in milliseconds since unix epoch format.

Specifying date ranges in query parameters require the use of the start_time and end_time parameters. If they are not passed in, sensible defaults are used.

Parameter Description Location
start_time Lower bounds, in milliseconds since unix epoch path
end_time Upper bounds, in milliseconds since unix epoch path

Paging Results

If you wanted to display 10 results per page across 3 pages, the requests would like as follows:

curl https://api.predikto.io/devices/loco_1/events \
-X POST \
-H "x-prd-api-token: API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "expression" : {
        "from" : 0,
        "size" : 10,
        "query" : {...}
    }
}'

curl https://api.predikto.io/devices/loco_1/events \
-X POST \
-H "x-prd-api-token: API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "expression" : {
        "from" : 10,
        "size" : 10,
        "query" : {...}
    }
}'

curl https://api.predikto.io/devices/loco_1/events \
-X POST \
-H "x-prd-api-token: API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "expression" : {
        "from" : 20,
        "size" : 10,
        "query" : {...}
    }
}'

Expressions allow for pagination of results by using the from and size fields within the JSON body.

These fields must be unquoted Integers.

Parameter Description Required
from Number of initial results that shold be skipped. Defaults to 0.
size Number of results that should be returned. Defaults to 1000.

Appendix

Miscellaneous odd-n-ends…

Date Math

Example Range Filter using Date Math. This example return all records between, and including, now and 2 years from now.

{
  "expression": {
      "query": {
        "filtered": {
          "filter": {
            "range": 
            {
                "time_stamp": {
                    "lte": "now", 
                    "gte": "now-2y"
                }
            }
          }
        }
      } 
  }
}

Any date field supports using date math expression when using it in a filter.

The expression starts with an “anchor” date, such as now. It can then follow by a math expression, supporting +, - and / (rounding). The units supported are y (year), M (month), w (week), d (day), h (hour), m (minute), and s (second).

Examples of Date Math:

Note, when doing range type searches, and the upper value is inclusive, the rounding will properly be rounded to the ceiling instead of flooring it.

Tutorials

This section provides walk-throughs for common tasks using the REST API.

Metrics Reporting

Predikto Maintain records a number of performance metrics and projections on it’s predictions and notifications over time, for the sake of auditing, evaluation, and system tuning it can be useful to extract these metrics periodically.

There are two notions of performance metric in a recurring machine learning system: projections and historically observed metrics. A projection is the current best estimate at future performance using the most recent data, models, and system settings. Models and data are updated daily, and system settings can be updated at any time, so these projections are expected to change over time and do not represent a report of what has happened historically. As an example if a threshold is changed from 0.3 to 0.5, the projection of accuracy would show the expected accuracy of the system using the threshold of 0.5. The historically observed metrics on the other hand, are a representation of the performance of what has actually been issued. Historically issued notifications may have had different thresholds day-to-day, so the metrics can at times diverge from projections, this is expected.

In the following section we document the various metrics we expose, how to query them via the API, and an example of results that you may see from these queries.

Obtaining Tier Name

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["event_info.pretty_name", "tier_name"]
    },
    "size": 10,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"match_phrase": {"event_info.pretty_name": SEARCH_TERM}}
            ]
          }
        }
      }
    }
  }
}
'

Sample Response:

{
  "total_count": <INT>,
  "took": 2,
  "success": true,
  "message": null,
  "status_code": 200,
  "_links": null,
  "data": [
    {
      "event_info": {
        "pretty_name": <STRING>
      },
      "tier_name": <STRING>
    },
    ...
  ]
}

POST /models

Parameter Description Required Location
SEARCH_TERM Model pretty name from UI. expression

Given a Model name from the User Interface, obtain the “tier_name”.

We use a “pretty name” for user-facing displays, but in reality, the backend model name is defined as “tier_name”. You will use “tier_name” in most of the following sections when analyzing a specific model.

Total Events on Record

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.event_count*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "event_count": {
          "medium_risk": <INT>,
          "medium_risk_critical": <INT>,
          "any": <INT>,
          "low_risk_medium_risk": <INT>,
          "low_risk": <INT>,
          "critical": <INT>
        }
      }
    }
  ],
  "message": null,
  "success": true,
  "took": 1,
  "_links": null
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Model Pretty Name

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["event_info.pretty_name"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "total_count": 1,
  "took": 1,
  "success": true,
  "message": null,
  "status_code": 200,
  "_links": null,
  "data": [
    {
      "event_info": {
        "pretty_name": <STRING>
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

If needing to fetch the pretty name from a model, given a tier_name. This is the inverse of Obtaining Tier Name.

Prediction Horizon

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["threshold_windows.critical.window", "threshold_windows.low_risk.window", "threshold_windows.medium_risk.window"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "threshold_windows": {
        "medium_risk": {
          "window": <INT>
        },
        "low_risk": {
          "window": <INT>
        },
        "critical": {
          "window": <INT>
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

The prediction horizon for each risk level is presented here in number of seconds.

Projected Mean Days to Failure (L, M, C)

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.avg_days_until_failure*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "avg_days_until_failure": {
          "medium_risk": <FLOAT>,
          "medium_risk_critical": <FLOAT>,
          "any": <FLOAT>,
          "low_risk_medium_risk": <FLOAT>,
          "low_risk": <FLOAT>,
          "critical": <FLOAT>
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected Median Days to Failure (L, M, C)

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.median_days_until_failure*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
        "metrics": {
            "median_days_until_failure": {
              "medium_risk": <FLOAT>,
              "medium_risk_critical": <FLOAT>,
              "any": <FLOAT>,
              "low_risk_medium_risk": <FLOAT>,
              "low_risk": <FLOAT>,
              "critical": <FLOAT>
            }
        }   
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected Coverage (L, M, C)

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.notification_recall*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "notification_recall": {
          "medium_risk_critical": <FLOAT>,
          "low_risk": <FLOAT>,
          "any": <FLOAT>,
          "medium_risk": <FLOAT>,
          "low_risk_medium_risk": <FLOAT>,
          "critical": <FLOAT>,
          ...,
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected Precision

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.notification_precision*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "notification_precision": {
          "medium_risk_critical": <FLOAT>,
          "low_risk": <FLOAT>,
          "any": <FLOAT>,
          "medium_risk": <FLOAT>,
          "low_risk_medium_risk": <FLOAT>,
          "critical": <FLOAT>,
          ...,
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected True Positives

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.notification_precision*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "notification_precision": {
          "any_div": {
            "correct_notifications": <INT>,
            ...
          },
          "medium_risk_critical_div": {
            "correct_notifications": <INT>,
            ...
          },
          "medium_risk_div": {
            "correct_notifications": <INT>,
            ...
          },
          "low_risk_medium_risk_div": {
            "correct_notifications": <INT>,
            ...
          },
          "low_risk_div": {
            "correct_notifications": <INT>,
            ...
          },
          "critical_div": {
            "correct_notifications": <INT>,
            ...
          },
          ...,
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected False Positives

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.notification_precision*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "notification_precision": {
          "any_div": {
            "correct_notifications": <INT>,
            "notifications": <INT>
          },
          "medium_risk_critical_div": {
            "correct_notifications": <INT>,
            "notifications": <INT>
          },
          "medium_risk_div": {
            "correct_notifications": <INT>,
            "notifications": <INT>
          },
          "low_risk_medium_risk_div": {
            "correct_notifications": <INT>,
            "notifications": <INT>
          },
          "low_risk_div": {
            "correct_notifications": <INT>,
            "notifications": <INT>
          },
          "critical_div": {
            "correct_notifications": <INT>,
            "notifications": <INT>
          },
          ...,
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected # Notifications

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.notification_count*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "notification_count": {
          "medium_risk": <INT>,
          "medium_risk_critical": <INT>,
          "any": <INT>,
          "low_risk_medium_risk": <INT>,
          "low_risk": <INT>,
          "critical": <INT>
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Projected Date Histogram

curl https://api.predikto.io/models \
-X POST 
-d '{
  "expression": {
    "_source": {
      "include": ["metrics.days_until_failure*"]
    },
    "size": 1,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "status_code": 200,
  "total_count": 1,
  "data": [
    {
      "metrics": {
        "days_until_failure": {
          "medium_risk": {
            "<INT>": <INT>,
            "<INT>": <INT>,
            ...
            "<INT>": <INT>
          },
          "medium_risk_critical": {
            "<INT>": <INT>,
            "<INT>": <INT>,
            ...
            "<INT>": <INT>
          },
          "any": {
            "<INT>": <INT>,
            "<INT>": <INT>,
            ...
            "<INT>": <INT>
          },
          "low_risk_medium_risk": {
            "<INT>": <INT>,
            "<INT>": <INT>,
            ...
            "<INT>": <INT>
          },
          "low_risk": {
            "<INT>": <INT>,
            "<INT>": <INT>,
            ...
            "<INT>": <INT>
          },
          "critical": {
            "54": 1
          }
        }
      }
    }
  ]
}

POST /models

Parameter Description Required Location
TIER_NAME Model name expression

Historical # Notifications

curl https://api.predikto.io/notifications \
-X POST 
-d '{
  "start_time" : 1,
  "end_time" : NOW,
  "expression": {
    "size": 10,
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
              {"term": {"tier_name": TIER_NAME}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "total_count": <INT>,
  "data": [],
  "_links": null,
  "message": null,
  "success": true,
  "took": 3,
  "status_code": 200
}

POST /notifications

Parameter Description Required Location
TIER_NAME Model name expression
NOW Unixtime in milliseconds expression

Historical True Positives

curl https://api.predikto.io/notifications \
-X POST 
-d '{
  "start_time" : 1,
  "end_time" : NOW,
  "expression": {
  "size": 0,
  "_source": {
    "include": [] 
  },
  "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
                {"term": {"tier_name": TIER_NAME}},
                {"term": {"notification.is_notification": 1}}
            ],
            "should": [
              {
                "bool": {
                  "must": [
                    {"range": {"validation.critical.cnt": {"gt": 0}}},
                    {"term": {"validation.critical.issued": 1}}
                  ]
                } 
              },
              {
                "bool": {
                  "must": [
                    {"range": {"validation.medium_risk.cnt": {"gt": 0}}},
                    {"term": {"validation.medium_risk.issued": 1}}
                  ]
                } 
              },
              {
                "bool": {
                  "must": [
                    {"range": {"validation.low_risk.cnt": {"gt": 0}}},
                    {"term": {"validation.low_risk.issued": 1}}
                  ]
                } 
              }
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "message": null,
  "_links": null,
  "status_code": 200,
  "took": 0,
  "data": [],
  "total_count": <INT>,
  "success": true
}

POST /notifications

Parameter Description Required Location
TIER_NAME Model name expression
NOW Unixtime in milliseconds expression

Historical False Positives

curl https://api.predikto.io/notifications \
-X POST 
-d '{
  "start_time" : 1,
  "end_time" : NOW,
  "expression": {
  "size": 0,
  "_source": {
    "include": [] 
  },
  "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
                {"term": {"tier_name": TIER_NAME}}
            ],
            "should": [
              {
                "bool": {
                  "must": [
                    {"term": {"validation.critical.cnt": 0}},
                    {"term": {"validation.critical.issued": 1}}
                  ]
                } 
              },
              {
                "bool": {
                  "must": [
                    {"term": {"validation.medium_risk.cnt": 0}},
                    {"term": {"validation.medium_risk.issued": 1}}
                  ]
                } 
              },
              {
                "bool": {
                  "must": [
                    {"term": {"validation.low_risk.cnt": 0}},
                    {"term": {"validation.low_risk.issued": 1}}
                  ]
                } 
              }
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "message": null,
  "_links": null,
  "status_code": 200,
  "took": 0,
  "data": [],
  "total_count": <INT>,
  "success": true
}

POST /notifications

Parameter Description Required Location
TIER_NAME Model name expression
NOW Unixtime in milliseconds expression

Notifications Which Covered a Specific Event

curl https://api.predikto.io/notifications \
-X POST 
-d '{
  "start_time" : 1,
  "end_time" : NOW,
  "expression": {
    "size": 10,
    "_source": {
      "include": [] 
    },
    "query": {
      "filtered": {
        "filter": {
          "bool": {
            "must": [
                {"term": {"tier_name": TIER_NAME}},
                {"term": {"notification.is_notification": 1}}
            ],
            "should": [
              {"match": {"validation.critical.docs": EVENT_ID}},
              {"match": {"validation.medium_risk.docs": EVENT_ID}},
              {"match": {"validation.low_risk.docs": EVENT_ID}}
            ]
          }
        }
      }
    }
  }
}'

Sample Response:

{
  "message": null,
  "_links": null,
  "status_code": 200,
  "took": 2,
  "data": [
    {
      "_id": <NOTIFICATION_ID>,
      ...,
    }
  ],
  "total_count": <INT>,
  "success": true
}

POST /notifications

Parameter Description Required Location
TIER_NAME Model name expression
NOW Unixtime in milliseconds expression

REST API Conventions

Character Encoding

curl https://api.predikto.io/status \
-X GET \
-H "Content-Type: application/json" 

The REST API uses UTF-8 character encoding. Request headers should include a Content-Type of application/json.

Errors and HTTP Responses

The Predikto API adheres to commonly accepted REST principles when handling responses and error scenarios.

Response Body

A standard response envelope looks as follows:

{
    "status_code": 200,
    "success": true,
    "_links": {
        "self" : "a_link"
    },
    "data": [
    {
        "name": "Sample Name",
        "descr": "Sample Description",
        "_links": {
            "self" : "a_link"
        }
    }]
}

The Predikto REST API has a standard response envelope and a uniform way of returning errors and status codes. A response will contain standard an HTTP Status Code in the Header and additionally information in the body.

Key Description
status_code INTEGER - The HTTP Status Code of the response.
success BOOLEAN - Whether the call was successful. ie. false denotes an error occurred.
data ARRAY - Resources requested from a GET call.

A sample Error response:

{
    "documentation_url": "http://docs.predikto.io/",
    "message": "API Token missing!",
    "status_code": 401,
    "success": false
}

Response Header

Sample Header response:

Access-Control-Allow-Credentials → true
Access-Control-Allow-Origin → *
Connection → keep-alive
Content-Length → 65
Content-Type → application/json
Date → Wed, 25 Feb 2015 20:33:13 GMT
Status → 200
X-Execution-Time → 0
X-Predikto-Version → v1

In addition to response body data, Predikto also responds with header variables in a standard format.

Key Description
Access-Control-Allow-Credentials CORS Headers
Access-Control-Allow-Origin CORS Headers
Content-Type Response should normally be in JSON
Date Server Time
Status HTTP Status Code
X-Execution-Time Round-trip time from request to response.
X-Predikto-Version REST API version, in the format: v#

HTTP Status Codes

All response codes are included in the HTTP Status response header and the status_code`key in the response body.

Possible status codes include:

Code Error
200 Success (upon a successful GET, PUT, or DELETE request)
201 Created (upon a successful POST request)
400 Resource Invalid (improperly formatted request)
401 Unauthorized (incorrect or missing authentication credentials)
404 Resource Not Found
405 Method Not Allowed
413 Request Entity Too Large
500 Application Error

Method-Specific Responses

Take note that the behavior of specific method types on response may differ:

POST

Successful POST requests will return a status code of 201, and include the JSON representation of the resource in the body of the response.

PUT

Successful PUT requests will return a status code of 200, and include the JSON representation of the resource in the body of the response.

DELETE

Successful DELETE requests will return a status code of 200, and no body.

HATEOAS

Sample HATEOS links embedded in response:

{
     "name": "Sample Report",
     "descr": "A Report with Predictive Results",
     "_links":
     {
         "self": "https://api.predikto.io/reports/17",
         "collection": "https://api.predikto.io/reports"
     }
}

Each API call response includes an array of HATEOAS (Hypermedia as the Engine of Application State) links. HATEOAS allows you to process hyperlinks programatically, removing the the need to hard-code logic into your application in order to use our API. We provide HATEOAS links for each call, if available.

The table below describes the possible HATEOAS links you may encounter in a response:

Element Description
self Link to retrieve more information about this resource.
collection Link to the collection (plural) of this resource.
next When paginating, the link to the next page of the resource collection.
prev When paginating, the link to the previous page of the resource collection.

Cross-Origin Resource Sharing

The REST API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

Versions

The X-Predikto-Version header response variable references the current Predikto API version, and not necessarily the version you requested.

This documentation covers the current version of the Predikto REST API, Version 2.x. Future versions will be backward-compatible up to one major versions behind.

By default, not specifying a version on an endpoint request, will default to the most recent version deployed.

Developer Resources

Query DSL Development

Developers with access to the Predikto user interface in the cloud, can use Chrome developer tools to inspect and test custom queries. The Developer Tools Network tab allows developers access to inspect the actual queries being requested of the REST API. They can then copy/paste/alter these queries and issue cURL or Postman requests.

Developer Tools

Data Input Standards

Predikto has standardized the format of input data and the naming of input files, to better ease the processing of machine data.

Data Format

An example data-set containing two events from the same device (device_id)

{
      "time_stamp": 1429291259,
      "device_id": "1000",
      "event": 0,
      "vibration_reading": 1.2342,
      "temperature": 80.5,
      "humidity": "25%",
      "color" : "red",
      "enabled" : true,
      "height" : 25,
      "lat" : 34.234,
      "lon" : -85.342
}\n
{
      "time_stamp": 1429291289,
      "device_id": "1000",
      "event": 0,
      "vibration_reading": null,
      "temperature": 80.5,
      "humidity": "25%",
      "color" : "blue",
      "enabled" : true,
      "height" : 19,
      "lat" : 37.234,
      "lon" : -82.342
}\n

Predikto API requires a standardized JSON input format, where the following fields are mandatory and reserved:

Field Description
time_stamp a unix timestamp (seconds since epoch)
device_id a String tying a record to a specific device
event binary or categorical integer indicating the event of interest (what is to be predicted)
lat/lon (Optional) If distributed assets, pass float-format signed lat and lon values.
parent_id (Optional) If the device_id is a child of a parent system, it should be noted here. Otherwise, Predikto assumes parent_id == device_id

All other fields are key-value pairs with the features to be sent (i.e. dimensional attributes or sensor signals), with the following caveats:

File Naming Conventions

When using one of the SDKs or the REST API, your filename will be set for you. Regardless of the name of the actual file you intend to upload, Predikto will rename the file within your project repository to a standard naming format: <project_name>_UNIXTIMESTAMP

Uploading data to Amazon S3

Follow the steps below to upload data to Amazon S3. This page describes using a Secure FTP Client to upload the initial batch of data, and the use of the Amazon CLI to schedule (ie. cron) uploads on an ongoing basis.

Individual Amazon S3 objects can range in size from a minimum of 0 bytes to a maximum of 5 terabytes. The largest object that can be uploaded in a single PUT is 5 gigabytes. For objects larger than 100 megabytes, customers should consider using the Multipart Upload capability. Most SFTP clients support multi-part uploading.

Initial Batch Upload

Step 1: Get your credentials

Your account contact will provide authentication and S3 bucket details to you. What you will get is:

  1. AWS Access Key ID
  2. AWS Access Key Secret
  3. Bucket name

Step 2: Configure the SFTP client

First, install an S3-compatible client. We prefer using Cyberduck.

Once installed, you will use your AWS Access Key ID, AWS Access Key Secret, and Bucket name to configure the client.

S3 Upload

Once connected, you should be able to drag and drop files on to the bucket.

Frequency-driven Uploads

Step 1: Get your credentials

Your account contact will provide authentication and S3 bucket details to you. What you will get is:

  1. AWS Access Key ID
  2. AWS Access Key Secret
  3. Bucket name

Step 3: Install the AWS CLI

The installation of the the AWS CLI, requires python and pip to be installed. This page covers installation of the entire suite.

In-depth instructions for this CLI are kept here

The quickest way to get started is to run the aws configure command, as seen on the right:

    $ aws configure
    AWS Access Key ID: foo
    AWS Secret Access Key: bar
    Default region name [us-west-2]: us-west-2
    Default output format [None]: json

Step 4: Assemble and Upload your files

We recommend that files to be uploaded should be assembled in a working directory, and if using the AWS CLI, a crontab created to automate the transmission of these files.

Now assuming we have our files assembled daily in a directory, myDir, uploading is as simple as creating a crontab that executes the following command:

aws s3 cp myDir s3://mybucket/ --recursive

Predikto Maintain Resources

This section serves as an online reference area for developer-related Predikto Maintain concerns.

Date Formatting

Token Output
Month M 1 2 … 11 12
Mo 1st 2nd … 11th 12th
MM 01 02 … 11 12
MMM Jan Feb … Nov Dec
MMMM January February … November December
Quarter Q 1 2 3 4
Qo 1st 2nd 3rd 4th
Day of Month D 1 2 … 30 31
Do 1st 2nd … 30th 31st
DD 01 02 … 30 31
Day of Year DDD 1 2 … 364 365
DDDo 1st 2nd … 364th 365th
DDDD 001 002 … 364 365
Day of Week d 0 1 … 5 6
do 0th 1st … 5th 6th
dd Su Mo … Fr Sa
ddd Sun Mon … Fri Sat
dddd Sunday Monday … Friday Saturday
Day of Week (Locale) e 0 1 … 5 6
Day of Week (ISO) E 1 2 … 6 7
Week of Year w 1 2 … 52 53
wo 1st 2nd … 52nd 53rd
ww 01 02 … 52 53
Week of Year (ISO) W 1 2 … 52 53
Wo 1st 2nd … 52nd 53rd
WW 01 02 … 52 53
Year YY 70 71 … 29 30
YYYY 1970 1971 … 2029 2030
Y 1970 1971 … 9999 +10000 +10001
Note: This complies with the ISO 8601 standard for dates past the year 9999
Week Year gg 70 71 … 29 30
gggg 1970 1971 … 2029 2030
Week Year (ISO) GG 70 71 … 29 30
GGGG 1970 1971 … 2029 2030
AM/PM A AM PM
a am pm
Hour H 0 1 … 22 23
HH 00 01 … 22 23
h 1 2 … 11 12
hh 01 02 … 11 12
k 1 2 … 23 24
kk 01 02 … 23 24
Minute m 0 1 … 58 59
mm 00 01 … 58 59
Second s 0 1 … 58 59
ss 00 01 … 58 59
Fractional Second S 0 1 … 8 9
SS 00 01 … 98 99
SSS 000 001 … 998 999
SSSS … SSSSSSSSS 000[0..] 001[0..] … 998[0..] 999[0..]
Time Zone z or zz EST CST … MST PST
Note: as of 1.6.0, the z/zz format tokens have been deprecated from plain moment objects. Read more about it here. However, they *do* work if you are using a specific time zone with the moment-timezone addon.
Z -07:00 -06:00 … +06:00 +07:00
ZZ -0700 -0600 … +0600 +0700
Unix Timestamp X 1360013296
Unix Millisecond Timestamp x 1360013296123

Localized formats

Because preferred formatting differs based on locale, there are a few tokens that can be used to format a moment based on its locale.

There are upper and lower case variations on the same formats. The lowercase version is intended to be the shortened version of its uppercase counterpart.

Time LT 8:30 PM
Time with seconds LTS 8:30:25 PM
Month numeral, day of month, year L 09/04/1986
l 9/4/1986
Month name, day of month, year LL September 4 1986
ll Sep 4 1986
Month name, day of month, year, time LLL September 4 1986 8:30 PM
lll Sep 4 1986 8:30 PM
Month name, day of month, day of week, year, time LLLL Thursday, September 4 1986 8:30 PM
llll Thu, Sep 4 1986 8:30 PM

Number Formatting

Number Format String
10000‘0,0.0000’10,000.0000
10000.23'0,0’10,000
10000.23’+0,0’+10,000
-10000'0,0.0’-10,000.0
10000.1234'0.000’10000.123
100.1234'00000’00100
1000.1234'000000,0’001,000
10'000.00’010.00
10000.1234'0[.]00000’10000.12340
-10000’(0,0.0000)’(10,000.0000)
-0.23’.00’-.23
-0.23’(.00)’(.23)
0.23'0.00000’0.23000
0.23'0.0[0000]’0.23
1230974'0.0a’1.2m
-104000'0a’-104k
1'0o’1st
100'0o’100th