Overview

This guide provides users with a comprehensive set of API (Application Programming Interface) to interact with the MLW (Machine Learning Workbench) microservice using REST (Representational State Transfer) over HTTP (Hypertext Transfer Protocol). The MLW microservice API allows users to perform operations on projects, resources, tasks, and import data from different sources by issuing a simple request using any HTTP client such as a web browser.

URI

A full path to the MLW microservice API resource consists of a base path and a resource path.

The base path URI (Uniform Resource Identifier) for the MLW microservice API is http://domain:port/service/mlw, where HTTP or HTTPS is the protocol name, the domain is the internet domain or network address, the port is a non-negative integer representing the port number, and service/mlw represents the application context path. The base path is static and does not change between requests; it merely identifies the server with an application on the network.

Following the base path is the resource path. It may contain path or query parameters depending on the type of request and available resources on the server. For example, a resource path projects/{projectID}/resources/{resourceID}/predict/{modelID}?type=PMML contains static path definitions such as model or data/code file, path parameter projectID, resourceID and modelID for a dynamically allocated resource, and a query parameter type=PMML.

In the following examples, http://domain:port is represented as {{ url }}.

Request

The HTTP request is a combination of a simple URI, HTTP verb GET, POST, PUT, or DELETE, request parameters, which can be in the form of a path variable, query, body, or header parameters, and message body (content).

The path variable is a variable part of otherwise static URI that denotes a set of possible resource names on the server and is denoted with curly braces. For example, the /projects/0f981b26132d412097ee5e54a257ce9f/resources.

Query parameters are appended to the URI with a question mark followed by a list of key/value pairs. A query variable annotated with the value true in the /resources/deploy?type=PMML resource path specifies that the returned PMML file should contain annotations as placed by MLW Server, in case of errors or warnings.

Header parameters are HTTP message metadata in the form of key/value pairs containing information about the message such as content type, message encoding type, authorization, etc.

Body parameters appear only in POST or PUT requests and need to be encoded by the HTTP client.

In the following examples, {{ auth }} represents the base64-encoded tenant/username:password or username:password sent as Basic Authorization headers with HTTP requests.

Response

The HTTP response message is composed of a message header and a message body. All MLW microservice response content types implement standard UTF-8 character set encoding.

The header contains response status code and header fields represented as a list of key/value pairs, i.e. Content-Type:application/json. Every response from MLW microservice contains a Content-Type header entry with one of the following internet media types (aka MIME) as value.

Errors

In error cases, standard HTTP response codes are returned. The response body can contain more information about the error, see the error media type definition below.

The error interpretations are:

Code Name Description
400 Bad Request Invalid input from the user.
401 Unauthorized Authentication has failed, or credentials were required but not provided.
404 Not Found Model or resource was not found.
409 Conflict Model or resource already exists.
500 Internal Server Error An internal error has occurred and the request could not be processed.

Projects

Operations on Machine Learning Workbench (MLW) Projects.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - List of available projects

{{url}}/service/mlw/projects

Retrieves the list of projects available in MLW.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects'
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "id": "0f981b26132d412097ee5e54a257ce9f",
            "name": "MLW Testing Trial",
            "description": "Regression tests",
            "createdAt": "2021-09-16T06:18:38.193833Z",
            "properties": [],
            "isModified": true,
            "isFreeze": false,
            "isFreezeProjectPull": false,
            "selectedVersion": "v0",
            "versions": [
                "v0"
            ],
            "resourcesCount": {
                "data": 15,
                "model": 15,
                "code": 25,
                "workflow": 0,
                "pipeline": 0,
                "nn-designer": 5,
                "totalCount": 60
            }
        }
    ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/mlw/projects"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Create a new project

{{url}}/service/mlw/projects

Creates a new project with given project name and description.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
name (string) required name for the project as body parameter
description (string) required description of the project as body parameter

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"name":"Sample Project","description":"A dummy project"}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "Sample Project",
    "description": "A dummy project",
    "createdAt": "2021-09-16T06:48:44.995815Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "",
    "versions": [],
    "resourcesCount": {
        "data": 0,
        "model": 0,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 0
    }
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects' \
--header 'Content-Type: text/plain' \
--data-raw '{"name":"Sample Project","description":"A dummy project"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/projects' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"name":"Sample Project","description":"A dummy project"}'

Example Response

409 - Conflict

{
    "message": "Project Name already exist",
    "errorCode": 409,
    "exception": "Project Exist"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/projects' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"name":"","description":"A dummy project"}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "name"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

POST - Commit the resources of the project

{{url}}/service/mlw/projects/{{projectID}}/commit

Commit the resources of project for version control. The response will be a long running task which runs in the background.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
listOfResources (list) list of resource IDs as body parameter

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/commit' \
--header 'Authorization: {{auth}}
--header 'Content-Type: application/json' \
--data-raw '{"listOfResources":["72c0673497344164a80e298f679b8139","72c0673497344164a80e298f679b8138"]}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "Sample Project",
    "createdAt": "2021-09-16T07:38:28.712732Z",
    "type": "COMMIT/PULL",
    "cronExpression": "",
    "status": "Not Scheduled",
    "individualTasks": [
        {
            "id": "656ea5",
            "pID": "140104349759232",
            "status": "RUNNING",
            "message": "In progress",
            "tasksID": "656ea4",
            "taskName": "Sample Project",
            "type": "COMMIT/PULL",
            "executedAt": "2021-09-16T07:38:28.712732Z",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "versionNumber": "v0",
            "properties": [
                {
                    "key": "verison",
                    "label": "Version",
                    "value": "v0"
                },
                {
                    "key": "output",
                    "label": "Resources Commited to the Inventory",
                    "value": "admissions.csv\nirisDataset.csv"
                }
            ]
        }
    ],
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "projectName": "Sample Project",
    "properties": [
        {
            "key": "verison",
            "label": "Version",
            "value": "v0"
        }
    ],
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "sortTime": 1631777908
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/commit' \
--header 'Content-Type: application/json' \
--data-raw '{"listOfResources":["72c0673497344164a80e298f679b8139","72c0673497344164a80e298f679b8138","72c0673497344164a80e298f679b8137","72c0673497344164a80e298f679b8136","72c0673497344164a80e298f679b8131"]}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/commit" --header "Authorization: {{auth}}"

Example Response

409 - Conflict

{'message': 'Please select files',
 'errorCode': 409,
 'exception': 'No file to Commit'}

PUT - Update existing project name and description

{{url}}/service/mlw/projects/{{projectID}}

Updates the exiting project name and description with given new project name and description.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_UPDATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project for which the name needs to be changed
name (string) required name for the project as body parameter
description (string) required description of the project as body parameter

Example Request

201 - OK

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"ProjectNameChanged","description":"A dummy project New"}'

Example Response

201 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "ProjectNameChanged",
    "description": "A dummy project",
    "createdAt": "2021-09-16T06:48:44.995815Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "",
    "versions": [],
    "resourcesCount": {
        "data": 0,
        "model": 0,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 0
    }
}

Example Request

409 - Conflict

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"ProjectNameChanged","description":"A dummy project New"}'

Example Response

409 - Conflict

{'message': 'Project Name already exist for another project, Description also same',
 'errorCode': 409,
 'exception': 'Project Name Exist'}

Example Request

401 - Unauthorized

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"ProjectNameChanged","description":"A dummy project New"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "name"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

GET - Download a project

{{url}}/service/mlw/projects/{{projectID}}/dump

To facilitate collaboration and sharing, MLW allows you to export the contents of a project as a compressed file. Download a project by encapsulating all the resources of the project as a ZIP file. The response is a long running task which runs in the background.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/dump' \
--header 'Authorization: {{auth}}
--header 'Content-Type: application/json' \

Example Response

200 - OK

