Risks

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

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, a functionalNeeds 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,
    ...
  }
}

List functional needs for a risk

GET /v1/organizations/:orgId/products/:productSlug/risks/:riskNumber/functional-needs

Required role: Member.

Returns the functional needs linked to the risk.

Response:

{
  "functionalNeeds": [
    { "id": "...", "slug": "without-vision", "name": "Without vision", "url": "..." }
  ]
}

Replace functional needs for a risk

PUT /v1/organizations/:orgId/products/:productSlug/risks/:riskNumber/functional-needs

Required role: Member.

Replaces the full set of functional need links for the risk. Send an empty array to remove all links. Returns the updated functionalNeeds array.

Request body:

Field	Type	Description
`functionalNeedIds`	`string[]`	IDs of functional needs to link (max 50). Unknown IDs return `400 Bad Request`.

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).