Comment on page

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.

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

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

Parameter	Description
model_id	The ID of the model to delete.

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

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.

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

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.

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

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

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

Parameter	Description
monitor_id	The ID of the monitor to delete.

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

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

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

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

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

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

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

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

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

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.

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

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.

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

API Reference - Previous

Custom Metric Definition Language

Next - API Reference

Metrics Glossary

Last modified 4mo ago