REST APIs

NeoPulse™ Query Runtime exposes the following REST APIs on port 46921 of the machine to manage the training and querying of models.

delete

Delete can be used to remove an entire project, clear all the queries, or remove a specific queryID. Providing a project_name will completely remove the PIM from the instance. Deleting a query removes the query from the database and deletes the .csv file containing the results from the instance.

Method Type Path
POST application/json /api/ai/delete

Request Body Parameters:

Parameter Data Type Description
*project_name String Name of the project that is to be deleted
*query_id String Query ID that is to be deleted
Note: “all” - will delete all the queries

Note: At-least one of the parameters should be present

Response Body Parameters:

Parameter Data Type Description
success String Status of deleting the project or query
*error String Error message
*code Number Error code

cURL example (removing an entire project):

$ curl -s -X POST http://localhost:46921/api/ai/delete -H 'Content-Type: application/json' -d '{"project_name": "test_import"}'

Example response:

{
    "success":true
}

cURL example (Clearing a query_id):

$ curl -s -X POST http://localhost:46921/api/ai/delete -H 'Content-Type: application/json' -d '{"query_id": "ryfHIQ3XM"}'

Example response:

{
    "success":true
}

cURL example (Clearing all queries):

$ curl -s -X POST http://localhost:46921/api/ai/delete -H 'Content-Type: application/json' -d '{"query_id": "all"}'

Example response:

{
    "success": true
}

import

Import a model that was trained and exported elsewhere into NeoPulse™ AI Studio.

Method Type Path
POST application/json /api/ai/import

Request Body Parameters:

Parameter Data Type Description
project_name String Name for this imported project
file_path String Absolute path to the PIM file that is being imported

Response Body Parameters:

Parameter Data Type Description
success Boolean Status of import job
*error String Error message
*code Number Error code

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/import -H 'Content-Type: application/json' -d '{"project_name": "test_import", "file_path": "/path/to/model.pim"}'

Example response:

{
    "success": true
}

list

List is used to query the AI Collections Database about submitted training jobs. When providing a model_id the document for that model from the "Models" collection is returned. If a project_name is provided, an array of documents for all models associated with that project is returned. When the request doesn’t contain either a model_id or project_name an array of all the projects in the "Train" collection is returned.

Method Type Path
POST application/json /api/ai/info

Request Body Parameters:

Parameter Data Type Description
*model_id String ID of a model
*project_name String Name of the project

Response Body Parameters:

Parameter Data Type Description
*<name of the project> Object database document of the project
*<model ID> Object Database document of the model
*error String Error message
*code String Error code

cURL example (List all projects):

$ curl -s -X POST http://localhost:46921/api/ai/list -H 'Content-Type: application/json' -d ''

Assuming there are 3 projects.

[
    {
        "_id": "test_error",
        "error": "Unable to compile",
        "model_list": [],
        "name": "test_error10",
        "num_models": 0,
        "num_trained": 0,
        "status": "ERROR",
        "uuid": "BJwe6pPVLN",
        "version": "3.0.0"
    },
    {
        "_id": "test",
        "model_list": [
            "test_1"
        ],
        "name": "test",
        "num_models": 1,
        "num_trained": 1,
        "status": "TRAINING_COMPLETED",
        "uuid": "SyVe6pDEU4",
        "version": "3.0.0"
    },
    {
        "_id": "test_import",
        "model_list": [
            "test_import_0"
        ],
        "name": "test_import",
        "num_models": 1,
        "num_trained": 1,
        "status": "IMPORTED_PROJECT",
        "uuid": "Skygga6v4UV",
        "version": "3.0.0"
    }
]

cURL example (List project_name):

$ curl -s -X POST http://localhost:46921/api/ai/list -H 'Content-Type: application/json' -d '{"project_name": "test"}'

Assuming the test project has 1 model.

