Risk Register API

The Risk Register API manages space-scoped AI risk entries, product links, scoring, status updates, templates, and heat-map aggregation. Product Detail uses the same API with a product_id filter to show risks linked to one AI product.

All paths below are under /api/v1.0. The router is gated by governance.risk_assessment and requires access to the target space.

Endpoints Overview

Method	Endpoint	Description
POST	/catalog/spaces/{space_slug}/risk-register/	Create a risk entry.
GET	/catalog/spaces/{space_slug}/risk-register/	List risk entries with optional filters.
GET	/catalog/spaces/{space_slug}/risk-register/heat-map	Get aggregated heat-map data.
GET	/catalog/spaces/{space_slug}/risk-register/templates	Get reusable risk templates.
GET	/catalog/spaces/{space_slug}/risk-register/{entry_id}	Retrieve one risk entry.
PUT	/catalog/spaces/{space_slug}/risk-register/{entry_id}	Update risk details or status.
POST	/catalog/spaces/{space_slug}/risk-register/{entry_id}/link-products	Link additional products.
DELETE	/catalog/spaces/{space_slug}/risk-register/{entry_id}/products/{product_id}	Remove one product link.

Scoring And Status

Field	Values
category	bias, privacy, safety, security, transparency, environmental, fundamental_rights, other
severity, likelihood, impact	Integers from 1 to 5
status	open, mitigating, accepted, closed
reassessment_cadence	monthly, quarterly, semi_annual, annual

The service computes risk_score as round(severity * likelihood * impact / 125 * 100).

Tier	Threshold
unacceptable	risk_score >= 80
high	risk_score >= 50
limited	risk_score >= 25
minimal	Otherwise

List Risk Entries

GET /api/v1.0/catalog/spaces/{space_slug}/risk-register/?limit=20&offset=0

Query Parameters

Parameter	Type	Description
category	string	Filter by risk category
status	string	Filter by status
tier	string	Filter by risk tier
product_id	UUID	Filter by linked product
limit	integer	Page size, 1-100
offset	integer	Pagination offset

The list is ordered newest first.

Risk Heat Map

GET /api/v1.0/catalog/spaces/{space_slug}/risk-register/heat-map

Returns aggregated risk counts by category and derived tier, plus status totals:

{
  "cells": [
    { "category": "bias", "tier": "high", "count": 2 }
  ],
  "total_risks": 8,
  "open_count": 3,
  "mitigating_count": 2,
  "accepted_count": 1,
  "closed_count": 2
}

Risk Templates

GET /api/v1.0/catalog/spaces/{space_slug}/risk-register/templates

Returns built-in templates for bias, privacy, safety, transparency, security, and environmental risks. Each template includes default scoring and suggested mitigation text.

Create Risk Entry

POST /api/v1.0/catalog/spaces/{space_slug}/risk-register/

{
  "title": "Model drift in credit scoring",
  "description": "Performance degradation detected",
  "category": "safety",
  "severity": 4,
  "likelihood": 3,
  "impact": 4,
  "misuse_scenarios": [
    {
      "scenario": "Scores are reused outside the approved credit workflow.",
      "countermeasure": "Limit API consumers and monitor downstream usage.",
      "severity": "high"
    }
  ],
  "mitigations": [
    {
      "title": "Add monthly drift review",
      "status": "pending",
      "priority": "high"
    }
  ],
  "product_ids": ["00000000-0000-0000-0000-000000000000"],
  "risk_owner_id": "00000000-0000-0000-0000-000000000000",
  "reassessment_cadence": "quarterly"
}

The response includes the computed risk_score, derived risk_tier, linked product_ids, and next_reassessment_at when a valid cadence is supplied.

Update Risk Entry

PUT /api/v1.0/catalog/spaces/{space_slug}/risk-register/{entry_id}

{
  "status": "mitigating",
  "severity": 3,
  "residual_risk_level": "limited",
  "residual_justification": "Monitoring and human review reduce exposure."
}

Changing severity, likelihood, or impact recomputes risk_score and risk_tier. Changing reassessment_cadence recomputes next_reassessment_at. Invalid status values return 400.

Link Products

POST /api/v1.0/catalog/spaces/{space_slug}/risk-register/{entry_id}/link-products

{
  "product_ids": [
    "00000000-0000-0000-0000-000000000000",
    "11111111-1111-1111-1111-111111111111"
  ]
}

Existing links are not duplicated.

Unlink Product

DELETE /api/v1.0/catalog/spaces/{space_slug}/risk-register/{entry_id}/products/{product_id}

The response returns the updated entry. If the link does not exist, the API returns 404.

Response Fields

Field	Description
id, space_id	Risk identity and scope.
title, description, category	Risk description.
severity, likelihood, impact, risk_score, risk_tier	Scoring fields and derived tier.
status	Lifecycle status.
residual_risk_level, residual_justification	Accepted-risk context.
misuse_scenarios, mitigations	Structured risk controls.
risk_owner_id, reassessment_cadence, next_reassessment_at	Ownership and review cadence.
created_by_id, created_at, updated_at	Audit metadata.
product_ids	Linked product IDs.

Error Responses

Status	Description
400	Invalid status or payload validation failure.
401	Authentication required for create.
404	Risk entry or product link not found.