{
    "id": "ecebc016f83843859e06d10cddce59ec",
    "name": "WF_download",
    "createdAt": "2022-02-09T07:54:28.111972Z",
    "type": "PROJECT_DOWNLOAD",
    "cronExpression": "",
    "status": "RUNNING",
    "individualTasks": {
        "97f42d387a534ca9902dfaff9e945a6d": {
            "pID": "140571638638336",
            "status": "RUNNING",
            "type": "PROJECT_DOWNLOAD",
            "id": "97f42d387a534ca9902dfaff9e945a6d",
            "message": "Zipping your project",
            "executedAt": "2022-02-09T08:14:51.399136Z",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "tasksID": "ecebc016f83843859e06d10cddce59ec"
        }
    },
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "sortTime": 1644394491,
    "projectName": "WF",
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "properties": [
        {
            "key": "zip_name",
            "label": "ZIP Name",
            "value": "WF_download.zip"
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/dump' \
--header 'Content-Type: application/json'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/dump" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "message": "Project with id '0f981b26132d412097ee5e54a257ce9f' not found.",
    "errorCode": 404,
    "exception": "Project not found"
}

POST - Upload a project

{{url}}/service/mlw/projects/upload

To facilitate collaboration and sharing, MLW allows you to import the contents of a project from a compressed file. Upload a project ZIP file which encapsulates all the resources. The response is a long running task which runs in the background.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
file {{file Object}}

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/upload' \
--header 'Authorization: {{auth}}
--header 'Content-Type: application/json' \
--form 'file=@"/../../WorkFlow_project.zip"'

Example Response

200 - OK

{
    "id": "395dc2be201b418b97f56f213b820de5",
    "name": "WorkFlow_project_e02232",
    "createdAt": "2022-02-09T08:24:53.045752Z",
    "type": "PROJECT_UPLOAD",
    "cronExpression": "",
    "status": "RUNNING",
    "individualTasks": {
        "ca16d85213014c6a980afacf1ebd7798": {
            "pID": "140571638638336",
            "status": "RUNNING",
            "type": "PROJECT_UPLOAD",
            "id": "ca16d85213014c6a980afacf1ebd7798",
            "message": "Uploading your project",
            "executedAt": "2022-02-09T08:24:53.046085Z",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "tasksID": "395dc2be201b418b97f56f213b820de5"
        }
    },
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "sortTime": 1644395093,
    "projectName": "WorkFlow_project_e02232",
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": ""
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/upload' \
--header 'Content-Type: application/json'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

DELETE - Delete an existing project

{{url}}/service/mlw/projects/{{projectID}}

Delete the existing project. The response will be the list of remaining projects, and the delete operation will happen in the background as a long-running task. The delete operation will remove all the tasks related to the project, and removes the notebook assets as well.

Info
If there is any running task associated with the project, the delete operation won’t be allowed until the task is completed.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \

Example Response

200 - OK

{
    "data": [
        {
            "id": "0f981b26132d412097ee5e54a257ce9f",
            "name": "MLW Testing Trial",
            "description": "Regression tests",
            "createdAt": "2021-09-16T06:18:38.193833Z",
            "properties": [],
            "isModified": false,
            "isFreeze": false,
            "isFreezeProjectPull": false,
            "selectedVersion": "v1",
            "versions": [
                "v0",
                "v1"
            ],
            "resourcesCount": {
                "data": 38,
                "model": 27,
                "code": 26,
                "workflow": 12,
                "pipeline": 3,
                "nn-designer": 5,
                "totalCount": 111
            }
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f' \
--header 'Content-Type: application/json' \

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

400 - Bad Request

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f' \
--header 'Content-Type: application/json' \

Example Response

400 - Bad Request

{
    "error": "general/internalError",
    "message": "Running task(s) found associated with projectId: 0f981b26132d412097ee5e54a257ce9f. Project delete not allowed."
}

DELETE - Delete an existing version of a project

{{url}}/service/mlw/projects/{{projectID}}?versionNumber={versionNumber}

Delete the existing version of a project. The response is the list of the remaining projects without the deleted version of the given project ID. The delete operation will happen in the background as a long-running task. It removes all the tasks related to the project, as well as the notebook assets.

Info
If there is any running task associated with the project, the delete operation won’t be allowed until the task is completed.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project
versionNumber version number to be deleted

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f?versionNumber=v0' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \

Example Response

200 - OK

{
    "data": [
        {
            "id": "0f981b26132d412097ee5e54a257ce9f",
            "name": "MLW Testing Trial",
            "description": "Regression tests",
            "createdAt": "2021-09-16T06:18:38.193833Z",
            "properties": [],
            "isModified": false,
            "isFreeze": false,
            "isFreezeProjectPull": false,
            "selectedVersion": "v1",
            "versions": [
                "v1"
            ],
            "resourcesCount": {
                "data": 38,
                "model": 27,
                "code": 26,
                "workflow": 12,
                "pipeline": 3,
                "nn-designer": 5,
                "totalCount": 111
            }
        },
        {
            "id": "0f981b26132d412097ee5e54a257ce9f",
            "name": "MLW Testing Trial 2",
            "description": "Regression tests 2",
            "createdAt": "2021-09-16T06:18:30.193833Z",
            "properties": [],
            "isModified": false,
            "isFreeze": false,
            "isFreezeProjectPull": false,
            "selectedVersion": "v0",
            "versions": [
                "v0"
            ],
            "resourcesCount": {
                "data": 8,
                "model": 2,
                "code": 2,
                "workflow": 0,
                "pipeline": 0,
                "nn-designer": 0,
                "totalCount": 12
            }
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f?versionNumber=v0' \
--header 'Content-Type: application/json' \

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

400 - Bad Request

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f?versionNumber=v0' \
--header 'Content-Type: application/json' \

Example Response

400 - Bad Request

{
    "error": "general/internalError",
    "message": "Running task(s) found associated with projectId: 0f981b26132d412097ee5e54a257ce9f. Project version delete not allowed.",
}

GET - List of available resources in a project

{{url}}/service/mlw/projects/{{projectID}}/resources

Retrieves the list of files available in the project. It contains info related to each file, counts of resources, all available version information of the selected project.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "Sample Project",
    "description": "A dummy project",
    "createdAt": "2021-09-16T07:58:21.293930Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "",
    "versions": [],
    "resources": {
        "data": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "irisDataset.csv",
                "description": "",
                "createdAt": "2021-09-16T07:58:29.494787Z",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 150
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 5
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "col1",
                            "col2",
                            "col3",
                            "col4",
                            "target"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/irisDataset.csv",
                "downloadUrl": "/download/0f981b26132d412097ee5e54a257ce9f/Data/irisDataset.csv",
                "size": 2878,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            }
        ],
        "model": [],
        "code": [],
        "pipeline": [],
        "workflow": [],
        "nn-designer": []
    },
    "resourcesCount": {
        "data": 1,
        "model": 0,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 1
    }
}

GET - Refresh the list of resources in a project

{{url}}/service/mlw/projects/{{projectID}}/resources

Scans the project structure to list any un-reported file in the system, which would have been generated by code execution or through notebook execution.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project
refresh {{True/False}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources?refresh=true' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "Sample Project",
    "description": "A dummy project",
    "createdAt": "2021-09-16T07:58:21.293930Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "",
    "versions": [],
    "resources": {
        "data": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "irisDataset.csv",
                "description": "",
                "createdAt": "2021-09-16T07:58:29.494787Z",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 150
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 5
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "col1",
                            "col2",
                            "col3",
                            "col4",
                            "target"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/irisDataset.csv",
                "downloadUrl": "/download/0f981b26132d412097ee5e54a257ce9f/Data/irisDataset.csv",
                "size": 2878,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            }
        ],
        "model": [],
        "code": [],
        "pipeline": [],
        "workflow": [],
        "nn-designer": []
    },
    "resourcesCount": {
        "data": 1,
        "model": 0,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 1
    }
}

GET - Pull data from a specific version of the project to work on

{{url}}/service/mlw/projects/{{projectID}}/resources

Pulls all the resources from the {{ < product-c8y-iot > }} inventory of the selected version of the project.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project
versionNumber {{versionNumber}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources?versionNumber=v0' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "Sample Project",
    "createdAt": "2021-09-16T08:27:08.878904Z",
    "type": "COMMIT/PULL",
    "cronExpression": "",
    "status": "Not Scheduled",
    "individualTasks": [
        {
            "id": "656ea5",
            "pID": "140106208573184",
            "status": "RUNNING",
            "message": "In progress",
            "tasksID": "656ea4",
            "taskName": "Sample Project",
            "type": "COMMIT/PULL",
            "executedAt": "2021-09-16T08:27:08.878904Z",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "versionNumber": "v0",
            "properties": [
                {
                    "key": "verison",
                    "label": "Version",
                    "value": "v0"
                },
                {
                    "key": "output",
                    "label": "Resources Commited to the Inventory",
                    "value": "irisDataset.csv"
                }
            ]
        },
        {
            "id": "656ea5",
            "pID": "140106208573184",
            "status": "RUNNING",
            "message": "In progress",
            "tasksID": "656ea4",
            "taskName": "Sample Project",
            "type": "COMMIT/PULL",
            "executedAt": "2021-09-16T08:27:39.810531Z",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "versionNumber": "v1",
            "properties": [
                {
                    "key": "verison",
                    "label": "Version",
                    "value": "v1"
                },
                {
                    "key": "output",
                    "label": "Resources Commited to the Inventory",
                    "value": "irisDataset.csv\nadmissions.csv"
                }
            ]
        },
        {
            "id": "656ea6",
            "status": "RUNNING",
            "message": "In progress",
            "tasksID": "656ea4",
            "taskName": "Sample Project",
            "type": "COMMIT/PULL",
            "executedAt": "2021-09-16T08:28:28.709415Z",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "versionNumber": "v0",
            "properties": [
                {
                    "key": "verison",
                    "label": "Version",
                    "value": "v0"
                },
                {
                    "key": "output",
                    "label": "Resources Pulled from Inventory",
                    "value": "nameOfFiles"
                }
            ],
            "pID": "140106208573184"
        }
    ],
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "projectName": "Sample Project",
    "properties": [
        {
            "key": "verison",
            "label": "Version",
            "value": "v0"
        }
    ],
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "sortTime": 1631780908
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources?versionNumber=v0'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Upload files into the Project

{{url}}/service/mlw/projects/{{projectID}}/resources

To upload the resource files to use in the project, files like csv, txt, json.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) project ID of the project
file {{file Object}}

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources' \
--header 'Authorization: {{auth}}' \
--form 'file=@/../../iris Dataset.csv'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "Sample Project",
    "description": "A dummy project",
    "createdAt": "2021-09-16T06:48:44.995815Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "",
    "versions": [],
    "resources": {
        "data": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "irisDataset.csv",
                "description": "",
                "createdAt": "2021-09-16T07:35:52.294740Z",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 150
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 5
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "col1",
                            "col2",
                            "col3",
                            "col4",
                            "target"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/irisDataset.csv",
                "downloadUrl": "/download/0f981b26132d412097ee5e54a257ce9f/Data/irisDataset.csv",
                "size": 2878,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            }
        ],
        "model": [],
        "code": [],
        "pipeline": [],
        "workflow": [],
        "nn-designer": []
    },
    "resourcesCount": {
        "data": 1,
        "model": 0,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 1
    }
}

Example Request

409 - Not Supported

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources' \
--header '{{auth}}' \
--form 'file=@/../../LogisticR.pmml'

Example Response

409 - Not Supported

{'message': 'File type not supported',
 'errorCode': 409,
 'exception': 'Contact Admin for Support'}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources' \
--form 'file=@/../../iris Dataset.csv'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Create new resource files into the Project

{{url}}/service/mlw/projects/{{projectID}}/resources/createnew

To create a new Python script.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
name {{name of the file}}
type py
projectID (string) project ID of the project

To create a new workflow file.

PARAMS
projectID (string) project ID of the project
type wf
name {{name of file}}
modelID {{modelID}}
preProcessingID {{preProcessingID}}
dataID {{dataID}}

To create a new notebook file.

PARAMS
projectID (string) project ID of the project
type ipynb
name {{name of file}}

To create a new architecture file for NN Designer.

PARAMS
projectID (string) project ID of the project
template {{template}}
type arch
name {{name of file}}

To create a new pipeline file.

PARAMS
projectID (string) project ID of the project
type pipeline
name {{name of file}}
modelID {{modelID}}
preProcessingID {{preProcessingID}}
postProcessingID {{postProcessingID}}

Example Request

200 - OK

curl --location --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/createnew" \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"type":"py","name":"samplePY"}'

Example Response

200 - OK



{ "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "Sample Project",
    "description": "A dummy project",
    "createdAt": "2021-09-16T07:58:21.293930Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "v0",
    "versions": [
        "v0",
        "v1"
    ],
 'resources': {'data': [{'id': '72c0673497344164a80e298f679b8139',
    'name': 'MD.Orig.jpg',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'IMAGE',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Data/MD.Orig.jpg',
    'size': 39675,
    'mimeType': 'image/jpeg',
    'extension': '.jpg',
    'category': 'Data'},
   {'id': '72c0673497344164a80e298f679b8138',
    'name': 'MD.Diet.jpg',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'IMAGE',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Data/MD.Diet.jpg',
    'size': 42146,
    'mimeType': 'image/jpeg',
    'extension': '.jpg',
    'category': 'Data'},
   {'id': '72c0673497344164a80e298f679b8137',
    'name': 'predicted_MD_1600753267.json',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [{'key': 'numberOfobjects',
      'label': 'Number of Objects',
      'value': 2},
     {'key': 'keysInJson',
      'label': 'keys in Dictionary',
      'value': ['Dense3', 'PredictedClass']}],
    'editedAt': '',
    'type': 'JSON',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Data/predicted_MD_1600753267.json',
    'size': 222,
    'mimeType': 'application/json',
    'extension': '.json',
    'category': 'Data'},
   {'id': '72c0673497344164a80e298f679b8136',
    'name': 'sample.zip',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'ZIP',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Data/sample.zip',
    'size': 22655457,
    'mimeType': 'application/zip',
    'extension': '.zip',
    'category': 'Data'},
   {'id': '72c0673497344164a80e298f679b8135',
    'name': 'predicted_MD_1600753576.json',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [{'key': 'numberOfobjects',
      'label': 'Number of Objects',
      'value': 2},
     {'key': 'keysInJson',
      'label': 'keys in Dictionary',
      'value': ['Dense3', 'PredictedClass']}],
    'editedAt': '',
    'type': 'JSON',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Data/predicted_MD_1600753576.json',
    'size': 235,
    'mimeType': 'application/json',
    'extension': '.json',
    'category': 'Data'},
   {'id': '72c0673497344164a80e298f679b8134',
    'name': 'admissions.csv',
    'description': '',
    'createdAt': 'Mon Sep 28 00:26:07 2020',
    'properties': [{'key': 'numberOfRows',
      'label': 'Number of Rows',
      'value': 644},
     {'key': 'numberOfColumns', 'label': 'Number of Columns', 'value': 3},
     {'key': 'columnNames',
      'label': 'Column Names',
      'value': ['target', 'gpa', 'gre']}],
    'editedAt': '',
    'type': 'CSV',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Data/admissions.csv',
    'size': 17192,
    'mimeType': 'text/csv',
    'extension': '.csv',
    'category': 'Data'}],
  'model': [{'id': '72c0673497344164a80e298f679b8141',
    'name': 'sampleNewDemo_1600751365.onnx',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'ONNX',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Model/sampleNewDemo_1600751365.onnx',
    'size': 8296336,
    'mimeType': 'application/ONNX',
    'extension': '.onnx',
    'category': 'Model',
    'deployed': True}],
  'code': [{'id': '72c0673497344164a80e298f679b8142',
    'name': 'samplePY.py',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'PY',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Code/samplePost.py',
    'size': 260,
    'mimeType': 'text/x-python',
    'extension': '.py',
    'category': 'Code'},
   {'id': '72c0673497344164a80e298f679b8145',
    'name': 'samplePre.py',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'PY',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Code/samplePre.py',
    'size': 278,
    'mimeType': 'text/x-python',
    'extension': '.py',
    'category': 'Code'}],
  'pipeline': [{'id': '72c0673497344164a80e298f679b8187',
    'name': 'samplePipe.pipeline',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [{'label': 'ONNX Model',
      'value': 'sampleNewDemo_1600751365.onnx',
      'key': 'modelID'},
     {'label': 'Pre-Processing Script',
      'value': 'samplePre.py',
      'key': 'preProcessingID'},
     {'label': 'Post-Processing Script',
      'value': 'samplePost.py',
      'key': 'postProcessingID'}],
    'editedAt': '',
    'type': 'PIPELINE',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/Pipeline/samplePipe.pipeline',
    'size': 134,
    'mimeType': 'application/PIPELINE',
    'extension': '.pipeline',
    'category': 'Pipeline',
    'deployed': True}],
  'workflow': [],
  'nn-designer': [{'id': '72c0673497344164a80e298f679b8177',
    'name': 'sample.architecture',
    'description': '',
    'createdAt': 'Fri Sep 25 09:49:29 2020',
    'properties': [],
    'editedAt': '',
    'type': 'ARCHITECTURE',
    'url': './MLW/0f981b26132d412097ee5e54a257ce9f/NN-Designer/sample.architecture',
    'size': 17176,
    'mimeType': 'application/ARCHITECTURE',
    'extension': '.architecture',
    'category': 'NN-Designer'}]},
 'resourcesCount': {'data': 6,
  'model': 1,
  'code': 2,
  'workflow': 0,
  'pipeline': 1,
  'nn-designer': 1,
  'totalCount': 11}
}

Example Request

401 - Unauthorized

curl --location --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/createnew" \
--header 'Content-Type: application/json' \
--data-raw '{"type":"py","name":"samplePY"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "type"
            ],
            "msg": "unexpected value; permitted: 'wf', 'py', 'ipynb', 'architecture', 'pipeline'",
            "type": "value_error.const",
            "ctx": {
                "given": "",
                "permitted": [
                    "wf",
                    "py",
                    "ipynb",
                    "architecture",
                    "pipeline"
                ]
            }
        }
    ]
}