{
    "test": [
        {
            "_id": "test_1",
            "acc": [
                0.4500000023841858,
                0.5599999964237213
            ],
            "auto": [
                {
                    "compile_9__0": "'categorical_crossentropy'"
                },
                {
                    "inp_size_e": 21862
                },
                {
                    "compile_8__0": "'adadelta'"
                },
                {
                    "2_0": [
                        {
                            "filter_length": 5
                        },
                        {
                            "pool_length": 7
                        },
                        {
                            "nb_filters_cn": 112
                        },
                        {
                            "bi_lstm_size": 105
                        },
                        {
                            "lstm_size": 86
                        }
                    ]
                },
                {
                    "embed_dimension": 54
                }
            ],
            "loss": [
                0.6946831297874451,
                0.6927492642402648
            ],
            "metric_list": [
                "val_loss",
                "val_acc",
                "loss",
                "acc"
            ],
            "num_iterations": 2,
            "project_name": "test",
            "status": "TRAINING_COMPLETED",
            "time_updated": "2019-02-27 20:06:15",
            "val_acc": [
                0.4848484857515855,
                0.5353535455886764
            ],
            "val_loss": [
                0.693558607438598,
                0.692483000683062
            ],
            "version": "3.0.0"
        }
    ]
}

cURL example (List model_id):

$ curl -s -X POST http://localhost:46921/api/ai/list -H 'Content-Type: application/json' -d '{"model_id": "test_1"}'

Example response:

{
    "test_1": {
        "_id": "test_1",
        "acc": [
            0.4500000023841858,
            0.5599999964237213
        ],
        "auto": [
            {
                "compile_9__0": "'categorical_crossentropy'"
            },
            {
                "inp_size_e": 21862
            },
            {
                "compile_8__0": "'adadelta'"
            },
            {
                "2_0": [
                    {
                        "filter_length": 5
                    },
                    {
                        "pool_length": 7
                    },
                    {
                        "nb_filters_cn": 112
                    },
                    {
                        "bi_lstm_size": 105
                    },
                    {
                        "lstm_size": 86
                    }
                ]
            },
            {
                "embed_dimension": 54
            }
        ],
        "loss": [
            0.6946831297874451,
            0.6927492642402648
        ],
        "metric_list": [
            "val_loss",
            "val_acc",
            "loss",
            "acc"
        ],
        "num_iterations": 2,
        "project_name": "test",
        "status": "TRAINING_COMPLETED",
        "time_updated": "2019-02-27 20:06:15",
        "val_acc": [
            0.4848484857515855,
            0.5353535455886764
        ],
        "val_loss": [
            0.693558607438598,
            0.692483000683062
        ],
        "version": "3.0.0"
    }
}

query

Used to submit a query job for a model that has completed training.

Method Type Path
POST application/json /api/ai/query

Request Body Parameters:

Parameter Data Type Description
model_id String model_id for a specific model in a trained project
model_iter String model_iter for a specific iteration number associated with the model_id
csv String absolute path for a local csv file containing input to query

Response Body Parameters:

Parameter Data Type Description
success Boolean Query job submission status
query_id String uuid generated for this query job
*error String Error message
*code Number Error code if error

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/query -H 'Content-Type: application/json' -d '{"model_id": "test_1","model_iter": "1", "csv": "/path/to/query.csv"}'

Example response:

{
    "success":true,
    "query_id":"ryfHIQ3XM"
}

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/query -H 'Content-Type: application/json' -d '{"model_id": "test_error","model_iter": "1", "csv": "/query.csv"}' | python -m json.tool

Example response:

{
    "code": 261,
    "error": "Model or iteration of the model that is being queried is invalid."
}

results

Like LIST API, except results is for managing query submissions rather than those for training. If provided no keys are provided to the API, an array of all the documents in the query collection is returned. If provided a specific query_id, it will return just the document associated with that id. Additionally, the result CSV can be retrieved with this API if both a query_id and the show keys are provided in the request (assuming the status of the requested document is QUERY_COMPLETED).

Method Type Path
POST application/json /api/ai/results

Request Body Parameters:

Parameter Data Type Description
*query_id String query_id in the query collection to return document for
*show Boolean return the results of query

Response Body Parameters:

Parameter Data Type Description
*results String Document of the results file
* * Database document of the query
*error String Error message
*code Number Error code if in case of error

cURL example results for a query_id:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "SkH1L9J4V"}' | python -m json.tool

Example Response:

{
    "_id": "SkH1L9J4V",
    "input_file_path": "/absolute/path/to/query1.csv",
    "model_id": "test_1",
    "model_iter": "001",
    "status": "QUERY_COMPLETED",
    "time_updated": "2019-01-30 21:23:41",
    "version": "3.0.0"
}

When query results have error:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "H15oS91EN"}' | python -m json.tool

Example Response:

