📘

Enterprise Feature in beta

This feature is only available to customers with an enterprise Platform subscription. Please get in touch to discuss enabling it on your account.

Predictor™ is the one stop shop in the EVRYTHNG platform for acquiring, training and deploying dedicated machine learning solutions. It offers a number of pre-packaged models for complex supply-chain integrity problems, which we are developing with internal and external domain experts. You can select and install models which Predictor™ trains on the data in your EVRYTHNG account. This means that the model is tailored to your processes and products. You can read more about it in our walkthrough.

A successfully trained model will transparently run predictions on actions whenever a user-generated action, for example when a user scans a product, is generated.

Please note that this API is in early development and subject to frequent changes.


📘

Change in API URL

For this API, the beta domain is https://ml.evrythng.io

API Status
Beta:
/machineLearning/models
/machineLearning/models/{modelType}
/machineLearning/models/{modelType}/{modelId}
/machineLearning/models/{modelType}/{modelId}/datasets
/machineLearning/models/{modelType}/{modelId}/datasets/{datasetId}
/machineLearning/models/{modelType}/{modelId}/deployments
/machineLearning/models/{modelType}/{modelId}/deployments/{deploymentId}
/machineLearning/models/{modelType}/{modelId}/deployments/{deploymentId}/predict


DatasetCallbackDocument Data Model

Callback payload after dataset is downloaded.

.secret (string, required)
    Secret key used to authorize calling the callback

.state (string, required, one of 'downloaded', 'running', 'failed')
    State of the dataset
{
  "required": ["secret", "state"],
  "type": "object",
  "description": "Callback payload after dataset is downloaded",
  "properties": {
    "secret": {
      "type": "string",
      "description": "Secret key used to authorize calling the callback"
    },
    "state": {
      "type": "string",
      "description": "State of the dataset",
      "enum": ["downloaded", "running", "failed"]
    }
  }
}
{
 'secret': '8c5cae4cb67544481da8f888130a131022c155dfa65e8578bf80c55dfa65',
 'state':'downloaded'}

DatasetDefinitionDocument Data Model

Object containing URLs to datasets.

.datasetUrls (array of string, required)
    One or more URLs describing the training set as URLs of 
    EVRYTHNG resources
{
  "required": ["datasetUrls"],
  "type": "object",
  "description": "Object containing URLs to datasets.",
  "properties": {
    "datasetUrls": {
      "type": "array",
      "description": "One or more URLs describing the training set as URLs of EVRYTHNG resources",
      "items": { "type": "string" },
      "minLength": 1,
      "maxLength": 65536,
      "example": ["https://api.evrythng.com/actions/all?context=true"]
    }
  }
}
{
    "datasetUrls": [
    "https://api.evrythng.com/actions/all?context=true"
  ]
}

PredictionPayloadDocument Data Model

Object containing the prediction data items.

.data (array of object, required)
    Input on which the model should generate a prediction.
{
  "required": ["data"],
  "type": "object",
  "description": "Object containing the prediction data items.",
  "properties": {
    "data": {
      "type": "array",
      "description": "Input on which the model should generate a prediction.",
      "items": {
        "type": "object"
      }
    }
  }
}
{}

DeploymentConfigDocument Data Model

An object containing a list of datasets.

.datasets (array of string, required)
    The list of datasets on which the model will be trained.
{
  "required": ["datasets"],
  "type": "object",
  "description": "An object containing a list of datasets.",
  "properties": {
    "datasets": {
      "type": "array",
      "description": "The list of datasets on which the model will be trained.",
      "items": { "type": "string" }
    }
  }
}

ModelTypePayloadDocument Data Model

Object containing the name of the model type.

.name (string, required)
    The name of the new type of model.
{
  "required": ["name"],
  "type": "object",
  "description": "Object containing the name of the model type.",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the new type of model."
    }
  }
}

ModelTypePayloadDocument Data Model

Object containing the name of the model type.

.name (string, required)
    The name of the new type of model.
{
  "required": ["name"],
  "type": "object",
  "description": "Object containing the name of the model type.",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the new type of model."
    }
  }
}

Create a model type

Creates a new model type.

POST /machineLearning/models
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ModelTypePayloadDocument
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://ml.evrythng.io/machineLearning/models\
  -d '{
  "name": "abnormalScans"
}'
HTTP/1.1 201 Created
Content-Type: application/json

