API Reference

This page documents the REST API exposed by the Data Valuation Engine backend.

Base URL

The frontend calls the backend using VITE_API_BASE_URL (see Configuration).

For local development this is typically:

Authentication

Authentication depends on your deployment:

  • If VITE_USE_KEYCLOAK=false, the API is typically used without Keycloak authentication in local/demo setups.

  • If VITE_USE_KEYCLOAK=true, the frontend obtains a Keycloak access token and calls the API with a Bearer token.

Bearer token header (when enabled)

Authorization: Bearer <access_token>

Endpoint Index

Endpoint Description

POST /api/correlations/analyze

Analyze feature correlations (Pearson / Spearman / Kendall)

POST /api/feature-importance/analyze

Analyze feature importance (model ranking + SHAP)

GET /api/spatial-hitl/task/{data_collection_name}/dataset-columns

HITL: inspect dataset columns for a saved task

POST /api/spatial-hitl/task/{data_collection_name}/audit

HITL: run audit for a task

POST /api/spatial-hitl/task/{data_collection_name}/mitigate/relabel

HITL: run relabeling mitigation for a task

POST /api/spatial-hitl/task/{data_collection_name}/mitigate/threshold

HITL: run threshold mitigation for a task

POST /api/spatial-hitl/task/{data_collection_name}/mitigate/writeback

HITL: write back mitigated predictions

GET /api/dave/documents

List configuration documents (tasks)

GET /api/dave/document/{data_collection_name}

Get a configuration document by id

PATCH /api/dave/document/{data_collection_name}

Update a configuration document (e.g., status)

DELETE /api/dave/document/{data_collection_name}

Delete a configuration document

Correlations

POST /api/correlations/analyze?dataset-id="<dataset-id>"

Analyzes feature correlations for the specified dataset and returns the data required to plot correlation matrix(es).

Query parameters

dataset-id (string, required) Identifier of the dataset to analyze.

Request body

Use the following JSON fields to select which correlation methods to compute. You may enable either one or both.

{
  "include_pearson": true,
  "include_spearman": true,
  "include_kendall": true
}

Example

Perform a POST request to the endpoint below with the following JSON body.

POST /api/correlations/analyze?dataset-id="abc123"
Content-Type: application/json
{
  "include_pearson": true,
  "include_spearman": true
}

Response (200)

The response includes the dataset shape and feature count, plus one or both correlation matrices depending on the request.

dataset_shape is a two-element array [rows, columns].

feature_count is the number of features (columns) included in the correlation computation.

pearson and spearman contain square matrices represented as nested JSON objects: each top-level key is a column name, and its value maps every column name to a correlation coefficient.

{
  "dataset_shape": [569, 31],
  "feature_count": 31,
  "pearson": {
    "column-name-1": {
      "column-name-1": 1.0,
      "column-name-2": 0.3,
      ...
      "column-name-n": 0.5
    }
  },
  "spearman": {
    "column-name-1": {
      "column-name-1": 1.0,
      "column-name-2": 0.1,
      ...
      "column-name-n": 0.35
    }
  }
}

Feature Importance

POST /api/feature-importance/analyze?dataset-id="<dataset-id>"

Computes feature importance for the specified dataset and returns a ranked list of features, along with the evaluated models and their accuracy scores.

Query parameters

dataset-id (string, required) Identifier of the dataset to analyze.

Request body

This endpoint accepts an optional list of model names to restrict which models are evaluated. If omitted or empty, the service evaluates the default set of supported models. The available models are: "Extra Trees Classifier", "Light Gradient Boosting Machine", "Random Forest Classifier", and "Decision Tree Classifier".

{
  "model_names": [
    "Extra Trees Classifier",
    "Light Gradient Boosting Machine",
    "Random Forest Classifier",
    "Decision Tree Classifier"
  ]
}

Example

Perform a POST request to the endpoint below.

POST /api/feature-importance/analyze?dataset-id="abc123"
Content-Type: application/json

Response (200)