GET - Get the details of the resource file

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}

Gets the details of a resource file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "samplePY.py",
    "description": "",
    "createdAt": "2021-09-16T08:35:23.743283Z",
    "properties": [],
    "editedAt": "2021-09-16T08:35:23.743283Z",
    "type": "PY",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Code/samplePY.py",
    "downloadUrl": "/download/0f981b26132d412097ee5e54a257ce9f/Code/samplePY.py",
    "size": 0,
    "mimeType": "application/CODE",
    "extension": ".py",
    "category": "Code",
    "deployed": false
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Preview the files (code/data/architecture)

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/preview

Gets the content of the code file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/preview' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "content": "def process(content):\n    import ssl\n    import requests\n    ssl._create_default_https_context = ssl._create_unverified_context\n    class_indexes = requests.get('https://storage.googleapis.com/download.tensorflow.org/data/imagenet_class_index.json').json()\n    preds = content[0]\n    results = []\n    for pred in preds:\n        top_indices = pred.argsort()[-5:][::-1]\n        result = [tuple(class_indexes[str(i)]) + (pred[i],) for i in top_indices]\n        result.sort(key=lambda x: x[2], reverse=True)\n        results.append(result)\n    contents = {}\n    contents[\"predicted_category\"] = {\n        results[0][0][1]: float(results[0][0][2])\n    }\n    contents[\"top_5_categories\"] = []\n    for pred in results[0]:\n        contents[\"top_5_categories\"].append({pred[1]:float(pred[2])})\n    return contents"
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/preview' \

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Preview the notebook file

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/jnb-content

Gets the content of the notebook file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": {
        "name": "sampleNotebook1.ipynb",
        "path": "0f981b26132d412097ee5e54a257ce9f/Code/sampleNotebook1.ipynb",
        "last_modified": "2020-09-29T23:02:37.279122Z",
        "created": "2020-09-29T23:02:37.279122Z",
        "content": {
            "cells": [],
            "metadata": {},
            "nbformat": 4,
            "nbformat_minor": 4
        },
        "format": "json",
        "mimetype": null,
        "size": 65,
        "writable": true,
        "type": "notebook"
    },
    "session": {
        "id": "bce72e99-6e7b-47dd-b236-2852936147dd",
        "path": "0f981b26132d412097ee5e54a257ce9f/Code/sampleNotebook1.ipynb",
        "name": "sampleNotebook1",
        "type": "notebook",
        "kernel": {
            "id": "caa3c162-6ee4-4021-b018-f2e19c97c403",
            "name": "python3",
            "last_activity": "2020-09-29T23:26:23.256662Z",
            "execution_state": "idle",
            "connections": 1
        },
        "notebook": {
            "path": "0f981b26132d412097ee5e54a257ce9f/Code/sampleNotebook1.ipynb",
            "name": "sampleNotebook1"
        }
    }
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

PUT - Add content to the file and save

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/save

Updates the contents of a file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_UPDATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}
content {{content}} as body parameter

Example Request

200 - OK

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/save' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"content":"def hello():\r\n    return '\''Hello'\''"}'

Example Response

200 - OK

{
    "message": "File updated successfully!",
    "data": {
        "id": "0f981b26132d412097ee5e54a257ce9f",
        "name": "sampleCode.py",
        "description": "",
        "createdAt": "Tue Sep 29 23:37:56 2020",
        "properties": [],
        "editedAt": "Tue Sep 29 23:37:56 2020",
        "type": "PY",
        "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Code/sampleCode.py",
        "size": 32,
        "mimeType": "application/CODE",
        "extension": ".py",
        "category": "Code"
    }
}

Example Request

401 - Unauthorized

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/save' \
--header 'Content-Type: text/plain' \
--data-raw '{"content":"def hello():\r\n    return '\''Hello'\''"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

DELETE - Delete the file from the Project

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}

Deletes a resource file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --request DELETE "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "Sample Project",
    "description": "A dummy project",
    "createdAt": "2021-09-16T07:58:21.293930Z",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "isFreezeProjectPull": false,
    "selectedVersion": "v0",
    "versions": [
        "v0",
        "v1"
    ],
    "resources": {
        "data": [],
        "model": [],
        "code": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "samplePY1.py",
                "description": "",
                "createdAt": "2021-09-16T08:37:05.724194Z",
                "properties": [],
                "editedAt": "2021-09-16T08:37:05.724194Z",
                "type": "PY",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Code/samplePY1.py",
                "downloadUrl": "/download/0f981b26132d412097ee5e54a257ce9f/Code/samplePY1.py",
                "size": 0,
                "mimeType": "application/CODE",
                "extension": ".py",
                "category": "Code",
                "deployed": false
            }
        ],
        "pipeline": [],
        "workflow": [],
        "nn-designer": []
    },
    "resourcesCount": {
        "data": 0,
        "model": 0,
        "code": 1,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 1
    }
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Download the file from the Project in local system

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/download

Downloads a resource file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/download' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

col1,col2,col3,col4,target
5.1,3.5,1.4,0.2,0
4.9,3.0,1.4,0.2,0
4.7,3.2,1.3,0.2,0
4.6,3.1,1.5,0.2,0
5.0,3.6,1.4,0.2,0
5.4,3.9,1.7,0.4,0
4.6,3.4,1.4,0.3,0
5.0,3.4,1.5,0.2,0
4.4,2.9,1.4,0.2,0


Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/download' \

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Tasks

Operations on MLW tasks.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - Get the list of tasks in the system

{{url}}/service/mlw/tasks

Gets the list of tasks running or completed in the system.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/tasks' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "id": "656ea4",
            "name": "sensorData2",
            "createdAt": "Mon Sep 28 10:06:49 2020",
            "type": "C8YDATA",
            "cronExpression": "",
            "status": "Not Scheduled",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "projectName": "ExampleProject",
            "properties": [
                {
                    "key": "deviceID",
                    "label": "Device ID",
                    "value": "446"
                },
                {
                    "key": "dateFrom",
                    "label": "Date From",
                    "value": "2020-07-03T06:00:00.000Z"
                },
                {
                    "key": "dateTo",
                    "label": "Date To",
                    "value": "2020-09-28T07:00:10.509Z"
                },
                {
                    "key": "columnNames",
                    "label": "Measurements",
                    "value": [
                        "sensor4",
                        "sensor2",
                        "sensor3",
                        "sensor1"
                    ]
                },
                {
                    "key": "aggregationType",
                    "label": "Aggregation Type",
                    "value": "None"
                }
            ],
            "recurrence": "ONE_TIME",
            "startDate": "",
            "startTimeH": "",
            "startTimeM": "",
            "sortTime": 1601287609
        },

    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/tasks'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get the details of a parent task

{{url}}/service/mlw/tasks/{{parenttaskID}}

