REST API Reference

NeoPulse® Query Runtime exposes the following REST APIs on port 8081 of the machine to manage the querying of models in production.

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 you are importing

Response Body Parameters:

Parameter Data Type Description
success boolean successful import
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/import -H 'Content-Type: application/json' -d '{"project_name": "test_import", "file_path": "/DM-Dash/test_npqr/npqr_test_model.pim"}'

Example response:

{
  "success": true
}

info

Returns the database collection document associated with project_name or query_id respectively. The database collections are described here.

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

Request Body Parameters:

Parameter Data Type Description
*project_name string name of a project submitted for training
*query_id string id associated with a submitted query job

Response Body Parameters:

Parameter Data Type Description
_id string _id key value used as the index in the database
* * the entire database document is returned; its structure varies by collection
*error string error message
*info string other information string

cURL example:

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

Example response:

{
    "_id":"test_import",
    "path":"/DM-Dash/projects/test_import",
    "uuid":"NA","completed":1,
    "models":["test_import-0"],
    "num_models":1,
    "imported":true,
    "weights":"/DM-Dash/projects/test_import/test_import-0/results/weights-000.model"
}

list

List is used to query the AI Collections Database about imported models. 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 database collection is returned.

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

Request Body Parameters:

Parameter Data Type Description
*project_name string name of a project to list all models for
*model_id string a specific model to list information for

Response Body Parameters:

Parameter Data Type Description
* * database document, or an array of documents
*error string error message
*info string other information string

cURL example (List all projects):

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

Example response (one project in list):

[
    {
        "_id":"test_import",
        "path":"/DM-Dash/projects/test_import",
        "uuid":"NA","completed":1,
        "models":["test_import-0"],
        "num_models":1,
        "imported":true,
        "weights":"/DM-Dash/projects/test_import/test_import-0/results/weights-000.model"
    }
]

cURL example (List project_name):

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

Example response:

[
    {
        "_id":"test_import",
        "path":"/DM-Dash/projects/test_import",
        "uuid":"NA","completed":1,
        "models":["test_import-0"],
        "num_models":1,
        "imported":true,
        "weights":"/DM-Dash/projects/test_import/test_import-0/results/weights-000.model"
    }
]

cURL example (List model_id):

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

Example response:

{
    "_id":"test_import-0",
    "status":"IMPORTED_MODEL",
    "auto":{"error":"Could not load autoparams IMPORTED_MODEL"},
    "path":"/DM-Dash/projects/test_import/test_import-0",
    "headers":["val_loss","val_acc","loss","acc"],
    "val_loss":[2.1223669052124023],
    "val_acc":[0.5],
    "loss":[0.1658657883397407],
    "acc":[0.955555555721124]
}

top

Sort the models in a given project by the metric provided, and return the top model iterations.

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

Request Body Parameters:

Parameter Data Type Description
project_name string name of the project to list
metric string sorting metric
top_num number number of top models to return

Response Body Parameters:

Parameter Data Type Description
success boolean successfully returned top models
top array array of strings in a human readable format for top models
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/top -H 'Content-Type: application/json' -d '{"project_name": "test_import","metric": "acc", "top_num": 1}'

Example response:

{
    "model":"test_import-0",
    "iter":"weights-000.model",
    "top":["model: test_import-0 iter: weights-000.model"]
}

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 weights file 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 was the train job submitted successfully
models array list of uuid’s generated for each model in the project
query_id string uuid generated for this query job
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/query -H 'Content-Type: application/json' -d '{"model_id": "test_import-0","model_iter": "weights-000.model", "csv": "/DM-Dash/test_studio/query.csv"}'

Example response:

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

results

Similar to list, 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 string return the .csv for this query_id in the response

Response Body Parameters:

Parameter Data Type Description
*success string if reading the results was successful
*results string database document, or an array of documents
* * document or array of documents in the query collection
*error string error message
*info string other information string

cURL example results for a query_id:

$ curl -s -X POST http://localhost:8081/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "ry1cDMn7f"}'

Example response:

{
    "_id":"ry1cDMn7f",
    "status":"QUERY_COMPLETED",
    "time_updated":"2018-01-04 21:07:19.056662",
    "path":"/DM-Dash/query_results",
    "csv_path":"/DM-Dash/test_studio/query.csv",
    "model_id":"test_import-0",
    "model_iter":"weights-000.model",
    "result_path":"/DM-Dash/query_results/ry1cDMn7f.csv"
}

cURL example retrieving results for a query_id using show:

$ curl -s -X POST http://localhost:8081/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "ry1cDMn7f", "show": ""}'

Example response:

{
    "success":true,
    "results":"1.336649656295776367e-01,1.430640071630477905e-01,4.499375820159912109e-02,4.731103032827377319e-02,7.890328019857406616e-02,1.207960695028305054e-01,4.191153496503829956e-02,1.101234257221221924e-01,7.754502445459365845e-02,2.016869336366653442e-01\n1.477717608213424683e-01,1.205739751458168030e-01,5.051809549331665039e-02,5.346546694636344910e-02,6.388561427593231201e-02,1.429085731506347656e-01,5.700185149908065796e-02,9.599520266056060791e-02,9.621882438659667969e-02,1.716606020927429199e-01\n1.242994144558906555e-01,1.245336458086967468e-01,3.972632065415382385e-02,4.716908559203147888e-02,8.985404670238494873e-02,1.269043236970901489e-01,4.799102619290351868e-02,1.184404268860816956e-01,1.026519313454627991e-01,1.784297525882720947e-01\n",
    "_id":"ry1cDMn7f"
}

Example response for a query that failed:

{
    "_id": "BkTd4OFXM",
    "status": "ERROR",
    "time_updated":
    "2018-01-02 21:07:00.813117",
    "path": "/DM-Dash/query_results",
    "csv_path": "/DM-Dash/test_npqr/quer.csv",
    "model_id":"Sk2eUm2mz-1",
    "model_iter":"weights-004.model",
    "error": "CSV Path DNE csv_path=/DM-Dash/test_npqr/quer.csv"
}

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 project_name to delete
*query_id string query_id to delete or 'all' to delete all queries

Response Body Parameters:

Parameter Data Type Description
success string if deleting the project or query was successful
*error string error message
*info string other information string

cURL example (removing an entire project):

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

Example response:

{
    "success":true,
    "info":"project test_import deleted"
}

cURL example (Clearing a query_id):

$ curl -s -X POST http://localhost:8081/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:8081/api/ai/delete -H 'Content-Type: application/json' -d '{"query_id": "all"}'

Example response:

{
    "success": true
}