The response includes the dataset shape, the best-performing model, the list of evaluated models with their accuracy scores, and the ranked feature importance output.

dataset_shape is a two-element array [rows, columns].

model_names contains the names of the evaluated models, in the same order as accuracy_scores.

accuracy_scores contains the accuracy score for each model, aligned by index with model_names.

best_model is the name of the model selected as best for the run.

feature_importance is an ordered list of objects where: Feature is the feature name and Importance is its importance score. Higher values indicate more influential features.

{
  "feature_importance": [
    { "Feature": "worst radius", "Importance": 0.0581 },
    { "Feature": "worst perimeter", "Importance": 0.0536 },
    { "Feature": "worst concave points", "Importance": 0.0466 }
  ],
  "model_names": [
    "Extra Trees Classifier",
    "Light Gradient Boosting Machine",
    "Random Forest Classifier",
    "Decision Tree Classifier"
  ],
  "accuracy_scores": [0.9698, 0.968, 0.9627, 0.9254],
  "best_model": "Extra Trees Classifier",
  "dataset_shape": [569, 31]
}

Spatial HITL

The HITL endpoints operate on a persisted configuration/task identified by data_collection_name. These endpoints load data from the configured MongoDB collection, build the required payload internally, and then apply the requested module.

Common Concepts

  • data_collection_name: A string referring to a stored collection name.

  • Field Mapping: Allows the user to map expected field names (lat/lon/y_pred/etc.) to the actual column names in the dataset collection. If not provided, defaults are used:

{
  "lat": "lat",
  "lon": "lon",
  "y_true": "y_true",
  "y_pred": "y_pred",
  "region_ids": "region_ids",
  "y_pred_prob": "y_pred_prob"
}

  • Region Polygons (optional): Can be provided to support visualization and/or region-based computation.

[
  {
    "polygon": [
      [23.70, 37.99],
      [23.70, 37.97],
      [23.74, 37.97],
      [23.74, 37.99]
    ]
  }
]
Polygons are validated as a list of points with bounds checking. Each point is treated as [lon, lat].

GET /api/spatial-hitl/task/{data_collection_name}/dataset-columns

Returns the dataset columns available for mapping. The service samples up to ~200 documents to infer available fields.

Path parameter

  • data_collection_name (required): The collection name

Example

GET /api/spatial-hitl/task/example_collection_name/dataset-columns

Response (200)

A list of field names (strings):

["lat", "lon", "y_pred", "y_true", "region_ids", "y_pred_prob", "..."]

Errors

  • 400 Dataset is empty

  • 404 Configuration not found

  • 503 Database unavailable (Mongo not reachable)

  • 422 Validation error (invalid id format)

POST /api/spatial-hitl/task/{data_collection_name}/audit

Runs a spatial bias audit using dataset columns and optional field mapping.

Request body

Field Meaning

n_worlds

Monte Carlo samples ("alternate worlds"). Default: 1000.

signif_level

Significance level (0,1). Default: 0.005.

equal_opp

If true, audits Equal Opportunity (TPR) and requires y_true for all records. Default: true.

full_distribution

If 'true', displays all instances in maps, else up to 10000 sample, Default: 'false'.

region

Optional region polygons (see above).

mapping

Optional field mapping (see above).

Example

POST /api/spatial-hitl/task/example_collection_name/audit
Content-Type: application/json

{
  "n_worlds": 1000,
  "signif_level": 0.005,
  "equal_opp": true,
  "full_distribution": false,
  "region": [
    { "polygon": [[23.70, 37.99], [23.70, 37.97], [23.74, 37.97], [23.74, 37.99]] }
  ],
  "mapping": {
    "lat": "lat",
    "lon": "lon",
    "y_true": "y_true",
    "y_pred": "y_pred",
    "region_ids": "region_ids"
  }
}

Response (200)

  • sbi_score, signif_thresh, total_signif_regions

  • maps as fair_map_html and fair_map_image

  • stats: per-region entries { idx, stat, is_signif }

