Main Content

Using the Modelscape API

Modelscape™ provides workflow tools for model lifecycle support including governance, automation, documentation, and operation in a unified, customizable system.

The Modelscape application programming interface (API) provides a set of HTTP endpoints to work with lifecycles, models, model versions, model version reviews, references, builds, and deployments. Application developers can use the Modelscape API to interact with Modelscape using a web-based language such as JavaScript®, or build client applications using HTTP-supported programming languages such as Java®, Python®, and C++.

The Modelscape API uses the HTTP request-response model for communicating with Modelscape. This model includes request methods, response codes, message headers, and message bodies. The Modelscape API has these characteristics:

  • The HTTP method POST forms the primary mode of communication between the client and the server.

  • Unique uniform resource identifiers (URIs) identify the resources that the server creates.

  • Message headers convey metadata such as the Content-Type header of a request. The Modelscape API uses application/json as the HTTP Content-Type header.

  • The message body of the request contains information to send to the server.

To view the complete Modelscape API, see Modelscape API Reference (PDF).

Example Workflow Instructions

This example shows how to take a financial model from proposal to deployment by using the Modelscape API. You can use the API to create, get, and update Modelscape resources such as lifecycles, models, model versions, reviews, and deployments.

To get started, you need access to Modelscape. To host Modelscape for your organization, contact MathWorks Consulting Services.

Authenticate Credentials

Use the Modelscape API to authenticate and authorize user actions. Submit valid Modelscape credentials by using a PasswordLogin request.

URI: /service/core/authnz

{
    "mwtype": "authnz/PasswordLogin",
    "subjectId": "Service_Agent",
    "password": "My_Token",
}

You receive a response. This response sets a cookie in your HTTP client so the software can authenticate subsequent requests. If your HTTP client does not support cookies, set the authToken from the response in the mwauthtoken header of subsequent requests.

{
    "mwtype": "authnz/SubjectAuthResponse",
    "subject": {
        "subjectId": "Service_Agent",
        "displayName": "Service_Agent",
        "groups": [
            "service"
        ],
        "extra": {},
        "idpId": "local"
    },
    "authToken": "_5YtU0sc6lvaySLkw2eaT1g4mRQkEs5",
    "issuedAt": "2023-03-31T15:56:18.025918282Z",
    "expiration": "2023-04-01T03:56:18.025918282Z",
    "authenticated": true
}

Create Lifecycle

To create a lifecycle, use the Lifecycle Designer app.

To look up information about an existing lifecycle, use a GetAllLifeCycles request.

URI: /modelscape/lifecycle/api/1.0

{
    "mwtype": "lifecycle/GetAllLifeCycles"
}

You receive a response. This message contains GUIDs that uniquely identify all available lifecycles.

For clarity, this example workflow uses GUID strings such as example-lifecycle-guid-001. In practice, Modelscape GUIDs conform to the Version 4 UUID standard (Internet Engineering Task Force). 

{
    "mwtype": "lifecycle/LifeCyclesResponse",
    "lifecycles": [
        {
            "guid": "example-lifecycle-guid-001",
        "name": "New Lifecycle 1",
        "diagram": "{example_diagram}",
        "metaData": {
            "createdOn": "2023-04-03T14:08:26Z",
            "modifiedOn": "2023-04-03T14:08:26Z",
            "createdBy": "Service_Agent",
            "modifiedBy": "Service_Agent",
            "custom": {}
        },
        "states": [
            {
                "name": "Proposal",
                "guid": "proposal-001"
            },
            {
                "name": "Development"
                "guid": "development-001"
            }
        ],
        "transitions": [
            {
                "source": {
                    "guid": "proposal-001"
                },
                "destination": {
                    "guid": "development-001"
                }
            }
        ]
         }
    ]
}

To retrieve the information for a particular lifecycle, use the lifecycle GUID in a GetLifeCycleByGUID request.

URI: /modelscape/lifecycle/api/1.0

{
    "mwtype": "lifecycle/GetLifeCycleByGUID",
    "guid": "example-lifecycle-guid-001",
}

You receive a message containing information about this lifecycle. The states property contains GUIDs for different states. You use these GUIDs to save the state of a model version as it progresses through a lifecycle. 

