Model Governance

The Model Governance API provides controls for responsible AI deployment: approval workflows before production promotion, automated drift detection, and fairness parity checks across customer segments.

GET /api/v1/model-governance

Retrieve governance status for a model including approval history and drift check results.

Query Parameters

Parameter	Type	Required	Description
`modelId`	string	Yes	Algorithm model ID

Response

{
  "modelId": "clx...",
  "approvals": [
    {
      "id": "clx...",
      "modelId": "clx...",
      "version": 3,
      "requestedBy": "data-scientist@example.com",
      "status": "approved",
      "reviewedBy": "admin@example.com",
      "reason": "AUC improved from 0.82 to 0.87",
      "createdAt": "2026-03-18T10:00:00.000Z"
    }
  ],
  "driftChecks": [
    {
      "id": "clx...",
      "modelId": "clx...",
      "version": 3,
      "driftDetected": false,
      "psiScore": 0.04,
      "aucDelta": -0.01,
      "checkedAt": "2026-03-18T12:00:00.000Z"
    }
  ]
}

POST /api/v1/model-governance

Perform governance actions. Editor or Admin (review requires Admin).

Actions

`request_approval` — Request approval to promote a model version

{
  "action": "request_approval",
  "modelId": "clx...",
  "version": 3,
  "metrics": { "auc": 0.87, "precision": 0.82, "recall": 0.79 }
}

Response (201):

{ "approvalId": "clx...", "status": "pending" }

`review` — Approve or reject a model promotion (Admin only)

{
  "action": "review",
  "approvalId": "clx...",
  "decision": "approved",
  "reason": "AUC meets threshold, no drift detected"
}

Response:

{ "approvalId": "clx...", "status": "approved" }

`drift_check` — Run a drift detection check

Compares baseline vs. current score distributions using three methods:

PSI (Population Stability Index): measures shift between score distributions (< 0.1 OK, 0.1–0.25 monitor, > 0.25 retrain)
KS (Kolmogorov-Smirnov): max CDF difference between distributions
AUC decay: drop in AUC from baseline

Each check is persisted to the model drift-check history.

{
  "action": "drift_check",
  "modelId": "clx...",
  "version": 3,
  "baselineScores": [0.1, 0.3, 0.5, 0.7, 0.9],
  "currentScores": [0.15, 0.35, 0.45, 0.65, 0.85],
  "baselineAuc": 0.85,
  "currentAuc": 0.82,
  "thresholds": { "psi": 0.25, "ks": 0.1, "aucDecay": 0.05 }
}

Response (200):

{
  "psi": { "score": 0.03, "drifted": false },
  "ks": { "score": 0.05, "drifted": false },
  "aucDecay": { "score": 0.03, "drifted": false },
  "anyDrift": false
}

Field	Type	Description
`psi.score`	number	Population Stability Index (0 = identical distributions)
`psi.drifted`	boolean	`true` if PSI exceeds threshold (default 0.25)
`ks.score`	number	Kolmogorov-Smirnov statistic (0–1)
`ks.drifted`	boolean	`true` if KS exceeds threshold (default 0.1)
`aucDecay.score`	number	`baselineAuc - currentAuc`, floored at zero.
`aucDecay.drifted`	boolean	`true` if AUC dropped more than threshold (default 0.05)
`anyDrift`	boolean	`true` if any of the three checks flagged drift

`parity_check` — Check fairness across customer segments

Compares mean scores across segments and flags those deviating more than maxDeviation from the overall mean.

{
  "action": "parity_check",
  "segmentScores": {
    "young_adults": [0.8, 0.7, 0.9, 0.85],
    "seniors": [0.3, 0.2, 0.4, 0.25],
    "middle_aged": [0.5, 0.6, 0.55, 0.5]
  },
  "maxDeviation": 0.15
}

Response (200):

{
  "results": [
    { "segment": "young_adults", "sampleSize": 4, "meanScore": 0.813, "stdDev": 0.075 },
    { "segment": "seniors", "sampleSize": 4, "meanScore": 0.288, "stdDev": 0.073 },
    { "segment": "middle_aged", "sampleSize": 4, "meanScore": 0.538, "stdDev": 0.041 }
  ],
  "disparityDetected": true,
  "flaggedSegments": ["young_adults", "seniors"]
}

Field	Type	Description
`results`	array	Per-segment statistics (sampleSize, meanScore, stdDev)
`disparityDetected`	boolean	`true` if any segment deviates > `maxDeviation` from overall mean
`flaggedSegments`	string[]	Segments exceeding the deviation threshold

POST /api/v1/models//drift

Feature-distribution drift check. Unlike the drift_check action above (which compares score distributions), this endpoint compares two feature-value snapshots keyed by feature name and returns PSI + KS per feature plus an overall severity verdict. The model id is used only for audit-log attribution — the trained model itself is not read.

