Compare Versions

Page Outline

• Path Parameters
• Query Parameters
• Behavior
• Response

---

Returns a side-by-side comparison of metrics, hyperparameters, and configuration between two model versions.

Base Path: /api/v1/models

Method: GET

Path: /{model_id}/versions/compare

Auth: Requires a valid Bearer token (Authorization: Bearer <JWT>)

Path Parameters

Parameter	Type	Description
model_id	string	Unique identifier of the parent model

Query Parameters

Parameter	Type	Default	Description
version_a	string	—	Required. ID of the first version to compare
version_b	string	—	Required. ID of the second version to compare

Behavior

• Both version_a and version_b must belong to the specified model_id; otherwise returns HTTP 422.
• The diff field in the response highlights fields where the two versions differ.
• Metric deltas are expressed as version_b_value - version_a_value (positive = version B is better for that metric).
• Returns HTTP 404 if either version ID is not found.
• Audit logging is not triggered on comparison reads.

Response

Returns a VersionComparison object.

{
  "model_id": "mdl-7f3a19bc",
  "version_a": {
    "version_id": "ver-001",
    "version_number": 1,
    "metrics": { "accuracy": 0.889, "f1_score": 0.874, "roc_auc": 0.941 },
    "hyperparameters": { "n_estimators": 100, "max_depth": 4 }
  },
  "version_b": {
    "version_id": "ver-002",
    "version_number": 3,
    "metrics": { "accuracy": 0.934, "f1_score": 0.921, "roc_auc": 0.967 },
    "hyperparameters": { "n_estimators": 200, "max_depth": 6 }
  },
  "metric_deltas": {
    "accuracy": +0.045,
    "f1_score": +0.047,
    "roc_auc": +0.026
  },
  "config_diff": {
    "n_estimators": { "version_a": 100, "version_b": 200 },
    "max_depth": { "version_a": 4, "version_b": 6 }
  }
}