​
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:

  1. Bearer token in the Authorization header:
Authorization: Bearer your_api_key
  1. 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

ParameterTypeDescription
statusstringFilter by risk status. Possible values: open, pending, closed, archived
categorystringFilter by risk category (e.g., technology, operations, regulatory, etc.)
departmentstringFilter by department. Possible values: none, admin, gov, hr, it, itsm, qms
searchstringSearch 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": "[email protected]"
        }
      }
    }
    // 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

FieldTypeDescriptionRequired
titlestringThe title of the riskYes
descriptionstringA detailed description of the riskYes
categorystringThe risk category (e.g., technology, operations, regulatory, etc.)Yes
departmentstringThe department associated with the riskNo
statusstringThe risk status. Default: openNo
probabilitynumberThe initial probability score (0-10). Default: 0No
impactnumberThe initial impact score (0-10). Default: 0No
residual_probabilitynumberThe residual probability score after mitigation (0-10). Default: 0No
residual_impactnumberThe residual impact score after mitigation (0-10). Default: 0No
assigneeIdstringThe ID of the user who owns the riskNo

​
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

ParameterTypeDescription
idstringThe 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": "[email protected]"
      }
    },
    "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

ParameterTypeDescription
idstringThe 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"
}