{
    "_id": "H15oS91EN",
    "error": "Error loading query CSV file.Make sure the number of columns are equal to the number of inputs and that they are in the same order used for training.",
    "input_file_path": "/absolute/path/to/query.csv",
    "model_id": "test_1",
    "model_iter": "001",
    "status": "ERROR",
    "time_updated": "2019-01-30 21:22:42",
    "version": "3.0.0"
}

cURL example retrieving results for a query_id using show:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "SkH1L9J4V", "show": true}' | python -m json.tool

Example Response:

{
    "_id": "SkH1L9J4V",
    "results": "0.4961142,0.50388587\n0.4962748,0.5037252\n0.49729934,0.50270057\n0.49726972,0.5027303\n0.49468577,0.5053143\n0.49725237,0.5027476\n0.49193063,0.50806934\n0.5004346,0.49956545\n0.5116662,0.4883339\n0.49684286,0.5031571\n0.50167054,0.49832943\n0.5005348,0.49946523\n0.4910176,0.5089825\n0.5018504,0.4981495\n0.49455598,0.505444\n0.50737834,0.49262166\n0.49599665,0.5040034\n0.4986556,0.5013443\n0.49964067,0.5003593\n0.4968565,0.50314355\n0.50329053,0.49670947\n0.50993,0.49006996\n0.5066415,0.49335846\n0.49716932,0.5028307\n0.4974647,0.5025354\n0.50237805,0.49762192\n0.50951856,0.4904814\n0.51113683,0.48886314\n0.4960988,0.50390124\n0.49836245,0.5016375\n0.49418578,0.5058142\n0.5093612,0.49063873\n0.49954656,0.5004534\n0.508187,0.491813\n0.49370107,0.5062989\n0.50705296,0.49294704\n0.50126415,0.49873585\n0.49884957,0.5011504\n0.5064257,0.49357435\n"
}

cURL response for a query when show is passed that failed:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "ry_ZSskN4", "show": true}' | python -m json.tool

Example Response:

{
    "code": 142,
    "error": "Unable to show the results for queries that are either not complete or contains error."
}

status

This API can be used to check the NeoPulse® application status. If any of the components of the application which is needed for the correct functioning the application is down, it reports it with the info message.

Method Type Path
POST application/json /api/ai/status

Request Body Parameters:

Parameter Data Type Description

Response Body Parameters:

Parameter Data Type Description
status Boolean Status of NeoPulse® application
*info String Any information that is to be communicated to the user
*error String Error message
*code Number Error code

cURL example (successful status):

$ curl -s -X POST http://localhost:46921/api/ai/status -H 'Content-Type:application/json' -d ''

Example response:

{
    "status": true,
    "info": ""
}

cURL example (failure status):

$ curl -s -X POST http://localhost:46921/api/ai/status -H 'Content-Type:application/json' -d ''

Example response:

{
    "status": false,
    "info": "Some entities of NeoPulse® application is running. Please shutdown the NeoPulse® application with force flag and start it again."
}

cURL example (error):

$ curl -s -X POST http://localhost:46921/api/ai/status -H 'Content-Type:application/json' -d ''

Example response:

{
    "code": 380,
    "error": "Unknown error checking the status of NeoPulse® entities."
}

visualize

This API can be used to look at the architecture of the training that was performed. This either starts architecture visualization for a given project or shutdown any existing visualization. Providing the “project_name” will start the architecture visualization for the project and providing “shutdown” parameter with the valid Boolean value [true, false] will shut down any existing visualization session.

Method Type Path
POST application/json /api/ai/visualize

Request Body Parameters:

Parameter Data Type Description
*project_name String Name of the project that is to be deleted
*shutdown Boolean true – if any visualization session needs to be shut down
false – Otherwise

Note: At-least one of the parameters should be present. Also, having both with “shutdown” parameter set will result in error as it is an ambiguous request.

Response Body Parameters:

Parameter Data Type Description
success String Status of visualizing the project
*info String Success message that gives information on the task that was completed
*error String Error message
*code Number Error code

cURL example (visualizing a project):

$ curl -s -X POST http://localhost:46921/api/ai/visualize -H 'Content-Type: application/json' -d '{"project_name": "test"}'

Example response:

{
    "success": true,
    "info": "Successfully started to visualize on the port 6006 for the project: test"
}

cURL example (stopping visualization session):

$ curl -s -X POST http://localhost:46921/api/ai/visualize -H 'Content-Type: application/json' -d '{"shutdown": true}'

Example response:

{
    "success": true,
    "info": "Successfully shutdown running visualization."
}