Risks

The Risks endpoints allow you to list risks, create new risks, retrieve individual risks, and delete existing risks. Risks represent potential threats to your organization that need to be tracked, assessed, and mitigated.

Authentication

All endpoints require authentication using an API key. You can provide the API key in one of two ways:

Bearer token in the Authorization header:

Authorization: Bearer your_api_key

Using the X-API-Key header:

X-API-Key: your_api_key

Endpoints

GET /api/v1/risks - List all risks with optional filtering
POST /api/v1/risks - Create a new risk
GET /api/v1/risks/:id - Get a risk by ID
DELETE /api/v1/risks/:id - Delete a risk by ID

List Risks

GET /api/v1/risks

Get all risks for the organization associated with the API key.

Query Parameters

Parameter	Type	Description
status	string	Filter by risk status. Possible values: `open`, `pending`, `closed`, `archived`
category	string	Filter by risk category (e.g., `technology`, `operations`, `regulatory`, etc.)
department	string	Filter by department. Possible values: `none`, `admin`, `gov`, `hr`, `it`, `itsm`, `qms`
search	string	Search by title or description

Response

{
  "success": true,
  "data": [
    {
      "id": "clc123abc456",
      "title": "Server vulnerability",
      "description": "Outdated software on production servers",
      "category": "technology",
      "department": "it",
      "status": "open",
      "probability": 7,
      "impact": 8,
      "residual_probability": 3,
      "residual_impact": 5,
      "createdAt": "2023-01-15T12:00:00.000Z",
      "updatedAt": "2023-01-16T09:30:00.000Z",
      "assigneeId": "u123abc456",
      "assignee": {
        "id": "u123abc456",
        "user": {
          "name": "John Doe",
          "email": "john.doe@example.com"
        }
      }
    }
    // More risks...
  ]
}

Error Responses

Invalid API key (401):

{
  "success": false,
  "error": "Invalid or missing API key"
}

Validation Error (400):

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "status": {
      "_errors": [
        "Invalid enum value. Expected 'open' | 'pending' | 'closed' | 'archived'"
      ]
    }
  }
}

Internal Error (500):

{
  "success": false,
  "error": "Failed to fetch risks"
}

Create Risk

POST /api/v1/risks

Create a new risk for the organization associated with the API key.

Request Body

Field	Type	Description	Required
title	string	The title of the risk	Yes
description	string	A detailed description of the risk	Yes
category	string	The risk category (e.g., `technology`, `operations`, `regulatory`, etc.)	Yes
department	string	The department associated with the risk	No
status	string	The risk status. Default: `open`	No
probability	number	The initial probability score (0-10). Default: 0	No
impact	number	The initial impact score (0-10). Default: 0	No
residual_probability	number	The residual probability score after mitigation (0-10). Default: 0	No
residual_impact	number	The residual impact score after mitigation (0-10). Default: 0	No
assigneeId	string	The ID of the user who owns the risk	No

Example Request

{
  "title": "Server vulnerability",
  "description": "Outdated software on production servers",
  "category": "technology",
  "department": "it",
  "probability": 7,
  "impact": 8
}

Response

{
  "success": true,
  "data": {
    "id": "clc123abc456",
    "title": "Server vulnerability",
    "description": "Outdated software on production servers",
    "category": "technology",
    "department": "it",
    "status": "open",
    "probability": 7,
    "impact": 8,
    "residual_probability": 0,
    "residual_impact": 0,
    "createdAt": "2023-01-15T12:00:00.000Z",
    "updatedAt": "2023-01-15T12:00:00.000Z",
    "assigneeId": null,
    "organizationId": "org123abc456"
  }
}

Error Responses

Invalid API key (401):

{
  "success": false,
  "error": "Invalid or missing API key"
}

Validation Error (400):

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "title": {
      "_errors": ["Title is required"]
    },
    "category": {
      "_errors": ["Invalid enum value"]
    }
  }
}

Internal Error (500):

{
  "success": false,
  "error": "Failed to create risk"
}

Get Risk

GET /api/v1/risks/:id

Get a single risk by ID for the organization associated with the API key.

Path Parameters

Parameter	Type	Description
id	string	The ID of the risk to get

Response

{
  "success": true,
  "data": {
    "id": "clc123abc456",
    "title": "Server vulnerability",
    "description": "Outdated software on production servers",
    "category": "technology",
    "department": "it",
    "status": "open",
    "probability": 7,
    "impact": 8,
    "residual_probability": 3,
    "residual_impact": 5,
    "createdAt": "2023-01-15T12:00:00.000Z",
    "updatedAt": "2023-01-16T09:30:00.000Z",
    "assigneeId": "u123abc456",
    "assignee": {
      "id": "u123abc456",
      "user": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    },
    "treatmentStrategy": {
      "id": "trt123abc456",
      "type": "mitigate",
      "description": "Update software and implement regular updates",
      "createdAt": "2023-01-15T14:00:00.000Z",
      "updatedAt": "2023-01-15T14:00:00.000Z"
    },
    "mitigationTasks": [
      {
        "id": "tsk123abc456",
        "title": "Update server software",
        "description": "Update all production servers to the latest stable version",
        "status": "open",
        "dueDate": "2023-02-15T00:00:00.000Z",
        "completedAt": null,
        "createdAt": "2023-01-15T14:10:00.000Z",
        "updatedAt": "2023-01-15T14:10:00.000Z",
        "assigneeId": "u123abc456"
      },
      {
        "id": "tsk789xyz123",
        "title": "Implement automatic updates",
        "description": "Set up automatic security updates for all servers",
        "status": "open",
        "dueDate": "2023-03-01T00:00:00.000Z",
        "completedAt": null,
        "createdAt": "2023-01-15T14:15:00.000Z",
        "updatedAt": "2023-01-15T14:15:00.000Z",
        "assigneeId": "u123abc456"
      }
    ]
  }
}

Error Responses

Invalid API key (401):

{
  "success": false,
  "error": "Invalid or missing API key"
}

Risk Not Found (404):

{
  "success": false,
  "error": "Risk not found"
}

Internal Error (500):

{
  "success": false,
  "error": "Failed to fetch risk"
}

Delete Risk

DELETE /api/v1/risks/:id

Delete a risk by ID for the organization associated with the API key.

Path Parameters

Parameter	Type	Description
id	string	The ID of the risk to delete

Response

{
  "success": true,
  "data": {
    "message": "Risk deleted successfully"
  }
}

Error Responses

Invalid API key (401):

{
  "success": false,
  "error": "Invalid or missing API key"
}

Risk Not Found (404):

{
  "success": false,
  "error": "Risk not found"
}

Internal Error (500):

{
  "success": false,
  "error": "Failed to delete risk"
}

API Reference

​Risks

​Authentication

​Endpoints

​List Risks

​Query Parameters

​Response

​Error Responses

​Create Risk

​Request Body

​Example Request

​Response

​Error Responses

​Get Risk

​Path Parameters

​Response

​Error Responses

​Delete Risk

​Path Parameters

​Response

​Error Responses

Risks

Authentication

Endpoints

List Risks

Query Parameters

Response

Error Responses

Create Risk

Request Body

Example Request

Response

Error Responses

Get Risk

Path Parameters

Response

Error Responses

Delete Risk

Path Parameters

Response

Error Responses