Risk Register API

Full risk lifecycle management with FAIR (Factor Analysis of Information Risk) quantification. Create risks, run Monte Carlo simulations, manage mitigations, and generate board-ready reports. All endpoints require JWT authentication.

Risk CRUD

POST /api/v1/risk-register 🔒

Create a new risk entry.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Risk title
`description`	string	No	Detailed description
`category`	string	Yes	`operational`, `technical`, `compliance`, `financial`, `reputational`, `third-party`
`owner_email`	string	No	Risk owner email
`likelihood`	integer	No	1–5 scale
`impact`	integer	No	1–5 scale
`scenario_id`	string	No	Pre-built FAIR scenario ID

curl -X POST https://api.privabase.com/api/v1/risk-register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Data breach via third-party vendor",
    "description": "Vendor with access to PII suffers a breach",
    "category": "third-party",
    "likelihood": 3,
    "impact": 5,
    "owner_email": "ciso@company.com"
  }'

// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/risk-register', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Data breach via third-party vendor',
    category: 'third-party',
    likelihood: 3,
    impact: 5
  })
});

# Python
resp = requests.post('https://api.privabase.com/api/v1/risk-register',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'title': 'Data breach via third-party vendor',
        'category': 'third-party',
        'likelihood': 3,
        'impact': 5
    })

Response `201`

{
  "success": true,
  "data": {
    "id": "risk-abc-123",
    "title": "Data breach via third-party vendor",
    "category": "third-party",
    "status": "identified",
    "likelihood": 3,
    "impact": 5,
    "severity": "critical",
    "created_at": "2026-03-14T10:30:00Z"
  }
}

GET /api/v1/risk-register 🔒

List all risks with optional filters.

Query Parameters

Param	Type	Description
`status`	string	`identified`, `assessed`, `mitigating`, `accepted`, `closed`
`category`	string	Risk category filter
`owner`	string	Filter by owner email
`severity`	string	`critical`, `high`, `medium`, `low`

curl "https://api.privabase.com/api/v1/risk-register?severity=critical&status=identified" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/v1/risk-register/:id 🔒

Get risk detail with FAIR analysis results, mitigations, and history.

curl https://api.privabase.com/api/v1/risk-register/risk-abc-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

PUT /api/v1/risk-register/:id 🔒

Update a risk's properties (title, description, category, status, likelihood, impact, owner).

DELETE /api/v1/risk-register/:id 🔒

Archive (soft-delete) a risk.

FAIR Assessment

POST /api/v1/risk-register/:id/assess 🔒

Run FAIR quantification on a risk. Performs Monte Carlo simulation with PERT distributions. Returns annualized loss expectancy (ALE) percentiles and loss exceedance curve.

Request Body

Field	Type	Description
`tef_min`	number	Threat Event Frequency minimum (events/year)
`tef_likely`	number	TEF most likely value
`tef_max`	number	TEF maximum
`vulnerability`	number	Probability of loss given event (0–1)
`primary_loss_min`	number	Primary loss minimum ($)
`primary_loss_likely`	number	Primary loss most likely ($)
`primary_loss_max`	number	Primary loss maximum ($)
`secondary_loss_min`	number	Secondary loss minimum ($)
`secondary_loss_likely`	number	Secondary loss most likely ($)
`secondary_loss_max`	number	Secondary loss maximum ($)
`scenario_id`	string	Use a pre-built scenario's defaults

curl -X POST https://api.privabase.com/api/v1/risk-register/risk-abc-123/assess \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tef_min": 0.5,
    "tef_likely": 1,
    "tef_max": 3,
    "vulnerability": 0.6,
    "primary_loss_min": 50000,
    "primary_loss_likely": 250000,
    "primary_loss_max": 1000000
  }'

// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/risk-register/risk-abc-123/assess', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tef_min: 0.5, tef_likely: 1, tef_max: 3,
    vulnerability: 0.6,
    primary_loss_min: 50000, primary_loss_likely: 250000, primary_loss_max: 1000000
  })
});