{
    "mwtype": "lifecycle/LifeCycleResponse",
    "lifecycle": {
        "guid": "example-lifecycle-guid-001",
        "name": "New Lifecycle 1",
        "diagram": "{example_diagram}",
        "metaData": {
            "createdOn": "2023-04-03T14:08:26Z",
            "modifiedOn": "2023-04-03T14:08:26Z",
            "createdBy": "Service_Agent",
            "modifiedBy": "Service_Agent",
            "custom": {}
        },
        "states": [
            {
                "name": "Proposal",
                "guid": "proposal-001"
            },
            {
                "name": "Development"
                "guid": "development-001"
            }
        ],
        "transitions": [
            {
                "source": {
                    "guid": "proposal-001"
                },
                "destination": {
                    "guid": "development-001"
                }
            }
        ]
    }
}

The transitions property reflects valid transitions from one state to another.

Create Model

You need a repository to store the code for models. To create a new model, include the repository URL and the lifecycle GUID in a CreateModel request.

URI: /modelscape/model/api/1.0

{
    "mwtype": "model/CreateModel",
    "name": "Retail PD",
    "description": "Retail Probability of Default (PD) model",
    "repository": "example-repo-dot-com",
    "lifecycle": {
        "guid": "example-lifecycle-guid-001"
    },
    "metaData": {
        "custom": {}
    }
}

Your response contains a GUID identifying the new model.

{
    "mwtype": "model/CreateModelResponse",
    "guid": "example-model-guid-001",
}

Create Model Version

Distinguish between iterations of a model by marking them as model versions. To create a model version, use the CreateModelVersion request. Include a name for the version, a signature (which consists of inputs, parameters, and outputs), the model GUID, and the state GUID. To retrieve the GUID for a state, use a GetLifeCycleByGUID request.

URI: /modelscape/modelversion/api/1.0

{
    "mwtype": "modelversion/CreateModelVersion",
    "model": {
        "guid": "example-model-guid-001"
    },
    "version": "1.0.0",
    "inputs": [
        {
            "name": "income",
            "description": "requester income",
            "unit": "$",
            "sizes": [],
            "dataType": {
                "name": "double"
            },
        }
    ],
    "parameters": [
        {
            "name": "inflation",
            "description": "current inflation",
            "unit": "%",
            "sizes": [],
            "dataType": {
                "name": "double"
            },
        }
    ],
    "outputs": [
        {
            "name": "probability_default",
            "description": "probability of default",
            "unit": "%",
            "sizes": [],
            "dataType": {
                "name": "double"
            },
        }
    ],
    "lifecycleState": "proposal-001",
    "metaData": {
        "custom": {}
    }
}

You receive this GUID for the new model version.

{
    "mwtype": "modelversion/CreateModelVersionResponse",
    "guid": "example-modelversion-guid-001",
}

Update Model Version State to Development

When your proposed model version is ready for development, use UpdateModelVersion to change the model version state from proposal to development.

URI: /modelscape/modelversion/api/1.0

{
    "mwtype": "modelversion/UpdateModelVersion",
    "guid": "example-modelversion-guid-001",
    "lifecycleState": "development-001"
}

You receive this confirmation.

{
    "mwtype": "modelversion/UpdateModelVersionResponse"
}

Set Model Version Commit

Implement your model version, then use SetModelVersionCommit to set the commit of the model version. This step marks a significant point in the model version development history. This setting indicates that this code is for reviewing or deployment. Include any subsequent changes in a new model version to avoid confusion.

In the SetModelVersionCommit request, include the commit hash.

{
    "mwtype": "modelversion/SetModelVersionCommit",
    "guid": "example-modelversion-guid-001",
    "commit": "example_commit_hash_1"
}

You receive this confirmation.

{
    "mwtype": "modelversion/SetModelVersionCommitResponse"
}

Create Review

To create a review for your model version, use CreateReview. Include the Model Version GUID.

URI: /modelscape/review/api/1.0

{
    "mwtype": "review/CreateReview",
    "modelVersion": {
     "guid": "example-modelversion-guid-001",
    }
    "requestMetaData": {
        "description": "Requesting approval for deployment of Retail PD v1.0.0 (Europe 2022)"
    }
    "metaData": {
        "custom": {}
    }
}

You receive a GUID for the review.

{
    "mwtype": "review/CreateReviewResponse",
    "guid": "example-review-001"
}

Update Model Version State to Review

Use UpdateModelVersion to change the model version state from development to review.

URI: /modelscape/modelversion/api/1.0