{}

Read all model types

Returns a list of model types that can be activated by customers.

GET /machineLearning/models
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models
HTTP/1.1 200 OK
Content-Type: application/json

[
  "scanningAnomalies",
  "supplychainIntegrityChecks"
]

Read a model type

Returns a list of model instances. If the query parameter context is set to true, it returns information about the model type.

GET /machineLearning/models/:modelType
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models/:modelType
HTTP/1.1 200 OK
Content-Type: application/json

{}

Read a model instance

Returns metadata for a given deployed model.

GET /machineLearning/models/:modelType/:modelId
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models/:modelType/:modelId
HTTP/1.1 200 OK
Content-Type: application/json

{}

Create a training dataset

Creates a training data set. The dataset is described as an EVRYTHNG URL

POST /machineLearning/models/:modelType/:modelId/datasets
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

DatasetDefinitionDocument
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/datasets\
  -d '{}'
HTTP/1.1 201 Created
Content-Type: application/json

{}

Read all training datasets

Read a list of training datasets.

GET /machineLearning/models/:modelType/:modelId/datasets
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/datasets
HTTP/1.1 200 OK
Content-Type: application/json

{}

Read a training dataset

Read a training dataset by ID.

GET /machineLearning/models/:modelType/:modelId/datasets/:datasetId
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/datasets/:datasetId
HTTP/1.1 200 OK
Content-Type: application/json

{}

Update a training dataset

Updates a dataset and calls this endpoint when the update is complete.

PUT /machineLearning/models/:modelType/:modelId/datasets/:datasetId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

DatasetCallbackDocument (partial)
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X PUT https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/datasets/:datasetId\
  -d '{}'
HTTP/1.1 200 OK
Content-Type: application/json

{}

Create a new model deployment

Create a new model deployment of the specified model type.

POST /machineLearning/models/:modelType/:modelId/deployments
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

DeploymentConfigDocument
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/deployments\
  -d '{}'
HTTP/1.1 201 Created
Content-Type: application/json

{}

Read all deployed models

Returns a list of deployed models

GET /machineLearning/models/:modelType/:modelId/deployments
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/deployments
HTTP/1.1 200 OK
Content-Type: application/json

[
    "b685b9ff7eac4f1981de264606709955",
  "7ebdb541b06847409b8ab41059530949",
  "6953ac88f6ae4eb08a17d614beba7d4c"
]

Read a model deployment

Returns metadata about a model deployment.

GET /machineLearning/models/:modelType/:modelId/deployments/:deploymentId
Authorization: $OPERATOR_API_KEY
curl -i \
  -H Authorization:$OPERATOR_API_KEY \
  -X GET https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/deployments/:deploymentId
HTTP/1.1 200 OK
Content-Type: application/json

{}

Creating a new prediction

Create a Prediction

POST /machineLearning/models/:modelType/:modelId/deployments/:deploymentId/predict
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

PredictionPayloadDocument
curl -i -H Content-Type:application/json \
  -H Authorization:$OPERATOR_API_KEY \
  -X POST https://ml.evrythng.io/machineLearning/models/:modelType/:modelId/deployments/:deploymentId/predict\
  -d '{
  "data": [
    {
      "id": "Upt3AYbSny3VatRRwGxSdkee",
      "createdAt": 1543059217046,
      "timestamp": 1543059217046,
      "type": "implicitScans",
      "user": "10ff93f061029f0a20273005",
      "location": {
        "latitude": 51.4779,
        "longitude": -0.0118,
        "position": {
          "type": "Point",
          "coordinates": [
            -0.0118,
            51.4779
          ]
        }
      },
      "locationSource": "geoIp",
      "context": {
        "city": "Greenwich",
        "region": "England",
        "countryCode": "GB",
        "userAgent": "Wget/1.19.5 (darwin17.5.0)",
        "timeZone": "Europe/London"
      },
      "createdByProject": "10ff93f061029f0a20273005",
      "createdByApp": "10ff93f061029f1a20273005",
      "thng": "UKPcKYGCrbkSqFRaakRbTesr",
      "product": "U5egb3EkVg8a9pRaw3mSDbQd"
    }
  ]
}'
HTTP/1.1 200 OK
Content-Type: application/json

{}