REST API

Aporia provides a REST API, which is currently in beta.

Using the REST API

The API is accessible thorough https://app.aporia.com/v1beta.

To use the API, you must pass your token in the authorization header of each request:

Authorization: Bearer <token>

Endpoints

Create Model

Creates a new model.

POST https://app.aporia.com/v1beta/models
{
    "id": "my-model",
    "name": "My Model",
    "description": "My awesome model",
    "color": "turquoise",
    "icon": "fraud-detection",
    "owner": "[email protected]",
    "tags": {
        "foo": "bar"
    }
}

{
    "id": "my-model"
}

Request Parameters

Parameter	Type	Required	Description
id	str	False	A unique identifier for the new model, which will be used in all future operations. If this parameter is not passed, an id will be generated from the name parameter
name	str	True	A name for the new model, which will be displayed in Aporia's dashboard
description	str	False	A description of the model
color	ModelColor	False	A color to distinguish the model in Aporia's dashboard. Defaults to blue
icon	ModelIcon	False	An icon that indicates the model's designation. Defaults to general
owner	str	False	The email of the model owner (must be a registered aporia user)
tags	Dict[str, str]	False	A mapping of tag keys to tag values

ModelColor options: blue,arctic_blue, green, turquoise, pink, purple, yellow, red

ModelIcon options: general, churn-and-retention, conversion-predict, anomaly, dynamic-pricing, email-filtering, demand-forecasting, ltv, personalization, fraud-detection, credit-risk, recommendations

Response

Value	Type	Description
id	str	The id of the newly created model

Delete Model

Deletes a model.

DELETE https://app.aporia.com/v1beta/models/<model_id>/

Path Parameters

Parameter	Description
model_id	The ID of the model to delete.

Get Model Versions

Returns all model versions and their creation date.

GET https://app.aporia.com/v1beta/models/<model_id>/versions

[
    {
        "id": "4dc246a2-0fd4-4342-8e30-95c2b43e8b63",
        "name": "v1",
        "model_type": "regression",
        "created_at": "2021-10-03T10:23:00.913784+00:00"
    },
    {
        "id": "21a6ee3f-8102-4e54-90bd-5809cff409cd",
        "name": "v2",
        "model_type": "regression",
        "created_at": "2021-10-03T10:33:54.073001+00:00"
    }
]

Path Parameters

Parameter	Description
model_id	The ID of the model whose versions you wish to fetch.

Response

A List of VersionDetails objects, each with the following format:

Value	Type	Description
id	str	Version id.
name	str	Version name.
model_type	str	The type of the model created by the version (regression, binary, etc).
created_at	str	The creation date of the version.

Create Model Version

Defines a new version for an existing model.

POST https://app.aporia.com/v1beta/models/<model_id>/versions
{
    "name": "v1",
    "model_type": "binary",
    "version_schema": {
        "features": {
            "amount": "numeric",
            "owner": "string",
            "is_new": "boolean",
            "created_at": "datetime"
        },
        "predictions": {
            "approved": "boolean",
            "another_output_field": "numeric"
        }
    },
    "feature_importance" : {
        "amount": 100,
        "owner": 20,
        "is_new": 50,
        "created_at": 10
    }
}

{
    "id": "d84a497b-6a13-49e3-91f0-b01117f49ac7"
}

Path Parameters

Parameter	Description
model_id	The ID of the model for which the new version is being defined

Request Parameters

Parameter	Type	Required	Description
name	str	True	A unique name for the new model version
model_type	ModelType	True	Model type
version_schema	object	The schema for the new version, mapping various fields to their types
feature_importance	Dict[str, float]	False	Mapping between feature name to it's importance.

Notes

• ModelType options: binary, multiclass, multi-label, regression

• Feature positions: When reporting a model schema, there is an optional argument called feature_positions. This argument provides mapping of feature names to feature positions in the dataframe which the model receives. Feature Positions are required for Explainability capabilities. In the console, to explain a data point, go to Model Overview -> Investigation Toolbox -> Data points and click Explain on a specific data point. For example:

"feature_positions":{
    "Age":1,
    "Gender:2
}

Response

Value	Type	Description
id	UUID	The id of the new model version

Create Monitor

Creates a new monitor.

The documentation for each monitor contains an example of creating that monitor using the REST API.

POST https://app.aporia.com/v1beta/monitors
{
    "name": "Hourly Predictions > 100",
    "type": "model_activity",
    "scheduling": "*/5 * * * *",
    "configuration":  {
        "configuration": {
            "focal": {
                "source": "SERVING",
                "timePeriod": "1h"
            },
            "metric": {
                "type": "count",
                "field": "_id"
            },
            "actions": [
                {
                    "type": "ALERT",
                    "schema": "v1",
                    "severity": "MEDIUM",
                    "alertType": "model_activity_threshold",
                    "description": "An anomaly in the number of total predictions within the defined limits was detected.<br />The anomaly was observed in the <b>{model}</b> model, in version <b>{model_version}</b> for the <b>last {focal_time_period} ({focal_times})</b> <b>{focal_segment}</b>.<br /><br />Based on defined limits, the count was expected to be above <b>{min_threshold}</b>, but <b>{focal_value}</b> was received.<br />",
                    "notification": [
                        {
                            "type": "EMAIL",
                            "emails": [
                                "[email protected]"
                            ]
                        }
                    ],
                    "visualization": "value_over_time"
                }
            ],
            "logicEvaluations": [
                {
                    "max": null,
                    "min": 100,
                    "name": "RANGE"
                }
            ]
        },
        "identification": {
            "models": {
                "id": "seed-0000-5wfh"
            },
            "segment": {
                "group": null
            },
            "environment": null
        }
    }
}