Errors

  • 400 Invalid configuration/dataset (missing columns, bad types, empty dataset)

  • 404 Configuration not found

  • 503 Database unavailable

  • 422 Validation error

POST /api/spatial-hitl/task/{data_collection_name}/mitigate/relabel

Runs mitigation via relabeling (prediction flips) on the task dataset.

Request body

Includes audit parameters plus mitigation controls:

Field Meaning

n_worlds

Monte Carlo samples ("alternate worlds"). Default: 1000.

signif_level

Significance level (0,1). Default: 0.005.

equal_opp

If true, audits Equal Opportunity (TPR) and requires y_true for all records. Default: true.

full_distribution

If 'true', displays all instances in maps, else up to 10000 sample, Default: 'false'.

region

Optional region polygons (see above).

mapping

Optional field mapping (see above).

approx

Whether to use an approximate solver. Default: true.

budget_constr

Maximum flip budget in [0,1]. Default: 0.2.

pr_constr

Allowed positive-rate change tolerance in [0,1]. Default: 0.1.

work_limit

Work limit (approx runtime control). Default: 30.

Example

POST /api/spatial-hitl/task/example_collection_name/mitigate/relabel
Content-Type: application/json

{
  "n_worlds": 1000,
  "signif_level": 0.005,
  "equal_opp": true,
  "full_distribution": false,
  "region": [
    { "polygon": [[23.70, 37.99], [23.70, 37.97], [23.74, 37.97], [23.74, 37.99]] }
  ],
  "mapping": {
    "lat": "lat",
    "lon": "lon",
    "y_true": "y_true",
    "y_pred": "y_pred",
    "region_ids": "region_ids"
  },
  "approx": true,
  "budget_constr": 0.2,
  "pr_constr": 0.1,
  "work_limit": 30
}

Response (200)

  • metrics_before, metrics_after: performance + fairness metrics

  • audit_before_mitigation, audit_after_mitigation: audit payloads (maps + stats)

  • mitigated_preds: final predictions

  • flips_map_html / flips_map_image: visualization of flips

  • solver_status_code, solver_status_message: optimization status

Errors

  • 400 Invalid configuration/dataset (missing columns, bad types, empty dataset)

  • 404 Configuration not found

  • 503 Database unavailable

  • 422 Validation error

POST /api/spatial-hitl/task/{data_collection_name}/mitigate/threshold

Runs mitigation via per-region decision thresholds.

This endpoint: 1. loads the task dataset, 2. validates required columns (including probabilities), 3. performs an internal train/test split using train_ratio (+ optional stratification), 4. fits thresholds on the train subset and applies them to the test subset.

Request body

Field Meaning

n_worlds

Monte Carlo samples ("alternate worlds"). Default: 1000.

signif_level

Significance level (0,1). Default: 0.005.

equal_opp

If true, audits Equal Opportunity (TPR) and requires y_true for all records. Default: true.

full_distribution

If 'true', displays all instances in maps, else up to 10000 sample, Default: 'false'.

region

Optional polygons for visualization / region-based computations (used as predict_region internally).

mapping

Optional field mapping.

approx

Whether to use an approximate solver. Default: true.

budget_constr

Maximum flip budget in [0,1]. Default: 0.2.

pr_constr

Allowed positive-rate change tolerance in [0,1]. Default: 0.1.

default_boundary

Base model threshold (e.g., 0.5). Default: 0.5.

train_ratio

Fraction of rows used for training thresholds. Default: 0.7.

stratified

If true, preserves label distribution during split (uses y_true when present, else falls back to y_pred). Default: true.

random_state

Seed for reproducible split. Default: 42.

Example

POST /api/spatial-hitl/task/example_collection_name/mitigate/threshold
Content-Type: application/json