Gets the details of the parent task running or completed.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
parenttaskID {{parenttaskID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/tasks/656ea4' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "sensorData2",
    "createdAt": "Mon Sep 28 10:06:49 2020",
    "type": "C8YDATA",
    "cronExpression": "",
    "status": "Not Scheduled",
    "individualTasks": [
        {
            "id": "656ea5",
            "tasksID": "656ea4",
            "taskName": "sensorData2",
            "type": "C8YDATA",
            "executedAt": "Mon Sep 28 10:06:49 2020",
            "deviceID": "446",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "fileName": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/sensorData2.csv",
            "pID": "987",
            "status": "COMPLETED",
            "dateFrom": "2020-07-03T06:00:00.000Z",
            "dateTo": "2020-09-28T07:00:10.509Z",
            "message": "Data Saved to Data Section",
            "fileSaved": true
        }
    ],
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "projectName": "ExampleProject",
    "properties": [
        {
            "key": "deviceID",
            "label": "Device ID",
            "value": "446"
        },
        {
            "key": "dateFrom",
            "label": "Date From",
            "value": "2020-07-03T06:00:00.000Z"
        },
        {
            "key": "dateTo",
            "label": "Date To",
            "value": "2020-09-28T07:00:10.509Z"
        },
        {
            "key": "columnNames",
            "label": "Measurements",
            "value": [
                "sensor4",
                "sensor2",
                "sensor3",
                "sensor1"
            ]
        },
        {
            "key": "aggregationType",
            "label": "Aggregation Type",
            "value": "None"
        }
    ],
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "sortTime": 1601287609
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/tasks/656ea4'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

DELETE - Delete a parent task

{{url}}/service/mlw/tasks/{{parenttaskID}}

Deletes and stops all the individual tasks running under a parent task and delete the parent task.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
parenttaskID {{parenttaskID}}

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/tasks/656ea4' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK
{
    "data": {
        "1600941378514": {
            "id": "1600941378514",
            "name": "cast",
            "createdAt": "Thu Sep 24 09:56:18 2020",
            "sortTime": 1600941378,
            "type": "NN",
            "individualTasks": {
                "1600941378153": {
                    "status": "COMPLETED",
                    "type": "NN",
                    "projectID": "0f981b26132d412097ee5e54a257ce9f",
                    "log": {
                        "ARCH_READ": {
                            "timestamp": "2020-09-24 09:56:18.299939",
                            "type": "INFO",
                            "message": "File read successful.",
                            "error": ""
                        },
                        "ARCH_CREATE_LAYER": {
                            "timestamp": "2020-09-24 09:56:18.301050",
                            "type": "INFO",
                            "message": "layers are ordered.",
                            "error": ""
                        },
                        "DATA_INIT": {
                            "timestamp": "2020-09-24 09:56:19.628340",
                            "type": "INFO",
                            "message": "train and validation folder exist.",
                            "error": ""
                        },
                        "DATA_PROCESS": {
                            "timestamp": "2020-09-24 09:56:19.947158",
                            "type": "INFO",
                            "message": "Data processing complete",
                            "error": ""
                        },
                        "COMPILE": {
                            "timestamp": "2020-09-24 09:56:19.948185",
                            "type": "INFO",
                            "message": "Model compilation successful",
                            "error": ""
                        },
                        "TRAIN": {
                            "timestamp": "2020-09-24 11:03:40.438399",
                            "type": "INFO",
                            "message": "Model training complete",
                            "error": ""
                        },
                        "SAVE": {
                            "timestamp": "2020-09-24 11:03:41.259142",
                            "type": "INFO",
                            "message": "Model saved successfully. --> cast_1600941378.onnx",
                            "error": ""
                        }
                    },
                    "properties": [],
                    "message": "Model Saved to Model Section",
                    "history": [
                        {
                            "epoch": 1,
                            "acc": 0.6681777238845825,
                            "loss": 0.9347285657499664,
                            "lr": 9.999999747378752e-05,
                            "val_acc": 0.7475177049636841,
                            "val_loss": 0.5210347923826664
                        },
                        {
                            "epoch": 2,
                            "acc": 0.7357207536697388,
                            "loss": 0.5306199711164019,
                            "lr": 9.999999747378752e-05,
                            "val_acc": 0.8241134881973267,
                            "val_loss": 0.4010832756757736
                        },
                        {
                            "epoch": 3,
                            "acc": 0.8236627578735352,
                            "loss": 0.3880086645267816,
                            "lr": 9.999999747378752e-05,
                            "val_acc": 0.8794326186180115,
                            "val_loss": 0.2899192896612147
                        },
                        {
                            "epoch": 4,
                            "acc": 0.8703535795211792,
                            "loss": 0.3042577663546298,
                            "lr": 9.999999747378752e-05,
                            "val_acc": 0.9290780425071716,
                            "val_loss": 0.20286435729011576
                        },
                        {
                            "epoch": 5,
                            "acc": 0.9023874402046204,
                            "loss": 0.2476639048612642,
                            "lr": 9.999999747378752e-05,
                            "val_acc": 0.9517730474472046,
                            "val_loss": 0.16410305897923225
                        }
                    ],
                    "tasksID": "1600941378514",
                    "taskName": "cast",
                    "id": "1600941378153",
                    "executedAt": "Thu Sep 24 09:56:18 2020",
                    "pID": "68",
                    "fileName": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/cast_1600941378.onnx",
                    "completedAt": "Thu Sep 24 11:03:41 2020",
                    "fileSaved": true
                }
            },
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "projectName": "blah project",
            "startDate": "2020-09-24",
            "startTimeH": "09",
            "startTimeM": "56",
            "properties": [
                {
                    "key": "problemType",
                    "label": "Problem Type",
                    "value": "classification"
                },
                {
                    "key": "optimizer",
                    "label": "Optimizer",
                    "value": "adam"
                },
                {
                    "key": "learningRate",
                    "label": "Learning Rate",
                    "value": 0.0001
                },
                {
                    "key": "loss",
                    "label": "Loss",
                    "value": "categorical_crossentropy"
                },
                {
                    "key": "metrics",
                    "label": "Metrics",
                    "value": [
                        "accuracy"
                    ]
                },
                {
                    "key": "epoch",
                    "label": "Epoch",
                    "value": 5
                },
                {
                    "key": "testSize",
                    "label": "Test Size",
                    "value": 0.3
                },
                {
                    "key": "batchSize",
                    "label": "Batch Size",
                    "value": 15
                }
            ],
            "cronExpression": "",
            "status": "NOT SCHEDULED",
            "recurrence": "ONE_TIME"
        },

    }
}

Example Request

401 - Unauthorized

curl --location --request DELETE '{{url}}/service/mlw/tasks/656ea4'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get the details of the individual task within a parent task

{{url}}/service/mlw/tasks/{{parenttaskID}}/task/{{taskID}}

Provides the complete details of the individual task running under a parent task.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
taskID {{taskID}}
parenttaskID {{parenttaskID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/tasks/656ea4/task/656ea5' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "656ea5",
    "tasksID": "656ea4",
    "taskName": "sensorData2",
    "type": "C8YDATA",
    "executedAt": "Mon Sep 28 10:06:49 2020",
    "deviceID": "446",
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "fileName": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/sensorData2.csv",
    "pID": "987",
    "status": "COMPLETED",
    "dateFrom": "2020-07-03T06:00:00.000Z",
    "dateTo": "2020-09-28T07:00:10.509Z",
    "message": "Data Saved to Data Section",
    "fileSaved": true
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/tasks/656ea4/task/656ea5'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

PUT - Early stop the neural network training task

{{url}}/service/mlw/tasks/{{parenttaskID}}/task/{{taskID}}

Triggers an early stop callback for the neural network training task

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_UPDATE

HEADERS
Authorization {{auth}}
PARAMS
taskID {{taskID}}
parenttaskID {{parenttaskID}}

Example Request

200 - OK

curl --location --request PUT '{{url}}/service/mlw/tasks/656ea4/task/1601289809_Task' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "message": "Triggered early stopping"
}

Example Request

401 - Unauthorized

curl --location --request PUT '{{url}}/service/mlw/tasks/656ea4/task/1601289809_Task'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

DELETE - Delete an individual task within the parent task

{{url}}/service/mlw/tasks/{{parenttaskID}}/task/{{taskID}}

Deletes and stops the individual task running under a parent task.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
taskID {{taskID}}
parenttaskID {{parenttaskID}}

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/tasks/656ea4/task/656ea5' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK
{
    "data": [
        {
            "id": "656ea4",
            "name": "sensorData2",
            "createdAt": "Mon Sep 28 10:06:49 2020",
            "type": "C8YDATA",
            "cronExpression": "",
            "status": "Not Scheduled",
            "individualTasks": [],
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "projectName": "ExampleProject",
            "properties": [
                {
                    "key": "deviceID",
                    "label": "Device ID",
                    "value": "446"
                },
                {
                    "key": "dateFrom",
                    "label": "Date From",
                    "value": "2020-07-03T06:00:00.000Z"
                },
                {
                    "key": "dateTo",
                    "label": "Date To",
                    "value": "2020-09-28T07:00:10.509Z"
                },
                {
                    "key": "columnNames",
                    "label": "Measurements",
                    "value": [
                        "sensor4",
                        "sensor2",
                        "sensor3",
                        "sensor1"
                    ]
                },
                {
                    "key": "aggregationType",
                    "label": "Aggregation Type",
                    "value": "None"
                }
            ],
            "recurrence": "ONE_TIME",
            "startDate": "",
            "startTimeH": "",
            "startTimeM": "",
            "sortTime": 1601287609
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request DELETE '{{url}}/service/mlw/tasks/656ea4/task/656ea5'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Settings

Operations on MLW settings.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - Get AWS S3 credentials

{{url}}/service/mlw/credentials

Fetches the AWS S3 credentials information.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/credentials' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "AWS": {
        "accessKey": "AKIA4CCIEY3EHS3VHU5Q",
        "secretKey": "*******"
    }
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/credentials'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Register AWS S3 Credentials

{{url}}/service/mlw/credentials

Registers the AWS S3 credentials information with Cumulocity IoT.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
accessKey (string) required AWS access Key body parameter
secretKey (string) required AWS secret Key body parameter
type (string) required query parameter to store a particular credentials set (for example: AWS)

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/credentials?type=AWS' \
--header 'Authorization: {{auth}}' \
--data-raw '{
    "accessKey": "AKIA4CCIEY3EHS3VHU5Q",
    "secretKey": "Ddsm****************"}'

Example Response

200 - OK

{
    "message": "Success"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/credentials?type=AWS' \
--data-raw '{
    "accessKey": "AKIA4CCIEY3EHS3VHU5Q",
    "secretKey": "Ddsm****************"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/credentials?type=AWS' \
--header 'Authorization: {{auth}}'

Example Response

409 - Conflict

{
    "message": "Missing Parameters. Please provide complete info",
    "errorCode": 409,
    "exception": "Missing Parameters"
}

DELETE - Delete AWS S3 credentials

{{url}}/service/mlw/credentials

Deletes the AWS S3 credentials information from Cumulocity IoT.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
type (string) required query parameter to delete a particular credentials set (for example: AWS)

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/credentials?type=AWS' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "message": "Success"
}

Example Request

401 - Unauthorized

curl --location --request DELETE '{{url}}/service/mlw/credentials?type=AWS'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Missing query parameter

curl --location --request DELETE '{{url}}/service/mlw/credentials' \
--header 'Authorization: {{auth}}'

Example Response

409 - Missing query parameter

{
    "message": "Missing query parameter ('type')",
    "errorCode": 409,
    "exception": "Missing query parameter"
}

AutoML

Operations on MLW Automated ML.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - Start the AutoML process

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/automl

Start the AutoML process by passing the data to the engine and get the initial information to start the AutoML process.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data_details": {
        "data": [
            {
                "position": 1,
                "variable": "col1",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 2,
                "variable": "col2",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 3,
                "variable": "col3",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 4,
                "variable": "col4",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 5,
                "variable": "target",
                "dtype": "int64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            }
        ],
        "options": {
            "changedataTypes": [
                "None",
                "Continuous",
                "Categorical"
            ],
            "imputation_methods": [
                "None",
                "Mean",
                "Median",
                "Replace with NA",
                "Most Frequent"
            ],
            "data_transformation_steps": [
                "None",
                "One Hot Encoding",
                "Label Encoding",
                "Normalize",
                "Scaling Standard",
                "Scaling Min Max",
                "Scaling Max Absolute"
            ],
            "algorithmTypes": {
                "Regression": [
                    "GradientBoostingRegressor",
                    "DecisionTreeRegressor",
                    "LinearSVR",
                    "RandomForestRegressor",
                    "XGBRegressor",
                    "KNeighborsRegressor",
                    "LinearRegression",
                    "LGBMRegressor"
                ],
                "Classification": [
                    "DecisionTreeClassifier",
                    "RandomForestClassifier",
                    "GradientBoostingClassifier",
                    "KNeighborsClassifier",
                    "LinearSVC",
                    "LogisticRegression",
                    "XGBClassifier",
                    "LGBMClassifier"
                ],
                "Anomaly": [
                    "IsolationForest",
                    "OneClassSVM"
                ]
            },
            "metics_for_models": {
                "Regression": [
                    "neg_log_loss",
                    "neg_mean_absolute_error",
                    "neg_mean_squared_error",
                    "neg_median_absolute_error",
                    "r2",
                    "roc_auc"
                ],
                "Classification": [
                    "accuracy",
                    "adjusted_rand_score",
                    "average_precision",
                    "balanced_accuracy",
                    "f1",
                    "f1_macro",
                    "f1_micro",
                    "f1_samples",
                    "f1_weighted",
                    "precision",
                    "precision_macro",
                    "precision_micro",
                    "precision_samples",
                    "precision_weighted",
                    "recall",
                    "recall_macro",
                    "recall_micro",
                    "recall_samples",
                    "recall_weighted"
                ]
            },
            "anomaly_model_parameters": {
                "IsolationForest": [
                    "n_estimators",
                    "max_samples",
                    "contamination",
                    "max_features",
                    "bootstrap"
                ],
                "OneClassSVM": [
                    "kernel",
                    "degree",
                    "gamma",
                    "tol",
                    "nu",
                    "shrinking",
                    "cache_size",
                    "max_iter"
                ]
            }
        },
        "idforData": "656ea4"
    }
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Start the training process of the AutoML

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/automl

Train an AutoML model by using pre-processing options for variables and using the hyper-parameter given by the user in the form.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}
data filled form values as body parameter
idforData required description of the project as body parameter
target_variable column name which is target as body parameter
problem_type Classification/Regression as body parameter
HYPER- PARAMS
algorithm Selected Algorithms
generation integer
population_size integer
model_name name
scoring select one of the option

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"data_details":{"data":[{"position":1,"variable":"col1","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":false},{"position":2,"variable":"col2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":3,"variable":"col3","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":4,"variable":"col4","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":5,"variable":"target","dtype":"int64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true}],"problem_type":"Classification","target_variable":"col1","idforData":"656ea4","newPMMLFileName":"sampleClassifiactionModel","parameters":{"generation":5,"population_size":25,"model_name":"sampleClassifiactionModel","scoring":"accuracy","algorithm":["DecisionTreeClassifier","RandomForestClassifier","GradientBoostingClassifier","KNeighborsClassifier","LinearSVC","LogisticRegression","XGBClassifier","LGBMClassifier"]}}}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "sampleClassifiactionModel2",
    "createdAt": "2021-09-16T09:01:36.773619Z",
    "type": "AUTOML",
    "cronExpression": "",
    "status": "Not Scheduled",
    "individualTasks": [
        {
            "targetVar": "col1",
            "problem_type": "Classification",
            "id": "656ea4",
            "tasksID": "656ea4",
            "shape": [
                150,
                5
            ],
            "executedAt": "2021-09-16T09:01:36.773619Z",
            "taskName": "sampleClassifiactionModel2",
            "type": "AUTOML",
            "listOfModelAccuracy": [],
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "status": "RUNNING",
            "message": "In progress"
        }
    ],
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "projectName": "Sample Project",
    "properties": [
        {
            "key": "data",
            "label": "Data Used",
            "value": "irisDataset.csv"
        },
        {
            "key": "targetVar",
            "label": "Target variable",
            "value": "col1"
        },
        {
            "key": "problem_type",
            "label": "Problem Type",
            "value": "Classification"
        },
        {
            "key": "dataSize",
            "label": "Data Size",
            "value": [
                150,
                5
            ]
        },
        {
            "key": "model_name",
            "label": "Model Name",
            "value": "sampleClassifiactionModel2"
        },
        {
            "key": "alogrithm",
            "label": "Algorithms Size",
            "value": [
                "DecisionTreeClassifier",
                "RandomForestClassifier",
                "GradientBoostingClassifier",
                "KNeighborsClassifier",
                "LinearSVC",
                "LogisticRegression",
                "XGBClassifier",
                "LGBMClassifier"
            ]
        },
        {
            "key": "population_size",
            "label": "Population Size",
            "value": 25
        },
        {
            "key": "generation",
            "label": "Generation",
            "value": 5
        },
        {
            "key": "scoring_type",
            "label": "Scoring type",
            "value": "accuracy"
        }
    ],
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "sortTime": 1631782896
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl' \
--data-raw '{"data_details":{"data":[{"position":1,"variable":"col1","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":false},{"position":2,"variable":"col2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":3,"variable":"col3","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":4,"variable":"col4","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":5,"variable":"target","dtype":"int64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true}],"problem_type":"Classification","target_variable":"col1","idforData":"656ea4","newPMMLFileName":"sampleClassifiactionModel","parameters":{"generation":5,"population_size":25,"model_name":"sampleClassifiactionModel","scoring":"accuracy","algorithm":["DecisionTreeClassifier","RandomForestClassifier","GradientBoostingClassifier","KNeighborsClassifier","LinearSVC","LogisticRegression","XGBClassifier","LGBMClassifier"]}}}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl' \
--data-raw '{"data_details":{"data":[{"position":1,"variable":"col1","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":false},{"position":2,"variable":"col2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":3,"variable":"col3","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":4,"variable":"col4","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":5,"variable":"target","dtype":"int64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true}],"problem_type":"Classification","target_variable":"col1","idforData":"656ea4","newPMMLFileName":"sampleClassifiactionModel","parameters":{"generation":5,"population_size":25,"model_name":"","scoring":"accuracy","algorithm":["DecisionTreeClassifier","RandomForestClassifier","GradientBoostingClassifier","KNeighborsClassifier","LinearSVC","LogisticRegression","XGBClassifier","LGBMClassifier"]}}}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "model_name"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

GET - Start the Anomaly detection model training process

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/automl

Start the Anomaly detection model training process by passing the data to the engine and get the initial information to start the training.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data_details": {
        "data": [
            {
                "position": 1,
                "variable": "time",
                "dtype": "object",
                "missing_val": 0,
                "changedataType": "Categorical",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 2,
                "variable": "Sensor1_temperature2",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 3,
                "variable": "Sensor1_temperature1",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            },
            {
                "position": 4,
                "variable": "Sensor1_pressure2",
                "dtype": "float64",
                "missing_val": 0,
                "changedataType": "Continuous",
                "imputation_method": "None",
                "data_transformation_step": "None",
                "use_for_model": true
            }
        ],
        "options": {
            "changedataTypes": [
                "None",
                "Continuous",
                "Categorical"
            ],
            "imputation_methods": [
                "None",
                "Mean",
                "Median",
                "Replace with NA",
                "Most Frequent"
            ],
            "data_transformation_steps": [
                "None",
                "One Hot Encoding",
                "Label Encoding",
                "Normalize",
                "Scaling Standard",
                "Scaling Min Max",
                "Scaling Max Absolute"
            ],
            "algorithmTypes": {
                "Regression": [
                    "GradientBoostingRegressor",
                    "DecisionTreeRegressor",
                    "LinearSVR",
                    "RandomForestRegressor",
                    "XGBRegressor",
                    "KNeighborsRegressor",
                    "LinearRegression",
                    "LGBMRegressor"
                ],
                "Classification": [
                    "DecisionTreeClassifier",
                    "RandomForestClassifier",
                    "GradientBoostingClassifier",
                    "KNeighborsClassifier",
                    "LinearSVC",
                    "LogisticRegression",
                    "XGBClassifier",
                    "LGBMClassifier"
                ],
                "Anomaly": [
                    "IsolationForest",
                    "OneClassSVM"
                ]
            },
            "metics_for_models": {
                "Regression": [
                    "neg_log_loss",
                    "neg_mean_absolute_error",
                    "neg_mean_squared_error",
                    "neg_median_absolute_error",
                    "r2",
                    "roc_auc"
                ],
                "Classification": [
                    "accuracy",
                    "adjusted_rand_score",
                    "average_precision",
                    "balanced_accuracy",
                    "f1",
                    "f1_macro",
                    "f1_micro",
                    "f1_samples",
                    "f1_weighted",
                    "precision",
                    "precision_macro",
                    "precision_micro",
                    "precision_samples",
                    "precision_weighted",
                    "recall",
                    "recall_macro",
                    "recall_micro",
                    "recall_samples",
                    "recall_weighted"
                ]
            },
            "anomaly_model_parameters": {
                "IsolationForest": [
                    "n_estimators",
                    "max_samples",
                    "contamination",
                    "max_features",
                    "bootstrap"
                ],
                "OneClassSVM": [
                    "kernel",
                    "degree",
                    "gamma",
                    "tol",
                    "nu",
                    "shrinking",
                    "cache_size",
                    "max_iter"
                ]
            }
        },
        "idforData": "656ea4"
    }
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl' \

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Start the training process of the Anomaly detection model

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/anomaly

Train an Anomaly detection model by using pre-processing options for variables and using the model options given by the user in the form.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}
data filled form values as body parameter
idforData required description of the project as a body parameter
HYPER- PARAMS
algorithm selected algorithms

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/anomaly' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"data_details":{"data":[{"position":1,"variable":"time","dtype":"object","missing_val":0,"changedataType":"Categorical","imputation_method":"None","data_transformation_step":"None","use_for_model":false},{"position":2,"variable":"Sensor1_temperature2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":3,"variable":"Sensor1_temperature1","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":4,"variable":"Sensor1_pressure2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true}],"idforData":"656ea4","newPMMLFileName":"sampleAnomaly","parameters":{"n_estimators":100,"max_samples":"auto","contamination":0.5,"max_features":1,"bootstrap":false,"algorithm":"IsolationForest","model_name":"sampleAnomaly"}}}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "sampleAnomaly2",
    "createdAt": "2021-09-16T09:07:23.487543Z",
    "type": "ANOMALY",
    "cronExpression": "",
    "status": "Not Scheduled",
    "individualTasks": [
        {
            "status": "RUNNING",
            "message": "In progress",
            "problem_type": "Anomaly",
            "id": "656ea4",
            "tasksID": "656ea4",
            "shape": [
                106,
                4
            ],
            "taskName": "sampleAnomaly2",
            "type": "ANOMALY",
            "executedAt": "2021-09-16T09:07:23.487543Z",
            "listOfModelAccuracy": [],
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "pID": "140106208573184"
        }
    ],
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "projectName": "Sample Project",
    "properties": [
        {
            "key": "data",
            "label": "Data Used",
            "value": "anomalySampleData.csv"
        },
        {
            "key": "problem_type",
            "label": "Problem Type",
            "value": "Anomaly"
        },
        {
            "key": "dataSize",
            "label": "Data Size",
            "value": [
                106,
                4
            ]
        },
        {
            "key": "model_name",
            "label": "Model Name",
            "value": "sampleAnomaly2"
        },
        {
            "key": "alogrithm",
            "label": "Algorithms Size",
            "value": "IsolationForest"
        }
    ],
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "sortTime": 1631783243
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/anomaly' \
--header 'Content-Type: application/json' \
--data-raw '{"data_details":{"data":[{"position":1,"variable":"time","dtype":"object","missing_val":0,"changedataType":"Categorical","imputation_method":"None","data_transformation_step":"None","use_for_model":false},{"position":2,"variable":"Sensor1_temperature2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":3,"variable":"Sensor1_temperature1","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":4,"variable":"Sensor1_pressure2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true}],"idforData":"656ea4","newPMMLFileName":"sampleAnomaly","parameters":{"n_estimators":100,"max_samples":"auto","contamination":0.5,"max_features":1,"bootstrap":false,"algorithm":"IsolationForest","model_name":"sampleAnomaly"}}}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/anomaly' \
--header 'Content-Type: application/json' \
--data-raw '{"data_details":{"data":[{"position":1,"variable":"time","dtype":"object","missing_val":0,"changedataType":"Categorical","imputation_method":"None","data_transformation_step":"None","use_for_model":false},{"position":2,"variable":"Sensor1_temperature2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":3,"variable":"Sensor1_temperature1","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true},{"position":4,"variable":"Sensor1_pressure2","dtype":"float64","missing_val":0,"changedataType":"Continuous","imputation_method":"None","data_transformation_step":"None","use_for_model":true}],"idforData":"656ea4","newPMMLFileName":"sampleAnomaly","parameters":{"n_estimators":100,"max_samples":"auto","contamination":0.5,"max_features":1,"bootstrap":false,"algorithm":"IsolationForest","model_name":""}}}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "model_name"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

Cumulocity data pull

Operations on MLW data connectors - Data pull from Cumulocity IoT.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - Get the list of devices from the C8Y inventory

{{url}}/service/mlw/listDevices

Gets the list of devices from the C8Y inventory.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/listDevices' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "additionParents": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373/additionParents",
                "references": []
            },
            "owner": "vinayvinkumar@sag.com",
            "childDevices": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373/childDevices",
                "references": []
            },
            "childAssets": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373/childAssets",
                "references": []
            },
            "creationTime": "2020-09-15T12:43:07.121Z",
            "lastUpdated": "2020-09-15T12:43:07.121Z",
            "childAdditions": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373/childAdditions",
                "references": []
            },
            "name": "robot",
            "assetParents": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373/assetParents",
                "references": []
            },
            "deviceParents": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373/deviceParents",
                "references": []
            },
            "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/373",
            "id": "373",
            "c8y_IsDevice": {},
            "c8y_SupportedMeasurements": [
                "Sensor1"
            ],
            "c8y_SupportedOperations": [
                "c8y_Restart",
                "c8y_Configuration",
                "c8y_Software",
                "c8y_Firmware",
                "c8y_Command"
            ]
        },
        {
            "additionParents": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446/additionParents",
                "references": []
            },
            "owner": "vinayvinkumar@sag.com",
            "childDevices": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446/childDevices",
                "references": []
            },
            "childAssets": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446/childAssets",
                "references": []
            },
            "creationTime": "2020-09-15T12:44:39.791Z",
            "lastUpdated": "2020-09-15T12:44:39.791Z",
            "childAdditions": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446/childAdditions",
                "references": []
            },
            "name": "IoT_Robot",
            "assetParents": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446/assetParents",
                "references": []
            },
            "deviceParents": {
                "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446/deviceParents",
                "references": []
            },
            "self": "http://t71836.basic.stage.c8y.io/inventory/managedObjects/446",
            "id": "446",
            "c8y_IsDevice": [],
            "c8y_SupportedMeasurements": [
                "Sensors"
            ],
            "c8y_SupportedOperations": [
                "c8y_Restart",
                "c8y_Configuration",
                "c8y_Software",
                "c8y_Firmware",
                "c8y_Command"
            ]
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/automl'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get the list of measurements from the C8Y inventory