{
    "id": "a5d11808-0a42-4d25-84fa-0cc71173044c"
}

Request Parameters

Parameter	Type	Required	Description
name	str	True	A name for the new monitor, which will be displayed in Aporia's dashboard
type	MonitorType	True	The type of monitor to create
scheduling	str	True	A cron expression that indicates how often the monitor will run
configuration	object	True	The monitor's configuration
is_active	bool	False	True if the new monitor should be created as active, False if it should be created as inactive
custom_alert_description	str	False	A custom description for the alerts generated by this monitor

MonitorType options: model_activity, missing_values, data_drift, prediction_drift, values_range, new_values, model_staleness, performance_degradation, metric_change, custom_metric

Response

Value	Type	Description
id	UUID	The id of the newly created monitor

Delete Monitor

Deletes a monitor.

DELETE https://app.aporia.com/v1beta/monitors/<monitor_id>/

Path Parameters

Parameter	Description
monitor_id	The ID of the monitor to delete.

Get Existing Environments

Return the defined environments.

GET https://app.aporia.com/v1beta/environments

{
    "environments": [
        {
            "id": "12345678-1234-1234-1234-1234567890abc",
            "name": "local-dev"
        }
    ]
}

Request Parameters

No parameters required for the request.

Response

Return "environments" list of objects with the following fields:

Value	Type	Description
id	UUID	The id of the environment
name	str	The name of the environment

Get Model Tags

Returns all of the tags that were defined for a model.

GET https://app.aporia.com/v1beta/models/<model_id>/tags

{
    "tags": {
        "foo": "bar",
        "tag_key": "tag_value"
    }
}

Path Parameters

Parameter	Description
model_id	The ID of the model whose tags you wish to fetch.

Response

Value	Type	Description
tags	Dict[str, str]	A mapping of tag keys to tag values

Delete Model Tag

Deletes a single model tag.

DELETE https://app.aporia.com/v1beta/models/<model_id>/tags/<tag_key>

Path Parameters

Parameter	Description
model_id	The ID of the model whose tags you wish to fetch.
tag_key	The key of the tag to delete.

Create Model Tags

Creates or updates model tags.

POST https://app.aporia.com/v1beta/models/<model_id>/tags
{
    "tags": {
        "tag_1": "value_1",
        "foo": "bar",
        "my tag key": "my-tag-value!"
    }
}

Path Parameters

Parameter	Description
model_id	The ID of the model whose tags you wish to fetch.

Request Parameters

Parameter	Type	Required	Description
tags	Dict[str, str]	True	A mapping of tag keys to tag values

Notes

• Each model is restricted to 10 tags

• Tag keys are restricted to 15 characters, and may only contain letters, numbers, spaces, '-' and '_'.

• Tag values are restricted to 100 characters, and may only contain letters, numbers and special characters

• If a tag key already exists, you can use this enpoint to update its value

Update Model Owner

Update the owner of an existing model.

POST https://app.aporia.com/v1beta/models/<model_id>/owner
{
    "owner": "[email protected]"
}

Path Parameters

Parameter	Description
model_id	The ID of the model for which you would like to update an owner.

Request Parameters

Parameter	Type	Required	Description
owner	str	True	The email of the model owner (must be a registered aporia user).

Response

Value	Type	Description
model_id	str	The ID of the model that was updated.
owner	str	The email of new model's owner.

Update Feature Positions

Update feature positions for an existing model version. Feature Positions are required for Explainability capabilities. In the console, to explain a datapoint, go to Model Overview -> Investigation Toolbox -> Datapoints and click Explain on a specific datapoint.

POST https://app.aporia.com/v1beta/models/{model_id}/versions/{model_version}/feature_positions
{
    "feature_positions":{
            "Age": 1,
            "Gender: 2
        }
}

Path Parameters

Parameter	Description
model_id	The ID of the model for which you would like to update features' positions.
model_version	The version for which you would like to update an features' positions.

Request Parameters

Parameter	Type	Required	Description
feature_positions	dict	True	Mapping of feature names to feature positions in the dataframe which the model receives.

Notes

• Features should be identical to the model schema.

Update Feature Importance

Update feature importance for an existing model version.

POST https://app.aporia.com/v1beta/models/{model_id}/versions/{model_version}/feature_importance
{
    "feature_importance":{
            "Age": 100,
            "Gender: 50
        }
}

Path Parameters

Parameter	Description
model_id	The ID of the model for which you would like to update features' importance.
model_version	The version for which you would like to update an features' importance.

Request Parameters

Parameter	Type	Required	Description
feature_importance	dict	True	Mapping of feature names to feature importance.

Notes

• Mapping of features from the scema and their importance is expected. Partial mappings are also supported.

• When using the API call, all previous reported feature importance values will be overridden.