# Python
resp = requests.post(
    'https://api.privabase.com/api/v1/risk-register/risk-abc-123/assess',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'tef_min': 0.5, 'tef_likely': 1, 'tef_max': 3,
        'vulnerability': 0.6,
        'primary_loss_min': 50000, 'primary_loss_likely': 250000, 'primary_loss_max': 1000000
    })

Response

{
  "success": true,
  "data": {
    "assessment": {
      "id": "assess-001",
      "risk_id": "risk-abc-123",
      "created_at": "2026-03-14T10:30:00Z"
    },
    "fairOutput": {
      "aleP10": 42000,
      "aleP50": 175000,
      "aleP90": 520000,
      "lossExceedanceCurve": [
        { "threshold": 100000, "probability": 0.72 },
        { "threshold": 250000, "probability": 0.45 },
        { "threshold": 500000, "probability": 0.12 },
        { "threshold": 1000000, "probability": 0.03 }
      ]
    }
  }
}

Mitigations

POST /api/v1/risk-register/:id/mitigate 🔒

Add a mitigation plan to a risk.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Mitigation title
`description`	string	No	Details of the mitigation plan
`owner_email`	string	No	Person responsible
`due_date`	string	No	Target completion date (YYYY-MM-DD)

curl -X POST https://api.privabase.com/api/v1/risk-register/risk-abc-123/mitigate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement vendor security questionnaire",
    "description": "Require all vendors with PII access to complete annual security assessment",
    "owner_email": "security@company.com",
    "due_date": "2026-06-01"
  }'

PUT /api/v1/risk-register/:id/mitigate/:mid 🔒

Update mitigation status and progress.

Request Body

Field	Type	Description
`status`	string	`planned`, `in-progress`, `completed`, `overdue`
`completion_pct`	integer	0–100 percent complete

Dashboard & Reports

GET /api/v1/risk-register/dashboard 🔒

Risk overview dashboard — heatmap data, severity counts, top risks, total ALE exposure, and breakdowns by status/category.

curl https://api.privabase.com/api/v1/risk-register/dashboard \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "heatmap": [[0,1,0,0,0],[0,0,2,1,0],[0,1,0,1,0],[0,0,0,0,1],[0,0,0,0,0]],
    "counts": { "critical": 2, "high": 3, "medium": 4, "low": 1 },
    "totalALE": 1250000,
    "topRisks": [...]
  }
}

GET /api/v1/risk-register/report 🔒

Generate a board-ready risk report suitable for auditor or board presentation.

curl https://api.privabase.com/api/v1/risk-register/report \
  -H "Authorization: Bearer YOUR_TOKEN"

Scenarios & Auto-Identify

GET /api/v1/risk-register/scenarios 🔒

List pre-built FAIR risk scenarios with default parameters. Use scenario_id when creating or assessing risks to auto-fill FAIR inputs.

curl https://api.privabase.com/api/v1/risk-register/scenarios \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/v1/risk-register/auto-identify 🔒

AI-powered risk identification. Analyzes compliance gaps, failed controls, and vendor risk to suggest new risks with pre-filled FAIR parameters.

curl -X POST https://api.privabase.com/api/v1/risk-register/auto-identify \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "title": "Unencrypted data at rest in AWS S3",
      "description": "3 S3 buckets found without server-side encryption",
      "category": "technical",
      "likelihood": 3,
      "impact": 4,
      "fairParams": {
        "tef_min": 0.5, "tef_likely": 1.5, "tef_max": 4,
        "vulnerability": 0.7,
        "primary_loss_likely": 500000
      },
      "rationale": "Based on failing control soc2-cc6.1 from AWS integration"
    }
  ]
}

Risk Register API

Risk CRUD

Request Body

Response 201

Query Parameters

FAIR Assessment

Request Body

Response

Mitigations

Request Body

Request Body

Dashboard & Reports

Response

Scenarios & Auto-Identify

Response

Response `201`