{{url}}/service/mlw/listDevices/{{deviceID}}

Gets the list of measurements from the C8Y inventory.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
deviceID (string) device ID of the registered device

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/listDevices/446' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        "sensor4",
        "sensor2",
        "sensor3",
        "sensor1"
    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/listDevices/446' \

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

POST - Download the data from the inventory for the selected device ID

{{url}}/service/mlw/projects/{{projectID}}/resources/importFromCumulocity/data

Downloads the data in the data section from Cumulocity IoT inventory wih given aggregation, it is a long running process.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) {{project ID}}
resourceID (string) {{resource ID}}
fileName name of the file as body parameter
dateFrom date from as body parameter
timeFromH time from (hour) as body parameter
timeFromM time from (minute) as body parameter
dateTo date to as body parameter
timeToH time to (hour) as body parameter
timeToM time to (minute) as body parameter
source device ID as body parameter
series list of measurement names as body parameter

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/importFromCumulocity/data' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"fileName":"sensorData2","dateFrom":"2020-07-03T06:00:00.000Z","timeFromH":11,"timeFromM":30,"dateTo":"2020-09-28T07:00:10.509Z","timeToH":12,"timeToM":30,"source":"446","series":["sensor4","sensor2","sensor3","sensor1"]}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "sensorData2",
    "createdAt": "Mon Sep 28 10:06:49 2020",
    "type": "C8YDATA",
    "cronExpression": "",
    "status": "Not Scheduled",
    "individualTasks": [
        {
            "id": "656ea5",
            "tasksID": "656ea4",
            "taskName": "sensorData2",
            "type": "C8YDATA",
            "executedAt": "Mon Sep 28 10:06:49 2020",
            "deviceID": "446",
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "fileName": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/sensorData2.csv",
            "pID": "987",
            "status": "In Progress"
        }
    ],
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "projectName": "ExampleProject",
    "properties": [
        {
            "key": "deviceID",
            "label": "Device ID",
            "value": "446"
        },
        {
            "key": "dateFrom",
            "label": "Date From",
            "value": "2020-07-03T06:00:00.000Z"
        },
        {
            "key": "dateTo",
            "label": "Date To",
            "value": "2020-09-28T07:00:10.509Z"
        },
        {
            "key": "columnNames",
            "label": "Measurements",
            "value": [
                "sensor4",
                "sensor2",
                "sensor3",
                "sensor1"
            ]
        },
        {
            "key": "aggregationType",
            "label": "Aggregation Type",
            "value": "None"
        }
    ],
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "sortTime": 1601287609
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/importFromCumulocity/data' \
--data-raw '{"fileName":"sensorData2","dateFrom":"2020-07-03T06:00:00.000Z","timeFromH":11,"timeFromM":30,"dateTo":"2020-09-28T07:00:10.509Z","timeToH":12,"timeToM":30,"source":"446","series":["sensor4","sensor2","sensor3","sensor1"]}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/importFromCumulocity/data' \
--data-raw '{"fileName":"","dateFrom":"2020-07-03T06:00:00.000Z","timeFromH":11,"timeFromM":30,"dateTo":"2020-09-28T07:00:10.509Z","timeToH":12,"timeToM":30,"source":"446","series":["sensor4","sensor2","sensor3","sensor1"]}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "fileName"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

DataHub data pull

Operations on MLW data connectors - Data pull from Cumulocity IoT DataHub.

POST - Pull data from DataHub

{{url}}/service/mlw/projects/{{projectID}}/resources/importFromDatahub/data

Pulls the data with the given query from Cumulocity IoT DataHub.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
sql (string) required SQL query body parameter to pull the data
fileName (string) required file name body parameter to store the pulled data

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/importFromDatahub/data' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"sql":"select * from t23897369DataLake.\"c8y-dremio\".t23897369.alarms","fileName":"cdhData"}'

Example Response

200 - OK

