Risks

import { Aside } from ‘@astrojs/starlight/components’;

Risks require the `risks` module to be enabled for the organization.

List risks (organization)

GET /v1/organizations/:orgId/risks

Required role: Member.

Returns a paginated list of risks across all products in the organization. Materialized risks include the linked issue’s ID and number.

Query parameters:

Parameter	Type	Description
page	integer	Page number (default: 1).
pageSize	integer	Results per page (default: 25, max: 100).
status	"identified" | "mitigated" | "materialized" | "aged_out"	Filter by status.
likelihood	"high" | "medium" | "low"	Filter by likelihood.
impact	"high" | "medium" | "low"	Filter by impact.
productId	string	Filter to a specific product.
sortField	string	Field to sort by (e.g. "createdAt", "likelihood", "status").
sortDirection	"asc" | "desc"	Sort direction (default: "desc").

---

Risk insights (organization)

GET /v1/organizations/:orgId/risks/insights

Required role: Member.

Returns aggregated breakdowns by status, likelihood, impact, and product.

---

List risks (product)

GET /v1/organizations/:orgId/products/:productSlug/risks

Required role: Member.

Accepts the same query parameters as the organization-level list, excluding productId.

---

Create a risk

POST /v1/organizations/:orgId/products/:productSlug/risks

Required role: Member.

Cannot create a risk in an archived product — returns 409 Conflict.

Request body:

Field	Type	Required	Description
title	string	Yes	Risk title (max 200 characters).
description	string | null	No	Full description (max 2000 characters).
likelihood	"high" | "medium" | "low" | null	No	Likelihood of the risk materializing.
impact	"high" | "medium" | "low" | null	No	Potential impact if it materializes.
mitigation	string | null	No	Steps being taken to prevent materialization.
status	"identified" | "mitigated" | "aged_out"	No	Initial status (default: "identified"). Note: "materialized" cannot be set directly.
areaIds	string[]	No	IDs of areas to tag.

Risk numbers are sequential per product, assigned atomically. Returns 201 Created with a Location header.

---

Get a risk

GET /v1/organizations/:orgId/products/:productSlug/risks/:riskNumber

Required role: Member.

:riskNumber is the sequential integer risk number. The response includes an areas array and, for materialized risks, the linked issue’s ID and number.

---

Update a risk

PATCH /v1/organizations/:orgId/products/:productSlug/risks/:riskNumber

Required role: Member.

Request body (all fields optional):

Field	Type	Description
title	string
description	string | null
likelihood	"high" | "medium" | "low" | null
impact	"high" | "medium" | "low" | null
mitigation	string | null
status	"identified" | "mitigated" | "aged_out"	Cannot set "materialized" directly — use the materialize endpoint.
areaIds	string[]	Replaces the full set of area associations.

---

Delete a risk

DELETE /v1/organizations/:orgId/products/:productSlug/risks/:riskNumber

Required role: Admin or owner.

Returns 204 No Content.

---

Materialize a risk into an issue

POST /v1/organizations/:orgId/products/:productSlug/risks/:riskNumber/materialize

Required role: Member.

Atomically creates an issue from the risk’s title, description, and impact, then links the two together and sets the risk’s status to "materialized".

This operation is idempotent: calling it on a risk that has already been materialized returns the existing linked issue rather than creating a duplicate.

Response:

{
  "issue": {
    "id": "...",
    "number": 7,
    ...
  }
}

---

Bulk update risks

PATCH /v1/organizations/:orgId/risks/bulk

Required role: Member.

Request body:

Field	Type	Description
ids	string[]	Risk IDs to update (max 100).
data.status	"identified" | "mitigated" | "aged_out"	Optional.
data.likelihood	"high" | "medium" | "low" | null	Optional.
data.impact	"high" | "medium" | "low" | null	Optional.

---

Bulk delete risks

DELETE /v1/organizations/:orgId/risks/bulk

Required role: Admin or owner.

Request body:

Field	Type	Description
ids	string[]	Risk IDs to delete (max 100).