Risk Assessments API

Product-scoped risk assessments with multi-category scoring, mitigation tracking, and optional sync to product classification.

All endpoints are scoped under /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments and require authentication.

Endpoints Overview

Method	Endpoint	Description
POST	.../risk-assessments	Create assessment
GET	.../risk-assessments	List assessments
GET	.../risk-assessments/{id}	Get assessment
PUT	.../risk-assessments/{id}	Update assessment
POST	.../risk-assessments/{id}/complete	Complete assessment
PATCH	.../risk-assessments/{id}/mitigations/{mid}	Update mitigation

---

Create Assessment

POST /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments

Request Body

{
  "assessment_type": "initial",
  "lifecycle_stage": "development",
  "evaluations": [
    {
      "category": "bias",
      "severity": 3,
      "likelihood": 2,
      "impact": 4,
      "notes": "Potential demographic bias in training data"
    },
    {
      "category": "privacy",
      "severity": 4,
      "likelihood": 3,
      "impact": 5,
      "notes": "PII in feature pipeline"
    }
  ],
  "summary": "Initial risk assessment for customer scoring model",
  "mitigations": [
    {
      "title": "Implement fairness metrics",
      "category": "bias_mitigation",
      "owner_name": "Alice",
      "deadline": "2026-03-15",
      "priority": "high"
    }
  ]
}

Fields

Field	Type	Required	Description
assessment_type	string	✅	initial, pre_deployment, periodic, incident
lifecycle_stage	string	—	Stage at time of assessment
evaluations	RiskEvaluation[]	—	Category-level risk scores
summary	string	—	Assessment summary
mitigations	MitigationAction[]	—	Planned mitigation actions

RiskEvaluation

Field	Type	Range	Description
category	string	—	bias, fairness, robustness, privacy, security, explainability
severity	integer	1–5	Severity score
likelihood	integer	1–5	Likelihood score
impact	integer	1–5	Impact score
score	integer	—	Auto-computed: severity × likelihood × impact
notes	string	—	Free-form notes

---

List Assessments

GET /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Max items (1–100)
offset	integer	0	Pagination offset

---

Get Assessment

GET /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments/{assessment_id}

---

Update Assessment

PUT /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments/{assessment_id}

All fields are optional. Cannot update a completed assessment.

---

Complete Assessment

POST /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments/{assessment_id}/complete

Marks the assessment as completed and computes the final risk tier.

Request Body

{
  "risk_tier": "high",
  "sync_to_product": true
}

Field	Type	Default	Description
risk_tier	string	auto-derived	Override: unacceptable, high, limited, minimal
sync_to_product	bool	false	Update the product's risk_classification

Risk Tier Thresholds (Auto-Derived)

Tier	Score Range
unacceptable	≥ 80
high	≥ 50
limited	≥ 25
minimal	< 25

Overall score = average of (severity × likelihood × impact) across categories, normalised to 0–100.

---

Update Mitigation

PATCH /catalog/spaces/{space_slug}/products/{product_id}/risk-assessments/{assessment_id}/mitigations/{mitigation_id}

Update a single mitigation action within an assessment.

Request Body

{
  "status": "in_progress",
  "evidence": ["https://jira.example.com/PROJ-123"],
  "linked_issue_id": "uuid"
}

Field	Type	Description
status	string	pending, in_progress, completed, cancelled
evidence	string[]	References (links, issue IDs)
linked_issue_id	UUID	Link to platform issue/ticket
owner_id	UUID	Reassign owner
owner_name	string	Updated owner display name
deadline	string	ISO 8601 date
priority	string	low, medium, high, critical

---

Response Model

RiskAssessmentResponse

Field	Type	Description
id	UUID	Assessment identifier
product_id	UUID	Assessed product
space_id	UUID	Space scope
assessment_type	string	Type of assessment
lifecycle_stage	string | null	Lifecycle stage
status	string	draft, completed
evaluations	object[]	Category evaluations
overall_risk_score	integer | null	Computed 0–100 score
risk_tier	string | null	Derived or overridden tier
summary	string | null	Summary text
mitigations	object[] | null	Mitigation actions
assessed_by_id	UUID	User who created the assessment
assessed_at	datetime	Assessment timestamp
reviewed_by_id	UUID | null	Reviewer (if reviewed)
reviewed_at	datetime | null	Review timestamp
created_at	datetime	Creation timestamp
updated_at	datetime	Last update

MitigationAction

Field	Type	Description
id	string	Auto-generated UUID
title	string	Action description
category	string	bias_mitigation, retraining, robustness_testing, privacy_enhancement, explainability, monitoring_improvement, process_change, other
status	string	pending, in_progress, completed, cancelled
priority	string	low, medium, high, critical
owner_id	UUID	Responsible user
owner_name	string	Display name
deadline	string	Target date
evidence	string[]	Evidence references
linked_issue_id	UUID	Linked platform issue