{'id': '656ea4',
 'name': 'cdhData',
 'createdAt': 'Mon Aug  3 12:28:08 2020',
 'type': 'DATAHUB',
 'cronExpression': '',
 'status': 'RUNNING',
 'individualTasks': {'656ea5': {'pID': '20432',
   'status': 'RUNNING',
   'type': 'DATAHUB',
   'id': '656ea5',
   'message': 'Pulling Data from DataHub',
   'executedAt': 'Mon Aug  3 12:28:08 2020'}},
 'projectID': '0f981b26132d412097ee5e54a257ce9f',
 'projectName': 'DemoProject',
 'recurrence': 'ONE_TIME',
 'startDate': '',
 'startTimeH': '',
 'startTimeM': '',
 'properties': [{'key': 'file_name',
   'label': 'File Name',
   'value': 'cdhData'}]}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/importFromDatahub/data' \
--header 'Content-Type: application/json' \
--data-raw '{"sql":"select * from t23897369DataLake.\"c8y-dremio\".t23897369.alarms","fileName":"cdhData"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/projects/{{projectID}}/resources/importFromDatahub/data' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"sql":"select * from t23897369DataLake.\"c8y-dremio\".t23897369.alarms","fileName":"cdhData"}'

Example Response

409 - Conflict

{
    "message": "File name already exists. Please provide another name",
    "errorCode": 409,
    "exception": "Duplicate name"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/projects/{{projectID}}/resources/importFromDatahub/data' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"sql":"select * from t23897369DataLake.\"c8y-dremio\".t23897369.alarms","fileName":""}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "fileName"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

AWS S3 data pull

Operations on MLW data connectors - Download files from AWS S3.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - Names of all AWS S3 buckets

{{url}}/service/mlw/downloadFromS3/buckets

List names of all AWS S3 buckets.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/downloadFromS3/buckets' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json'

Example Response

200 - OK

{
    "data": [
        {
            "id": "c8y-checkmarx-scan",
            "name": "c8y-checkmarx-scan"
        },
        {
            "id": "mlwbucket",
            "name": "mlwbucket"
        },
        {
            "id": "pmml-xsd",
            "name": "pmml-xsd"
        },
        {
            "id": "zementis-server-10504",
            "name": "zementis-server-10504"
        },
        {
            "id": "zementis.test",
            "name": "zementis.test"
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/downloadFromS3/buckets' \
--header 'Content-Type: application/json'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Names of all files within an AWS S3 bucket

{{url}}/service/mlw/downloadFromS3/{{bucketName}}/files

Lists the names of all files within an AWS S3 buckets.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
bucketName (string) required path variable of an existing AWS S3 bucket name

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/downloadFromS3/mlwbucket/files' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json'

Example Response

200 - OK

{
    "data": [
        {
            "id": "ZADDrinking.png",
            "name": "ZADDrinking.png",
            "size": 78109
        },
        {
            "id": "admissions.csv",
            "name": "admissions.csv",
            "size": 17192
        },
        {
            "id": "admissionstest.json",
            "name": "admissionstest.json",
            "size": 35854
        },
        {
            "id": "casting_data.zip",
            "name": "casting_data.zip",
            "size": 72256364
        },
        {
            "id": "identationError.py",
            "name": "identationError.py",
            "size": 68
        },
        {
            "id": "mlwfiles/2ndfolder/cast_def_0_9921.png",
            "name": "mlwfiles/2ndfolder/cast_def_0_9921.png",
            "size": 10947
        },
        {
            "id": "mlwfiles/anomalySampleData.csv",
            "name": "mlwfiles/anomalySampleData.csv",
            "size": 8004
        },
        {
            "id": "mob.ipynb",
            "name": "mob.ipynb",
            "size": 48499
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/downloadFromS3/mlwbucket/files' \
--header 'Content-Type: application/json'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request GET '{{url}}/service/mlw/downloadFromS3/nomlwbucket/files' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json'

Example Response

404 - Not Found

{
    "message": "The specified bucket does not exist",
    "errorCode": 404,
    "exception": "invalid/error"
}

POST - Download a file from AWS S3 bucket

{{url}}/service/mlw/projects/{{projectID}}/resources/downloadFromS3/{{bucketName}}/download

Downloads the file from AWS S3 bucket.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
bucketName (string) required path variable of an existing AWS bucket name
name (string) required name body parameter to download an existing file from AWS S3

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/downloadFromS3/mlwbucket/download' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"mlwfiles/anomalySampleData.csv"}'

Example Response

200 - OK

{
    "id": "656ea4",
    "name": "anomalySampleData_1613992681",
    "createdAt": "Mon Feb 22 11:18:01 2021",
    "type": "S3",
    "cronExpression": "",
    "status": "RUNNING",
    "individualTasks": {
        "656ea4": {
            "pID": "140239630587648",
            "status": "RUNNING",
            "type": "S3",
            "id": "656ea4",
            "message": "Downloading Data from S3",
            "executedAt": "Mon Feb 22 11:18:01 2021"
        }
    },
    "projectID": "0f981b26132d412097ee5e54a257ce9f",
    "sortTime": 1613992681,
    "projectName": "DemoProject",
    "recurrence": "ONE_TIME",
    "startDate": "",
    "startTimeH": "",
    "startTimeM": "",
    "properties": [
        {
            "key": "file_name",
            "label": "File Name",
            "value": "anomalySampleData.csv"
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/downloadFromS3/mlwbucket/download' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"mlwfiles/anomalySampleData.csv"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/projects/{{projectID}}/resources/downloadFromS3/mlwbucket/download' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"mlwfiles/anomalySampleData.csv"}'

Example Response

409 - Conflict

{
    "message": "File already exists.",
    "errorCode": 409,
    "exception": "Duplicate name"
}

Training WorkFlow

Training WorkFlow in MLW.

Info
An active subscription of the MLW microservice is required to perform operations.

POST - Retrain Machine Learning models using WorkFlow

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourcesID}}/workflow

Trains the WorkFlow using the already created AutoML model, pre-processing script and the dataset.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID
taskName (string) required body parameter of a task name to start the re-training
cronExpression (string) required body parameter of a cron expression
recurrence (string) required body parameter of a recurrence (ONE_TIME or REPEAT)
startDate (string) optional startDate body parameter in “%Y-%m-%dT%H:%M:%S.%fZ” format
testSize (float) optional testSize body parameter for cross-validation (default is 0.2)

Example Request

200 - OK

curl --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/656ea5/workflow" \
     --header "Authorization: {{auth}}" \
     --header "Content-Type: application/json" \
     --data-raw '{"recurrence":"ONE_TIME","cronExpression":"","taskName":"workFlowTrain","startDate": "2020-03-08T18:30:00.000Z","testSize":0.33}'

Example Response

200 - OK

{
   "id":"656ea4",
   "name":"workFlowTrain",
   "createdAt":"Mon Sep 28 10:31:59 2020",
   "type":"WORKFLOW",
   "sortTime":1601289119,
   "cronExpression":"",
   "status":"RUNNING",
   "individualTasks":[
      {
         "status":"RUNNING",
         "type":"WORKFLOW",
         "message":"In Progress",
         "id":"656ea5",
         "projectID":"0f981b26132d412097ee5e54a257ce9f",
         "tasksID":"656ea4",
         "listOfModelAccuracy":[  
         ],
         "executedAt":"Mon Sep 28 10:31:59 2020",
         "pID":"140281294558976"
      }
   ],
   "projectID":"0f981b26132d412097ee5e54a257ce9f",
   "projectName":"Demo project",
   "recurrence":"ONE_TIME",
   "startDate":"2020-03-08",
   "startTimeH":"18",
   "startTimeM":"30",
   "timeZone":"UTC",
   "workflowName":"yyy",
   "testSize":"0.33"
   "properties":[
      {
         "key":"targetVar",
         "label":"Target variable",
         "value":"target"
      },
      {
         "key":"problem_type",
         "label":"Problem Type",
         "value":"Classification"
      },
      {
         "key":"dataSize",
         "label":"Data Size",
         "value":[
            "644",
            "3"
         ]
      },
      {
         "key":"model_name",
         "label":"Model Name",
         "value":"admsModel"
      }
   ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/656ea5/workflow" \
     --header "Content-Type: application/json" \
     --data-raw '{"recurrence":"ONE_TIME","cronExpression":"","taskName":"workFlowTrain"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/656ea5/workflow" \
     --header "Authorization: {{auth}}" \
     --header "Content-Type: application/json" \
     --data-raw '{"recurrence":"ONE_TIME","cronExpression":"","taskName":"workFlowTrain"}'

Example Response

409 - Conflict

{
    "message": "Task name already exists. Please provide another name",
    "errorCode": 409,
    "exception": "Duplicate name"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/656ea5/workflow" \
     --header "Authorization: {{auth}}" \
     --header "Content-Type: application/json" \
     --data-raw '{"recurrence":"ONE_TIME","cronExpression":"","taskName":""}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "taskName"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

MLE integration

Operations on models.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - List of deployed models

{{url}}/service/mlw/resources/deploy

Retrieves the list of PMML/ONNX/PIPELINE models deployed to MLE.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
type (string) required query parameter to fetch a model type (ex: PMML/ONNX/PIPELINE)

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/resources/deploy?type=PMML' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "id": "admissionsModel",
            "name": "admissionsModel",
            "type": "PMML"
        },
        {
            "id": "anomalyModelISO",
            "name": "anomalyModelISO",
            "type": "PMML"
        }
    ]
}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/resources/deploy?type=ONNX' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "id": "retrainCasting",
            "name": "retrainCasting",
            "type": "ONNX"
        },
        {
            "id": "sodaBottleModel",
            "name": "sodaBottleModel",
            "type": "ONNX"
        }
    ]
}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/resources/deploy?type=PIPELINE' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "id": "inferencePipeline",
            "name": "inferencePipeline",
            "type": "PIPELINE"
        },
        {
            "id": "castPipelineNew",
            "name": "castPipelineNew",
            "type": "PIPELINE"
        }
    ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/mlw/resources/deploy?type=PMML"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request POST '{{url}}/service/mlw/resources/deploy?type=H5' \
--header 'Authorization: {{auth}}'

Example Response

404 - Not Found

{
    "message": "Invalid Model Type",
    "errorCode": 404,
    "exception": "invalid model"
}

POST - Deploy model to MLE

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/deploy

Deploys the PMML/ONNX/PIPELINE model to MLE.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_CREATE

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}' \

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "deployModel.pmml",
    "description": "",
    "createdAt": "Tue Sep 29 04:52:45 2020",
    "properties": [
        {
            "key": "version",
            "label": "Version",
            "value": "4.4"
        },
        {
            "key": "fileCreated",
            "label": "Time File Created",
            "value": "2020-09-29 04:52:42.843828"
        },
        {
            "key": "desc",
            "label": "Description",
            "value": "Default Description"
        },
        {
            "key": "columns",
            "label": "Column names",
            "value": [
                "gpa",
                "gre",
                "target"
            ]
        },
        {
            "key": "functionName",
            "label": "Function Name",
            "value": "classification"
        },
        {
            "key": "modelType",
            "label": "Model Type",
            "value": "Tree Based Model"
        },
        {
            "key": "modelName",
            "label": "Model Name",
            "value": "deployModel"
        },
        {
            "key": "numberOfTrees",
            "label": "Number of trees",
            "value": 100
        },
        {
            "key": "modelInformation",
            "label": "Model information",
            "value": 10
        }
    ],
    "editedAt": "",
    "type": "PMML",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/deployModel.pmml",
    "size": 699812,
    "mimeType": "application/PMML",
    "extension": ".pmml",
    "category": "Model",
    "deployed": true,
    "mleID": "deployModel"
}

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}' \

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "admsNNN_1601357289.onnx",
    "description": "",
    "createdAt": "Tue Sep 29 05:28:25 2020",
    "properties": [],
    "editedAt": "",
    "type": "ONNX",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/admsNNN_1601357289.onnx",
    "size": 204024,
    "mimeType": "application/ONNX",
    "extension": ".onnx",
    "category": "Model",
    "deployed": true,
    "mleID": "admsNNN"
}

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "PPP.pipeline",
    "description": "",
    "createdAt": "Tue Sep 29 05:33:24 2020",
    "properties": [
        {
            "key": "modelID",
            "label": "ONNX Model",
            "value": "admsNNN_1601357289.onnx"
        },
        {
            "key": "preProcessingID",
            "label": "Pre-Processing Script",
            "value": "preScriptCastDefect.py"
        },
        {
            "key": "postProcessingID",
            "label": "Post-Processing Script",
            "value": "postScriptCastDefect.py"
        }
    ],
    "editedAt": "Tue Sep 29 05:33:24 2020",
    "type": "PIPELINE",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Pipeline/PPP.pipeline",
    "size": 134,
    "mimeType": "application/PIPELINE",
    "extension": ".pipeline",
    "category": "Pipeline",
    "preProcessingID": "0f981b26132d412097ee5e54a257ce9f",
    "modelID": "0f981b26132d412097ee5e54a257ce9f",
    "postProcessingID": "0f981b26132d412097ee5e54a257ce9f",
    "deployed": true,
    "mleID": "PPP"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}'

Example Response

409 - Conflict

{
    "message": "A model with the name 'deployModel' already exists.",
    "errorCode": 409,
    "exception": "invalid/error"
}

Example Request

400 - Error

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}'

Example Response

400 - Error

{
    "message": "Invalid XML format.",
    "errorCode": 400,
    "exception": "invalid/error"
}

Example Request

404 - Not Found

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}'

Example Response