This route lives at /api/v1/models/[id]/drift (the models prefix, not algorithm-models), parallel to the model registry surface. It is tenant-scoped, open to any authenticated caller, and rate-limited to 30 requests per minute per tenant.

Path Parameters

Parameter	Type	Description
`id`	string	Algorithm model ID — must belong to the tenant.

Request Body

Field	Type	Required	Description
`reference`	object	Yes	Map of `featureName → number[]` (baseline distribution).
`current`	object	Yes	Map of `featureName → number[]` (current distribution).

{
  "reference": { "age": [22, 34, 41, 55], "income": [40000, 52000, 61000] },
  "current":   { "age": [23, 35, 44, 58], "income": [41000, 53000, 63000] }
}

Response

{
  "modelId": "clx...",
  "modelName": "Credit Card Propensity",
  "features": [
    {
      "feature": "age",
      "psi": { "psi": 0.04, "severity": "none", "bins": [] },
      "ks": { "d": 0.08, "pValue": 0.71, "significant": false }
    }
  ],
  "overallSeverity": "none",
  "alertFeatures": []
}

Field	Type	Description
`features[].psi.psi`	number	Population Stability Index for the feature.
`features[].psi.severity`	string	`none` (< 0.1), `monitor` (0.1–0.25), or `alert` (≥ 0.25).
`features[].ks`	object	Kolmogorov-Smirnov result: `{ d, pValue, significant }` (`significant` when `pValue < 0.05`).
`overallSeverity`	string	`alert` if any feature alerts, else `monitor` if any is monitored, else `none`.
`alertFeatures`	string[]	Feature names whose PSI alerted or whose KS is significant with `d > 0.1`.

Error codes

Code	Reason
`400`	Missing `id`, or request body fails validation.
`404`	Algorithm model not found for tenant.
`429`	Rate limit exceeded (30/min/tenant).

Roles

any authenticated

POST /api/v1/models/import

Bring-your-own-model import. Accepts a multipart/form-data upload of an ONNX model, persists it as an AlgorithmModel with modelType: "onnx_imported", hashes the bytes (sha256), and stores them inline in modelState (or offloads to a configured blob store above the inline threshold).

Only ONNX is supported in V1. Single-file models only; multi-file bundles are rejected. File size cap: 100 MB. Admin role required.

Form fields

Part	Type	Required	Description
`file`	file	Yes	ONNX model bytes.
`name`	string	Yes	Display name for the created model.
`family`	string	Yes	Must be `"onnx_imported"` (the only supported value).
`featureNames`	string	Yes	JSON-encoded ordered `string[]` matching the ONNX input shape.
`featureDefaults`	string	No	JSON-encoded `Record<string, number>` for missing-input handling.

Response

{
  "id": "clx...",
  "name": "Fraud Propensity ONNX",
  "modelType": "onnx_imported",
  "bytesHashSha256": "9f86d081...",
  "size": 248192,
  "featureCount": 12,
  "createdAt": "2026-04-22T10:00:00.000Z"
}

Response: 201 Created

Error codes

Code	Reason
`400`	Missing/invalid `file`, `name`, or `featureNames`; `family` not `onnx_imported`; `featureNames`/`featureDefaults` JSON invalid; or file exceeds 100 MB.
`403`	Caller is not `admin`.

Roles

admin

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

GET /api/v1/model-governance

Query Parameters

Response

POST /api/v1/model-governance

Actions

`request_approval` — Request approval to promote a model version

`review` — Approve or reject a model promotion (Admin only)

`drift_check` — Run a drift detection check

`parity_check` — Check fairness across customer segments

POST /api/v1/models//drift

Path Parameters

Request Body

Response

Error codes

Roles

POST /api/v1/models/import

Form fields

Response

Error codes

Roles

​GET /api/v1/model-governance

​Query Parameters

​Response

​POST /api/v1/model-governance

​Actions

​request_approval — Request approval to promote a model version

​review — Approve or reject a model promotion (Admin only)

​drift_check — Run a drift detection check

​parity_check — Check fairness across customer segments

​POST /api/v1/models//drift

​Path Parameters

​Request Body

​Response

​Error codes

​Roles

​POST /api/v1/models/import

​Form fields

​Response

​Error codes

​Roles

GET /api/v1/model-governance

Query Parameters

Response

POST /api/v1/model-governance

Actions

`request_approval` — Request approval to promote a model version

`review` — Approve or reject a model promotion (Admin only)

`drift_check` — Run a drift detection check

`parity_check` — Check fairness across customer segments

POST /api/v1/models//drift

Path Parameters

Request Body

Response

Error codes

Roles

POST /api/v1/models/import

Form fields

Response

Error codes

Roles