{
    "mwtype": "modelversion/UpdateModelVersion",
    "guid": "example-modelversion-guid-001",
    "lifecycleState": "review-001"
}

You receive this confirmation.

{
    "mwtype": "modelversion/UpdateModelVersionResponse"
}

Close Review

After you validate your model version, close the review using CloseReview. Include the commit hash.

URI: /modelscape/review/api/1.0

{
    "mwtype": "review/CloseReview",
    "guid": "example-review-001",
    "finalCommit": "example_commit_hash_2",
    "reviewMetaData: {
        "description": "Approving use of Retail PD v1.0.0 (Europe 2022)"
    }
}

You receive this confirmation.

{
    "mwtype": "review/CloseReviewResponse"
}

Update Model Version State to Approved

To update the model version state from review to approved, use UpdateModelVersion.

{
    "mwtype": "modelversion/UpdateModelVersion",
    "guid": "example-modelversion-guid-001",
    "lifecycleState": "approved-001"
}

You receive this confirmation.

{
    "mwtype": "modelversion/UpdateModelVersionResponse"
}

Create Container Image

Use Modelscape Deploy to create a Docker image of your model version.

Create Build

To create a build of your Docker image, use CreateBuild. Include the image name in the buildMetaData.

URI: /modelscape/build/api/1.0

{
    "mwtype": "build/CreateBuild",
    "name": "Retail PD 1.0.0"
    "type":"docker-image"
    "modelVersion": {
        "guid": "example-modelversion-guid-001"
    },
    "buildMetaData": {
        "image": "example-retail-pd:1.0.0"
    },
    "metaData": {
        "custom": {}
    }
}

You receive a GUID identifying the build.

{
    "mwtype": "build/CreateBuildResponse",
    "guid": "example-build-guid-001"
}

Create Deployment Environment

If you do not already have a deployment environment, create one using CreateDeploymentEnvironment.

URI: /modelscape/deployment/api/1.0

{
    "mwtype": "deployment/CreateDeploymentEnvironment",
    "name": "dev"
    "type":"in_cluster"
    "deploymentEnvironmentMetaData": {},
    "metaData": {
        "custom": {}
    }
}

You receive a GUID identifying the deployment environment.

{
    "mwtype": "build/CreateDeploymentEvironmentResponse",
    "guid": "example-deployment-environment-guid-001"
}

Deploy Model

After obtaining approval to deploy your model, use CreateDeployment. Include the build GUID and deployment environment GUID.

URI: /modelscape/deployment/api/1.0

{
    "mwtype": "deployment/CreateDeployment",
    "build": {
        "guid": "example-build-guid-001" 
    }
    "deploymentEvironment": {
        "guid": "example-deployment-environment-guid-001"
    }
    "deploymentMetaData": {},
    "metaData": {
        "custom": {}
    }
}

You receive a confirmation.

{
    "mwtype": "deployment/CreateDeploymentResponse"
}

Update Model Version State to Deployed

After you deploy your build, use UpdateModelVersion to update the model version state to deployed.

URI: /modelscape/modelversion/api/1.0

{
    "mwtype": "modelversion/UpdateModelVersion",
    "guid": "example-modelversion-guid-001",
    "lifecycleState": "deployed-001"
}

You receive this confirmation.

{
    "mwtype": "modelversion/UpdateModelVersionResponse"
}

Evaluate Model

To evaluate your model, use EvaluateDeployment. Provide inputs and parameters that correspond to those you used to create the model version in Create Model Version.

URI: /modelscape/deployment/api/1.0

{
    "mwtype": "deployment/EvaluateDeployment",
    "build": {
        "guid": "example-build-guid-001" 
    }
    "deploymentEvironment": {
        "guid": "example-deployment-environment-guid-001"
    }
    "inputs": {
        "columns": ["income"],
        "index": ["run_1", "run_2"],
        "data": [[50000], [100000]]
    },
    "parameters": {
        "inflation": 3
    },
    "metaData": {
        "custom": {}
    }
}

You receive a response with the deployment output.

{
    "mwtype": "deployment/EvaluateDeploymentResponse",
    "outputs": {
        "columns": ["probability_default"],
        "index": ["run_1", "run_2"],
        "data": [[10,5]]
    },
    "diagnostics": {"run_1": {}, "run_2": {}},
    "batchDiagnostic": {}
}

Related Topics