404 - Not Found

{
    "message": "'errors'",
    "errorCode": 404,
    "exception": "Not Found"
}

DELETE - Remove model from MLE

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/deploy

Removes the PMML/ONNX/PIPELINE model from MLE.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}' \

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "deployModel.pmml",
    "description": "",
    "createdAt": "Tue Sep 29 04:52:45 2020",
    "properties": [
        {
            "key": "version",
            "label": "Version",
            "value": "4.4"
        },
        {
            "key": "fileCreated",
            "label": "Time File Created",
            "value": "2020-09-29 04:52:42.843828"
        },
        {
            "key": "desc",
            "label": "Description",
            "value": "Default Description"
        },
        {
            "key": "columns",
            "label": "Column names",
            "value": [
                "gpa",
                "gre",
                "target"
            ]
        },
        {
            "key": "functionName",
            "label": "Function Name",
            "value": "classification"
        },
        {
            "key": "modelType",
            "label": "Model Type",
            "value": "Tree Based Model"
        },
        {
            "key": "modelName",
            "label": "Model Name",
            "value": "deployModel"
        },
        {
            "key": "numberOfTrees",
            "label": "Number of trees",
            "value": 100
        },
        {
            "key": "modelInformation",
            "label": "Model information",
            "value": 10
        }
    ],
    "editedAt": "",
    "type": "PMML",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/deployModel.pmml",
    "size": 699812,
    "mimeType": "application/PMML",
    "extension": ".pmml",
    "category": "Model",
    "deployed": false,
    "mleID": "deployModel"
}

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}' \

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "admsNNN_1601357289.onnx",
    "description": "",
    "createdAt": "Tue Sep 29 05:28:25 2020",
    "properties": [],
    "editedAt": "",
    "type": "ONNX",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/admsNNN_1601357289.onnx",
    "size": 204024,
    "mimeType": "application/ONNX",
    "extension": ".onnx",
    "category": "Model",
    "deployed": false,
    "mleID": "admsNNN"
}

Example Request

200 - OK

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}' \

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "PPP.pipeline",
    "description": "",
    "createdAt": "Tue Sep 29 05:33:24 2020",
    "properties": [
        {
            "key": "modelID",
            "label": "ONNX Model",
            "value": "admsNNN_1601357289.onnx"
        },
        {
            "key": "preProcessingID",
            "label": "Pre-Processing Script",
            "value": "preScriptCastDefect.py"
        },
        {
            "key": "postProcessingID",
            "label": "Post-Processing Script",
            "value": "postScriptCastDefect.py"
        }
    ],
    "editedAt": "Tue Sep 29 05:33:24 2020",
    "type": "PIPELINE",
    "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Pipeline/PPP.pipeline",
    "size": 134,
    "mimeType": "application/PIPELINE",
    "extension": ".pipeline",
    "category": "Pipeline",
    "preProcessingID": "0f981b26132d412097ee5e54a257ce9f",
    "modelID": "0f981b26132d412097ee5e54a257ce8f",
    "postProcessingID": "0f981b26132d412097ee5e54a257ce6f",
    "deployed": false,
    "mleID": "PPP"
}

Example Request

401 - Unauthorized

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}'

Example Response

404 - Not Found

{
    "message": "Model 'deployModel' not found.",
    "errorCode": 404,
    "exception": "invalid/error"
}

Example Request

404 - Not Found

curl --location --request DELETE '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/deploy' \
--header 'Authorization: {{auth}}'

Example Response

404 - Not Found

{
    "message": "'errors'",
    "errorCode": 404,
    "exception": "Not Found"
}

GET - Predict using the deployed models

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/predict/{{modelID}}

Predicts from the list of deployed PMML/ONNX/PIPELINE models in MLE.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID
modelID (string) required path variable of an existing model ID
type (string) required query parameter to score against a model type (for example: PMML/ONNX/PIPELINE)

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/predict/deployModel?type=PMML' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "castingDefect",
    "description": "test project",
    "createdAt": "Tue Sep 29 04:51:25 2020",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "selectedVersion": "",
    "versions": [],
    "resources": {
        "data": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "admissions_test.csv",
                "description": "",
                "createdAt": "Tue Sep 29 06:05:13 2020",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 644
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 2
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "gpa",
                            "gre"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/admissions_test.csv",
                "size": 15897,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            },
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "predicted_admissions_test_1601359589.csv",
                "description": "",
                "createdAt": "Tue Sep 29 06:06:29 2020",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 644
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 3
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "probability_0",
                            "probability_1",
                            "predicted_target"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/predicted_admissions_test_1601359589.csv",
                "size": 7439,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            }
        ],
        "model": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "deployModel.pmml",
                "description": "",
                "createdAt": "Tue Sep 29 04:52:45 2020",
                "properties": [
                    {
                        "key": "version",
                        "label": "Version",
                        "value": "4.4"
                    },
                    {
                        "key": "fileCreated",
                        "label": "Time File Created",
                        "value": "2020-09-29 04:52:42.843828"
                    },
                    {
                        "key": "desc",
                        "label": "Description",
                        "value": "Default Description"
                    },
                    {
                        "key": "columns",
                        "label": "Column names",
                        "value": [
                            "gpa",
                            "gre",
                            "target"
                        ]
                    },
                    {
                        "key": "functionName",
                        "label": "Function Name",
                        "value": "classification"
                    },
                    {
                        "key": "modelType",
                        "label": "Model Type",
                        "value": "Tree Based Model"
                    },
                    {
                        "key": "modelName",
                        "label": "Model Name",
                        "value": "deployModel"
                    },
                    {
                        "key": "numberOfTrees",
                        "label": "Number of trees",
                        "value": 100
                    },
                    {
                        "key": "modelInformation",
                        "label": "Model information",
                        "value": 10
                    }
                ],
                "editedAt": "",
                "type": "PMML",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/deployModel.pmml",
                "size": 699812,
                "mimeType": "application/PMML",
                "extension": ".pmml",
                "category": "Model",
                "deployed": false,
                "mleID": "deployModel"
            }
        ],
        "code": [
        ],
        "pipeline": [
        ],
        "workflow": [],
        "nn-designer": [
        ]
    },
    "resourcesCount": {
        "data": 2,
        "model": 1,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 3
    }
}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/predict/admsNNN?type=ONNX' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "castingDefect",
    "description": "test project",
    "createdAt": "Tue Sep 29 04:51:25 2020",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "selectedVersion": "",
    "versions": [],
    "resources": {
        "data": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "testDefectImage.jpg",
                "description": "",
                "createdAt": "Fri Feb 26 05:06:45 2021",
                "properties": [],
                "editedAt": "",
                "type": "IMAGE",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/testDefectImage.jpg",
                "size": 22311,
                "mimeType": "image/jpeg",
                "extension": ".jpg",
                "category": "Data"
            },
            {
                "id": "0f981b26132d412097ee5e54a257ce8f",
                "name": "predicted_testDefectImage_1614323024.json",
                "description": "",
                "createdAt": "Fri Feb 26 07:03:44 2021",
                "properties": [
                    {
                        "key": "numberOfobjects",
                        "label": "Number of Objects",
                        "value": 3
                    },
                    {
                        "key": "keysInJson",
                        "label": "keys in Dictionary",
                        "value": [
                            "ProbabilityScore",
                            "PredictedClass"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "JSON",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/predicted_testDefectImage_1614323024.json",
                "size": 138,
                "mimeType": "application/json",
                "extension": ".json",
                "category": "Data"
            }
        ],
        "model": [
            {
                "id": "0f981b26132d412097ee5e54a257ce7f",
                "name": "castingDefectModel_1614316284.onnx",
                "description": "",
                "createdAt": "Tue Sep 29 05:28:25 2020",
                "properties": [],
                "editedAt": "",
                "type": "ONNX",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/castingDefectModel_1614316284.onnx",
                "size": 204024,
                "mimeType": "application/ONNX",
                "extension": ".onnx",
                "category": "Model",
                "deployed": false,
                "mleID": "castingDefectModel"
            }
        ],
        "code": [
            {
                "id": "0f981b26132d412097ee5e54a257cabf",
                "name": "castingPreProcessingForNN.py",
                "description": "",
                "createdAt": "Fri Feb 26 05:06:45 2021",
                "properties": [],
                "editedAt": "",
                "type": "PY",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Code/castingPreProcessingForNN.py",
                "size": 247,
                "mimeType": "text/x-python",
                "extension": ".py",
                "category": "Code",
                "deployed": false
            },
            {
                "id": "0f981b26132d412097ee5e54a257ccdf",
                "name": "castingPostProcessingForNN.py",
                "description": "",
                "createdAt": "Fri Feb 26 05:06:45 2021",
                "properties": [],
                "editedAt": "",
                "type": "PY",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Code/castingPostProcessingForNN.py",
                "size": 195,
                "mimeType": "text/x-python",
                "extension": ".py",
                "category": "Code",
                "deployed": false
            }
        ],
        "pipeline": [
            {
                "id": "0f981b26132d412097ee5e54a257cfgf",
                "name": "PPP.pipeline",
                "description": "",
                "createdAt": "Fri Feb 26 05:56:49 2021",
                "properties": [
                    {
                        "key": "modelID",
                        "label": "ONNX Model",
                        "value": "castingDefectModel_1614316284.onnx"
                    },
                    {
                        "key": "preProcessingID",
                        "label": "Pre-Processing Script",
                        "value": "castingPreProcessingForNN.py"
                    },
                    {
                        "key": "postProcessingID",
                        "label": "Post-Processing Script",
                        "value": "castingPostProcessingForNN.py"
                    }
                ],
                "editedAt": "Fri Feb 26 05:56:49 2021",
                "type": "PIPELINE",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Pipeline/PPP.pipeline",
                "size": 134,
                "mimeType": "application/PIPELINE",
                "extension": ".pipeline",
                "category": "Pipeline",
                "preProcessingID": "0f981b26132d412097ee5e54a257ce9f",
                "modelID": "0f981b26132d412097ee5e54a257ce8f",
                "postProcessingID": "0f981b26132d412097ee5e54a257ce7f",
                "deployed": true,
                "mleID": "PPP"
            }
        ],
        "workflow": [],
        "nn-designer": [
        ]
    },
    "resourcesCount": {
        "data": 2,
        "model": 1,
        "code": 0,
        "workflow": 0,
        "pipeline": 1,
        "nn-designer": 0,
        "totalCount": 4
    }
}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/predict/PPP?type=PIPELINE' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "id": "0f981b26132d412097ee5e54a257ce9f",
    "name": "castingDefect",
    "description": "test project",
    "createdAt": "Tue Sep 29 04:51:25 2020",
    "properties": [],
    "isModified": true,
    "isFreeze": false,
    "selectedVersion": "",
    "versions": [],
    "resources": {
        "data": [
            {
                "id": "0f981b26132d412097ee5e54a257ce9f",
                "name": "admissions_test.csv",
                "description": "",
                "createdAt": "Tue Sep 29 06:05:13 2020",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 644
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 2
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "gpa",
                            "gre"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/admissions_test.csv",
                "size": 15897,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            },
            {
                "id": "0f981b26132d412097ee5e54a257ce8f",
                "name": "predicted_admissions_test_1601360114.csv",
                "description": "",
                "createdAt": "Tue Sep 29 06:15:14 2020",
                "properties": [
                    {
                        "key": "numberOfRows",
                        "label": "Number of Rows",
                        "value": 644
                    },
                    {
                        "key": "numberOfColumns",
                        "label": "Number of Columns",
                        "value": 1
                    },
                    {
                        "key": "columnNames",
                        "label": "Column Names",
                        "value": [
                            "0"
                        ]
                    }
                ],
                "editedAt": "",
                "type": "CSV",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Data/predicted_admissions_test_1601360114.csv",
                "size": 12482,
                "mimeType": "text/csv",
                "extension": ".csv",
                "category": "Data"
            }
        ],
        "model": [
            {
                "id": "0f981b26132d412097ee5e54a257ce7f",
                "name": "admsNNN_1601357289.onnx",
                "description": "",
                "createdAt": "Tue Sep 29 05:28:25 2020",
                "properties": [],
                "editedAt": "",
                "type": "ONNX",
                "url": "./MLW/0f981b26132d412097ee5e54a257ce9f/Model/admsNNN_1601357289.onnx",
                "size": 204024,
                "mimeType": "application/ONNX",
                "extension": ".onnx",
                "category": "Model",
                "deployed": false,
                "mleID": "admsNNN"
            }
        ],
        "code": [],
        "pipeline": [],
        "workflow": [],
        "nn-designer": []
    },
    "resourcesCount": {
        "data": 2,
        "model": 2,
        "code": 0,
        "workflow": 0,
        "pipeline": 0,
        "nn-designer": 0,
        "totalCount": 4
    }
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/predict/deployModel?type=PMML'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/predict/admsNNN?type=ONNX' \
--header 'Authorization: {{auth}}'

Example Response

404 - Not Found

