📘

Enterprise Feature in beta

This feature is available only to customers with an enterprise Platform subscription. Contact us to discuss enabling it on your account.

Predictorâ„¢ is where you get, train, and deploy dedicated machine learning solutions in the EVRYTHNG Platform. It offers several 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 that Predictorâ„¢ trains on with 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 transparently run predictions on actions whenever a user-generated action is generated, for example when a user scans a product.

Note that this API is in early development and is 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 strings, 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 objects, required)
    Input on which the model generates 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

To create a model type, send a POST request to the /machineLearning/models endpoint with the ModelTypePayloadDocument in the body.

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

To get a list of model types that can be activated by customers, send a GET request to the /machineLearning/models endpoint.

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

To get a list of model instances, send a GET request to the /machineLearning/models endpoint with the model type in the path. If the query parameter context is set to true (?context=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

To get the metadata for a deployed model, send a GET request to the /machineLearning/models endpoint with the model type and model ID in the path.

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

To create a training data set, send a POST request to the /machineLearning/models/datasets endpoint with the model type and model ID in the path and the DatasetDefinitionDocument in the body. 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

To get a list of training datasets, send a GET request to the /machineLearning/models/datasets endpoint with the model type and model ID in the path.

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

To get a training dataset, send a GET request to the /machineLearning/models/datasets endpoint with the model type, model ID, and dataset ID in the path.

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

To update a dataset, send a PUT request to the /machineLearning/models/datasets endpoint with the model type, model ID, and dataset ID in the path and the DatasetCallbackDocument in the body.

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 Model Deployment

To create a model deployment of the specified model type, send a POST request to the /machineLearning/models/deployments endpoint with the model type and model ID in the path and the DeploymentConfigDocument in the body.

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

To get a list of deployed models, send a GET request to the /machineLearning/models/deployments endpoint with the model type and model ID in the path.

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

To get metadata about a model deployment, send a GET request to the /machineLearning/models/datasets endpoint with the model type, model ID, and deployment ID in the path.

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 Prediction

To create a prediction, send a POST request to the /machineLearning/models/deployments/predict endpoint with the model type, model ID, and deployment ID in the path and the PredictionPayloadDocument in the body.

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

{}