Skip to main content

AI Product Governance API

The AI Product Governance API exposes product-level evidence endpoints for AI Governance, Training Runs, Performance & Safety, runtime governance events, review requests, and Annex IV change log drafting.

All paths below are under /api/v1.0/catalog. Product-level reads require product view access. Mutating endpoints require product edit access.

Product Scope​

The AI Governance workbench is intended for AI product types such as:

  • ML Model
  • AI System
  • LLM Agent
  • AI App
  • Agent

If a product is not supported by the AI Governance workbench, summary and runtime-event endpoints return a validation error.

Endpoints​

MethodEndpointDescription
GET/products/{product_id}/ai-governance-summaryRead governance score, completeness, drift, evidence, audit, and runtime-event counts.
GET/products/{product_id}/ai-runtime-governance-eventsList runtime governance events.
POST/products/{product_id}/ai-runtime-governance-eventsCreate a runtime governance event.
POST/products/{product_id}/ai-governance-review-requestsCreate or reuse an AI governance review request.
GET/products/{product_id}/training-runsList training, fine-tuning, evaluation, and deployment runs.
POST/products/{product_id}/training-runsCreate a training run.
GET/products/{product_id}/training-runs/{run_id}Read one training run.
PATCH/products/{product_id}/training-runs/{run_id}Update one training run.
DELETE/products/{product_id}/training-runs/{run_id}Delete one training run.
GET/products/{product_id}/safety-metricsList performance and safety metrics.
POST/products/{product_id}/safety-metricsCreate a performance or safety metric.
GET/products/{product_id}/safety-metrics/{metric_id}Read one metric.
PATCH/products/{product_id}/safety-metrics/{metric_id}Update one metric.
DELETE/products/{product_id}/safety-metrics/{metric_id}Delete one metric.
POST/products/{product_id}/safety-metrics/{metric_id}/attestAttest a metric.
POST/products/{product_id}/generate-change-logGenerate a draft Annex IV change log entry.

AI Governance Summary​

GET /api/v1.0/catalog/products/{product_id}/ai-governance-summary

Response​

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "product_name": "Claims Triage Model",
  "product_type": "ML Model",
  "lifecycle_gate": "production",
  "review_status": "needs_review",
  "governance_score": 75,
  "completeness": [
    {
      "key": "evaluation_evidence",
      "label": "Evaluation evidence",
      "complete": true,
      "detail": "2 safety metrics and 1 deployed training run"
    }
  ],
  "drift_indicators": [
    {
      "key": "missing_eval",
      "label": "Missing evaluation evidence",
      "severity": "high",
      "active": false,
      "detail": "Evaluation evidence is present."
    }
  ],
  "evidence": [
    {
      "key": "training_runs",
      "label": "Training runs",
      "count": 4,
      "status": "present"
    }
  ],
  "audit_bundle": {},
  "runtime_event_counts": {
    "guardrail_trigger": 3
  },
  "generated_at": "2026-06-29T09:45:00Z"
}

Completeness keys are owner, purpose, risk_classification, data_dependencies, evaluation_evidence, policies, monitoring, and review.

Current drift indicator keys include overdue_review, changed_upstream_data, missing_eval, expired_approval, unresolved_high_risk_mitigation, and stale_documentation.

Runtime Governance Events​

GET /api/v1.0/catalog/products/{product_id}/ai-runtime-governance-events?limit=20&offset=0

Query Parameters​

ParameterTypeDescription
limitintegerNumber of events to return. Default 20, maximum 100.
offsetintegerNumber of events to skip. Default 0.

Events are ordered by occurred_at descending.

POST /api/v1.0/catalog/products/{product_id}/ai-runtime-governance-events

Request Body​

{
  "event_type": "guardrail_trigger",
  "severity": "medium",
  "status": "open",
  "summary": "Prompt-injection guardrail blocked a request.",
  "source": "runtime-guardrails",
  "external_ref": "run_123",
  "event_metadata": {
    "policy": "prompt_injection"
  },
  "occurred_at": "2026-06-29T09:30:00Z"
}

Supported event types are guardrail_trigger, blocked_action, sensitive_data_redaction, human_escalation, policy_exception, and incident_created. Severity values are info, low, medium, high, and critical. Status values are open, acknowledged, and resolved.

If occurred_at is omitted, Qarion records the current time.

AI Governance Review Requests​

POST /api/v1.0/catalog/products/{product_id}/ai-governance-review-requests

Creates a governance review request for active drift indicators. If an open AI governance review request already exists for the product, the API returns that request with deduplicated set to true.

Request Body​

{
  "drift_indicator_keys": [
    "overdue_review",
    "missing_eval"
  ]
}

Omit drift_indicator_keys to request review for all active drift indicators. If no selected drift indicators are active, the endpoint returns 400.

Response​

{
  "id": "9c78c2bb-b33a-4ec7-9f8e-f852b42b8f45",
  "status": "pending",
  "title": "AI governance review: Claims Triage Model",
  "description": "Review active AI governance drift indicators.",
  "details": {
    "source": "ai_governance_workbench",
    "drift_indicator_keys": [
      "missing_eval"
    ]
  },
  "requested_at": "2026-06-29T09:48:00Z",
  "deduplicated": false
}