{
    "message": "Onnx microservice is unsubscribed. Subscribe to Onnx microservice.",
    "errorCode": 404,
    "exception": "invalid/error"
}

Example Request

404 - Not Found

curl --location --request POST '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/predict/PPP?type=H5' \
--header 'Authorization: {{auth}}'

Example Response

404 - Not Found

{
    "message": "Invalid Model Type/File Type.",
    "errorCode": 404,
    "exception": "invalid model"
}

Neural network

Neural network training.

Info
An active subscription of the MLW microservice is required to perform operations.

POST - Start the training process of the neural network

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/trainNN

Train a neural network model using architecture file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID
batchSize (integer) required batchSize body parameter to train model
epoch (integer) required epoch body parameter to train model
stepPerEpoch (integer) required stepPerEpoch body parameter to train model
learningRate (float) required learningRate body parameter to train model
loss (string) required loss function body parameter to train model
metrics (list) required metrics body parameter to train model
optimizer (string) required optimizer body parameter to train model
testSize (float) required testSize body parameter to train model
recurrence (string) required ONE_TIME/REPEAT
cronExpression (string) mandatory Cron expression body parameter if recurrence is “REPEAT”
modelName (string) required modelName body parameter
dataID (string) required resource ID of data (body parameter)
codeID (string) optional resource ID of pre-processing script (body parameter)
problemType (string) required classification/regression
shuffleData (Boolean) required shuffleData body parameter
startDate (string) optional startDate body parameter in “%Y-%m-%dT%H:%M:%S.%fZ” format

Example Request

200 - OK

curl --location --request POST '{{url}}/projects/{{projectID}}/resources/{{resourceID}}/trainNN' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"batchSize":15,"epoch":100,"stepPerEpoch":10,"learningRate":0.001,"loss":"categorical_crossentropy","metrics":["accuracy","f1"],"optimizer":"adam","testSize":0.3,"scriptOutput":"NA","recurrence":"ONE_TIME","cronExpression":"","modelName":"modelName","dataID":"72c0673497344164a80e298f679b8139","shuffleData":true,"codeID":"72c0673497344164a80e298f679b8138","problemType":"classification","startDate": "2020-03-08T18:30:00.000Z"}'

Example Response

200 - OK

{
   "id":"1601358322415",
   "name":"modelName",
   "createdAt":"Tue Sep 29 05:45:22 2020",
   "sortTime":1601358322,
   "type":"NN",
   "individualTasks":[
      {
         "status":"INITIALISING",
         "type":"NN",
         "projectID":"0f981b26132d412097ee5e54a257ce9f",
         "log":{

         },
         "properties":[

         ],
         "message":"Initialising",
         "history":[

         ],
         "tasksID":"656ea4",
         "taskName":"modelName",
         "id":"1601358322191",
         "executedAt":"Tue Sep 29 05:45:22 2020",
         "pID":"1394"
      }
   ],
   "projectID":"0f981b26132d412097ee5e54a257ce9f",
   "projectName":"blah project",
   "startDate":"2020-03-08",
   "startTimeH":"18",
   "startTimeM":"30",
   "timeZone":"UTC",
   "properties":[
      {
         "key":"problemType",
         "label":"Problem Type",
         "value":"classification"
      },
      {
         "key":"optimizer",
         "label":"Optimizer",
         "value":"adam"
      },
      {
         "key":"learningRate",
         "label":"Learning Rate",
         "value":0.001
      },
      {
         "key":"loss",
         "label":"Loss",
         "value":"categorical_crossentropy"
      },
      {
         "key":"metrics",
         "label":"Metrics",
         "value":[
            "accuracy",
            "f1"
         ]
      },
      {
         "key":"epoch",
         "label":"Epoch",
         "value":100
      },
      {
         "key":"testSize",
         "label":"Test Size",
         "value":0.3
      },
      {
         "key":"batchSize",
         "label":"Batch Size",
         "value":15
      }
   ],
   "cronExpression":"",
   "status":"NOT SCHEDULED",
   "recurrence":"ONE_TIME"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/projects/{{projectID}}/resources/{{resourceID}}/trainNN' \
--header 'Content-Type: text/plain' \
--data-raw '{"batchSize":15,"epoch":100,"stepPerEpoch":10,"learningRate":0.001,"loss":"categorical_crossentropy","metrics":["accuracy","f1"],"optimizer":"adam","testSize":0.3,"scriptOutput":"NA","recurrence":"ONE_TIME","cronExpression":"","modelName":"someName","dataID":"72c0673497344164a80e298f679b8138","shuffleData":true,"codeID":"72c0673497344164a80e298f679b8139","problemType":"classification"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

400 Bad Request

curl --location --request POST '{{url}}/projects/{{projectID}}/resources/{{resourceID}}/trainNN' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"batchSize":15,"epoch":100,"stepPerEpoch":10,"learningRate":0.001,"loss":"categorical_crossentropy","metrics":["accuracy","f1"],"optimizer":"Adam","testSize":0.3,"scriptOutput":"NA","recurrence":"ONE_TIME","cronExpression":"","modelName":"","shuffleData":true,"dataID":"72c0673497344164a80e298f679b8139"}'

Example Response

400 - Conflict

{
    "error": "general/Internal Error",
    "message": "Variable issue",
    "info": [
        {
            "loc": [
                "modelName"
            ],
            "msg": "Invalid characters in attribute name",
            "type": "value_error"
        }
    ]
}

Script execution

Operations on MLW projects.

Info
An active subscription of the MLW microservice is required to perform operations.

POST - Execute a script

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/execute

Execute a python script.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID
recurrence (string) required ONE_TIME/REPEAT
cronExpression (string) mandatory Cron expression body parameter if recurrence is “REPEAT”
taskName (string) required taskName body parameter
startDate (string) optional startDate body parameter in “%Y-%m-%dT%H:%M:%S.%fZ” format

Example Request

200 - OK

curl --location --request POST '{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/execute' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"recurrence":"ONE_TIME","cronExpression":"","taskName":"script1","startDate": "2020-03-08T18:30:00.000Z"}'

Example Response

200 - OK

{
   "id":"656ea4",
   "name":"script1",
   "createdAt":"Tue Sep 29 06:27:16 2020",
   "sortTime":1601360836,
   "type":"CODE",
   "individualTasks":[
      {
         "type":"CODE",
         "projectID":"0f981b26132d412097ee5e54a257ce9f",
         "tasksID":"656ea4",
         "taskName":"script1",
         "id":"656ea5",
         "executedAt":"Tue Sep 29 06:27:16 2020",
         "pID":"140281294558976",
         "status":"RUNNING"
      }
   ],
   "projectID":"0f981b26132d412097ee5e54a257ce9f",
   "projectName":"blah project",
   "startDate":"2020-03-08",
   "startTimeH":"18",
   "startTimeM":"30",
   "timeZone":"UTC",
   "properties":[

   ],
   "cronExpression":"",
   "status":"EXECUTED",
   "recurrence":"ONE_TIME"
}

Example Request

401 - Unauthorized

curl --location --request POST '{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/execute' \
--header 'Content-Type: application/json' \
--data-raw '{"recurrence":"ONE_TIME","cronExpression":"","taskName":"script1"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

400 Bad Request

curl --location --request POST '{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/execute' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: application/json' \
--data-raw '{"recurrence":"ONE_TIME","cronExpression":""}'

Example Response

400 Bad Request

{
   "message":"Missing parameter taskName",
   "errorCode":400,
   "exception":"Missing parameters"
}

Jupyter integration

Operations on Jupyter Notebook.

Info
An active subscription of the MLW microservice is required to perform operations.

GET - Preview the Notebook code along with the session creation

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/jnb-content

Gets the content of the Jupyter Notebook file and also creates a Jupyter session.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": {
        "name": "untitled.ipynb",
        "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
        "last_modified": "2020-09-30T07:31:59.062747Z",
        "created": "2020-09-30T07:31:59.062747Z",
        "content": {
            "cells": [],
            "metadata": {},
            "nbformat": 4,
            "nbformat_minor": 4
        },
        "format": "json",
        "mimetype": null,
        "size": 78,
        "writable": true,
        "type": "notebook"
    },
    "session": {
        "id": "e2ba72b2-2daf-4aa6-851d-1b3e491cc2f3",
        "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
        "name": "untitled",
        "type": "notebook",
        "kernel": {
            "id": "7fd616bf-1044-4954-a0cd-591c973ee950",
            "name": "python3",
            "last_activity": "2020-09-30T07:33:20.920222Z",
            "execution_state": "starting",
            "connections": 0
        },
        "notebook": {
            "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
            "name": "untitled"
        }
    }
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

PUT - Update the Jupyter Notebook contents

{{url}}/service/mlw/projects/{{projectID}}/resources/{{resourceID}}/jnb-content

Updates the contents of the Jupyter Notebook file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}
PARAMS
projectID (string) required path variable of an existing project ID
resourceID (string) required path variable of an existing resource ID
content (string) required body parameter for updated contents of Jupyter Notebook
format (string) required body parameter for format (ex. ‘json’)
type (string) required body parameter for type (ex. ‘notebook’)
export (Boolean) required body parameter to export notebook to Python file.

Example Request

200 - OK

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content' \
--header 'Authorization: {{auth}} \
--header 'Content-Type: text/plain' \
--data-raw '{"content": {"cells": [{"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["asdasfas"]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.9"}}, "nbformat": 4, "nbformat_minor": 4},
"format": "json",
"type": "notebook"}'

Example Response

200 - OK

{
    "name": "untitled.ipynb",
    "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
    "last_modified": "2020-09-30T07:40:02.608464Z",
    "created": "2020-09-30T07:40:02.608464Z",
    "content": null,
    "format": null,
    "mimetype": null,
    "size": 571,
    "writable": true,
    "type": "notebook"
}

Example Request

401 - Unauthorized

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content' \
--header 'Content-Type: text/plain' \
--data-raw '{"content": {"cells": [{"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["asdasfas"]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.9"}}, "nbformat": 4, "nbformat_minor": 4},
"format": "json",
"type": "notebook"}'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

400 - Error

curl --location --request PUT '{{url}}/service/mlw/projects/0f981b26132d412097ee5e54a257ce9f/resources/72c0673497344164a80e298f679b8139/jnb-content' \
--header 'Authorization: {{auth}}' \
--header 'Content-Type: text/plain' \
--data-raw '{"content": {"cells": [{"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["asdasfas"]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.9"}}, "nbformat": 4, "nbformat_minor": 4},
"format": "json",
"type": "jnb"}'

Example Response

400 - Error

{
    "message": "Unhandled contents type: jnb",
    "reason": null
}

GET - List of created Jupyter sessions

{{url}}/service/mlw/jnb-sessions

Gets the list of created Jupyter sessions.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization {{auth}}

Example Request

200 - OK

curl --location --request GET '{{url}}/service/mlw/jnb-sessions' \
--header 'Authorization: {{auth}}'

Example Response

200 - OK

{
    "data": [
        {
            "id": "e1b8e814-36c2-4e5a-ba2a-e3524fe2d03c",
            "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
            "name": "untitled",
            "type": "notebook",
            "kernel": {
                "id": "63b58129-f89e-4325-a069-ef010153ff46",
                "name": "python3",
                "last_activity": "2020-09-28T06:00:14.946977Z",
                "execution_state": "idle",
                "connections": 0
            },
            "notebook": {
                "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
                "name": "untitled"
            },
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "projectName": "blah project",
            "fileName": "untitled.ipynb"
        },
        {
            "id": "e2ba72b2-2daf-4aa6-851d-1b3e491cc2f3",
            "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
            "name": "untitled",
            "type": "notebook",
            "kernel": {
                "id": "7fd616bf-1044-4954-a0cd-591c973ee950",
                "name": "python3",
                "last_activity": "2020-09-30T07:33:20.920222Z",
                "execution_state": "starting",
                "connections": 0
            },
            "notebook": {
                "path": "0f981b26132d412097ee5e54a257ce9f/Code/untitled.ipynb",
                "name": "untitled"
            },
            "projectID": "0f981b26132d412097ee5e54a257ce9f",
            "projectName": "vinsy",
            "fileName": "untitled.ipynb"
        }
    ]
}

Example Request

401 - Unauthorized

curl --location --request GET '{{url}}/service/mlw/jnb-sessions'

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Using Postman

Graphical REST clients such as Postman are a convenient way to explore REST interfaces and the Cumulocity IoT database content.

If you are already using the Cumulocity IoT API collection in Postman and the environment to access the collection for your tenant is set up, then you can directly import the MLW microservice collection (see below).

If you are doing a fresh set up of Postman for using the Machine Learning Workbench (MLW) microservice collection, first follow the steps described in Using the REST interface > Overview > Using Postman in the Microservice SDK guide.

Importing the Machine Learning Workbench (MLW) microservice collection into Postman

Import the APIs as a JSON file.

Alternatively click: Run in Postman After importing, you will see a new collection “MLW Microservice API” in the Collections tab in Postman.