{
  "n_worlds": 1000,
  "signif_level": 0.005,
  "equal_opp": true,
  "full_distribution": false,
  "region": [
    { "polygon": [[23.70, 37.99], [23.70, 37.97], [23.74, 37.97], [23.74, 37.99]] }
  ],
  "mapping": {
    "lat": "lat",
    "lon": "lon",
    "y_true": "y_true",
    "y_pred": "y_pred",
    "region_ids": "region_ids",
    "y_pred_prob": "y_pred_prob"
  },
  "approx": true,
  "budget_constr": 0.2,
  "pr_constr": 0.1,
  "work_limit": 30,
  "default_boundary": 0.5,
  "train_ratio": 0.7,
  "stratified": true,
  "random_state": 42
}

Response (200)

  • metrics_before, metrics_after: performance + fairness metrics

  • audit_before_mitigation, audit_after_mitigation: audit payloads (maps + stats)

  • mitigated_preds: final predictions

  • flips_map_html / flips_map_image: visualization of flips

  • solver_status_code, solver_status_message: optimization status

  • threshold_chart_before, threshold_chart_after: threshold plots (encoded)

  • new_thresholds: per-region thresholds (and tie-breaking values if applicable)

Errors

  • 400 Invalid configuration/dataset (missing columns, bad probability values, empty dataset, invalid split)

  • 404 Configuration not found

  • 503 Database unavailable

  • 422 Validation error

POST /api/spatial-hitl/task/{data_collection_name}/mitigate/writeback

Writes mitigated predictions back to the dataset collection by setting a new field for each record.

Field name must match the pattern: ^[A-Za-z_][A-Za-z0-9_]*$.

Request body

{
  "new_field": "mitigated_prediction",
  "preds": [
    { "doc_id": "abc123", "y_pred": 0 },
    { "doc_id": "def456", "y_pred": 1 }
  ]
}

Example

POST /api/spatial-hitl/task/example_collection_name/mitigate/writeback
Content-Type: application/json

{
  "new_field": "mitigated_prediction",
  "preds": [
    { "doc_id": "65a1b2c3d4e5f67890123456", "y_pred": 0 },
    { "doc_id": "65a1b2c3d4e5f67890123457", "y_pred": 1 }
  ]
}

Response (200)

Returns bulk update results:

{
  "matched": 2,
  "modified": 2,
  "field": "mitigated_prediction"
}

Errors

  • 400 Invalid field name

  • 404 Configuration not found

  • 503 Database unavailable

  • 422 Validation error

Dave Tasks

Dave task endpoints manage configuration documents that represent pipeline/task executions and their metadata.

These endpoints require MongoDB to be enabled (USE_MONGO=true).

GET /api/dave/documents

List configuration documents, optionally filtering by status and/or component.

Query parameters

Parameter Meaning

status

Optional status filter.

component

Optional component filter.

Example

GET /api/dave/documents?status=pending&component=DVE

Response (200)

Returns a list of configuration documents:

Field Meaning

pipeline_name

Pipeline name

database_name

Mongo database storing the collection

data_collection_name

Mongo collection containing the dataset

status

Human-in-the-loop status (e.g., pending, done)

component

Component id

started_at, ended_at

Execution timestamps (ISO8601)

Errors

  • 503 Database unavailable

  • 422 Validation error

GET /api/dave/document/{collection_name}

Get a single configuration document by its id.

Path parameter

  • collection_name (required): The name of the collection.

Example

GET /api/dave/document/example_collection_name

Errors

  • 404 Configuration not found

  • 503 Database unavailable

  • 422 Validation error

PATCH /api/dave/document/{collection_name}

Update a configuration document (currently supports updating status). If status is set to done, the service also sets ended_at to the current UTC time.

Request body

{
  "status": "done"
}

Example

PATCH /api/dave/document/example_collection_name
Content-Type: application/json

{
  "status": "done"
}

Errors

  • 404 Configuration not found

  • 503 Database unavailable

  • 422 Validation error

DELETE /api/dave/document/{collection_name}

Delete a configuration document by id.

Example

DELETE /api/dave/document/example_collection_name

Response (204)

No content.

See Also