Training Runs​

GET /api/v1.0/catalog/products/{product_id}/training-runs?skip=0&limit=50

Lists training runs ordered by started_at descending with null start times last. Pagination metadata is returned in response headers.

HeaderDescription
X-Total-CountTotal matching runs.
X-PageCurrent page number based on skip and limit.
X-Has-MoreWhether another page exists.
POST /api/v1.0/catalog/products/{product_id}/training-runs
PATCH /api/v1.0/catalog/products/{product_id}/training-runs/{run_id}

Request Body​

{
  "run_name": "June retraining",
  "run_type": "training",
  "status": "completed",
  "dataset_name": "claims_features",
  "dataset_version": "2026.06",
  "dataset_uri": "s3://qarion-evidence/claims/2026-06",
  "training_samples": 120000,
  "validation_samples": 20000,
  "test_samples": 20000,
  "random_seed": 42,
  "hyperparameters": {
    "learning_rate": 0.01
  },
  "metrics": {
    "auc": 0.94
  },
  "model_artifact_uri": "model://claims-triage/2026-06",
  "framework_version": "xgboost 2.0",
  "environment": "prod-training",
  "duration_seconds": 4200,
  "notes": "Retrained with updated claims data.",
  "is_deployed": true,
  "started_at": "2026-06-28T08:00:00Z",
  "completed_at": "2026-06-28T09:10:00Z"
}

run_type values are training, fine_tuning, evaluation, and deployment. status values are pending, running, completed, failed, and cancelled.

When a run is saved with is_deployed set to true, Qarion clears the deployed flag from the product's other runs, stamps deployment metadata, and triggers AI governance reassessment for the product.

GET /api/v1.0/catalog/products/{product_id}/training-runs/{run_id}
DELETE /api/v1.0/catalog/products/{product_id}/training-runs/{run_id}

Delete returns 204 No Content.

Performance And Safety Metrics​

GET /api/v1.0/catalog/products/{product_id}/safety-metrics?category=fairness&skip=0&limit=50

Lists metrics ordered by category, metric name, and newest measurement. Use category to filter to one metric family.

POST /api/v1.0/catalog/products/{product_id}/safety-metrics
PATCH /api/v1.0/catalog/products/{product_id}/safety-metrics/{metric_id}

Request Body​

{
  "category": "fairness",
  "metric_name": "False positive rate parity",
  "metric_value": 0.03,
  "unit": "ratio",
  "threshold_warning": 0.05,
  "threshold_critical": 0.1,
  "status": "healthy",
  "test_dataset": "claims_fairness_eval",
  "test_dataset_version": "2026.06",
  "methodology": "Compared false positive rate by age band and region.",
  "measured_at": "2026-06-28T10:00:00Z",
  "demographic_group": "all groups",
  "external_url": "https://example.internal/reports/claims-fairness",
  "notes": "Reviewed by model risk."
}

Categories are accuracy, robustness, fairness, cybersecurity, and drift. Status values are healthy, warning, critical, and not_available.

Patch requests update supplied non-null fields. Omitted fields are unchanged.

POST /api/v1.0/catalog/products/{product_id}/safety-metrics/{metric_id}/attest

Attestation records the current user and timestamp on the metric.

GET /api/v1.0/catalog/products/{product_id}/safety-metrics/{metric_id}
DELETE /api/v1.0/catalog/products/{product_id}/safety-metrics/{metric_id}

Delete returns 204 No Content.

Technical Documentation And Change Logs​

AI technical documentation is stored with the product's AI details. Use the Catalog Product API to update ai_details.technical_documentation:

PATCH /api/v1.0/catalog/spaces/{space_slug}/products/{product_id}
{
  "ai_details": {
    "technical_documentation": {
      "general_description": "Purpose, provider, version history...",
      "system_architecture": "Design choices and components...",
      "data_governance": "Training data origin and preparation...",
      "risk_management": "Risks, mitigations, residual risk...",
      "human_oversight": "Oversight mechanisms and limitations...",
      "performance_testing": "Benchmark and test methodology...",
      "change_log": "## 2026-06-29\nUpdated retraining evidence."
    }
  }
}

Generate draft change log text with:

POST /api/v1.0/catalog/products/{product_id}/generate-change-log
{
  "existing_change_log": "## 2026-05-01\nInitial model registration."
}

Response​

{
  "change_log_entry": "## 2026-06-29\n- Updated training run evidence..."
}

This endpoint requires the ai.change_log_generation feature and an AI provider configuration. LLM configuration, provider, and unexpected generation failures are returned as 502.

Errors​

StatusDescription
400Unsupported product type, no active selected drift indicators, or invalid payload.
401Authentication is missing or invalid.
403Caller does not have the required product permission.
404Product, run, metric, or linked review target was not found.
422Request body or query parameters failed validation.
502AI change-log generation could not complete because of provider configuration or runtime failure.