Risks

The Risks endpoints expose your organization’s risk register: every formally tracked risk, its current treatment decision, and the methodology context behind it.

This is a read-only surface in v1. Creating, updating, and closing risks happens in the Novantra UI (see the Risks user guide).

For shared conventions (auth, errors, pagination, ID format), read v1 conventions first.

Scope required

Endpoints

List risks

GET /api/v1/governance/risks
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "risks": [
    {
      "id": "risk_01HXY...",
      "riskKey": "vendor-cloud-availability",
      "title": "Cloud provider availability disruption affecting trading platform",
      "description": "Sustained outage of the primary cloud provider disrupts order execution capacity.",
      "status": "under-treatment",
      "subjectModuleKey": "party-engagements",
      "subjectResourceType": "engagement",
      "subjectResourceId": "peng_01HXY...",
      "subjectVersionId": null,
      "ownerResponsibilityAssignmentId": "ra_01HXY...",
      "createdAt": "2026-04-15T08:21:43.000Z",
      "updatedAt": "2026-05-25T14:08:33.000Z"
    },
    {
      "id": "risk_01HXZ...",
      "riskKey": "regulatory-record-keeping-gap",
      "title": "Trading record retention falls below required period",
      "description": "Trade reconstruction records are deleted before the required retention period.",
      "status": "accepted",
      "subjectModuleKey": null,
      "subjectResourceType": null,
      "subjectResourceId": null,
      "subjectVersionId": null,
      "ownerResponsibilityAssignmentId": "ra_01HXZ...",
      "createdAt": "2026-04-18T11:04:21.000Z",
      "updatedAt": "2026-05-10T09:42:17.000Z"
    }
  ],
  "pagination": {}
}

Get one risk

GET /api/v1/governance/risks/:riskId
Authorization: Bearer <access-token>

Path parameters:

Response: the single-risk shape from the list above.

Field notes

subjectModuleKey, subjectResourceType, subjectResourceId, subjectVersionId

When a risk is anchored to a specific governed object (a particular asset, a particular service, a particular party engagement), these fields identify it. For portfolio-level risks (the common case), all four are null. See Attaching records to governed subjects.

ownerResponsibilityAssignmentId

Points at the responsibility assignment naming the accountable risk owner. The responsibility record itself is not a v1 endpoint; the in-product UI shows the owner name and role.

Methodology and treatment snapshots

In the in-product UI, each risk carries a methodology snapshot (taxonomy, scoring inputs, assumptions) and a treatment snapshot (treatment decision, rationale, approver, expiry). In v1 these snapshot fields are not exposed in the API surface; reads return the durable risk record. The detailed history (assessments, acceptances, treatments) is available through the in-product UI.

Real-case integration: feeding the risk register into a board dashboard

A finance team produces a quarterly board pack including the enterprise risk view: current open risks, residual ratings, treatment status, owner. Their BI team writes an integration that walks the Risks endpoints, joins against owners and business lines, and renders the board pack automatically.

The integration:

1. Calls GET /api/v1/governance/risks to pull the full register, paginating with cursors.
2. Filters in-warehouse for status of interest (typically anything that isn’t closed).
3. Joins owner IDs against the workspace’s responsibility-assignment list (also exposed in-product), which the BI team caches separately on a monthly cadence.
4. Renders the board view: count by status, count by treatment, top risks by recency of last update, overdue review counts.

The service account holds exactly governance.risks:read. The integration pulls weekly (not daily), since boards see this view quarterly and weekly freshness is generous. Cursor pagination handles even very large registers cleanly.

For a real-time dashboard view, the integration polls more frequently against the same endpoint, but the natural pattern for board reporting is batch.

Related

• Risks user guide - what the risks module does and when to reach for it.
• v1 conventions - shared request and response patterns.
• Authentication - service accounts and scopes.