Links
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": [
]
}
],
"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.