Getting started

[!WARNING] The Classic XDR Cases REST API is deprecated

Don't use this API for new integrations. Existing integrations can continue to use the examples below. We will make this API read-only at a later time and remove it after that.

Use the Cases GraphQL API guide for new integrations. Follow the Cases REST to GraphQL migration guide to plan your migration. See the Fusion XDR GraphQL APIs and Classic XDR API deprecation announcement for more information.

Overview¶

Welcome to the Cases API documentation. This guide will help you understand how to effectively use the Cases API to get cases and their associated data. By the end of this guide, you will be able to do as follows:

This page documents the Cases REST API. For case workflows over GraphQL, see the Cases GraphQL API guide. For case creation, status transitions, and evidence in GraphQL, see Manage the case lifecycle.

Get cases from the API.
Get related information such as impacted entities.
Get MITRE ATT&CK summaries.
Get detection details.

Pre-requisites¶

You must have a set of API credentials (service principal) to be able to call the Cases API. For more information refer to the appropriate quick start guide:

Sophos Partners: Read Partner Getting Started Guide.
Enterprise customers: If you use Sophos Enterprise to manage multiple tenants, read the Organization Getting Started Guide.
Other customers: Read Tenant Getting Started Guide.

Making API requests¶

You can make the API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

When using curl, a request to the Cases API has the following general form:

curl -X <method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

<method>: The request method. For the Cases API, this is GET.
<jwt>: The JWT access token returned when the IDP authenticates the service principal.
<tenant-id>: The ID of the tenant you want to query.
<data-region>: The regional API host in the data geography where the tenant data is located.
<path>: The request path for the API operation, for example cases/{caseId}/mitre-attack-summary.

The API descriptions in this guide only specify the request method and path. For example:

GET cases/v1/cases

All API requests return HTTP status codes 200 or 201 when successful.

Case operations¶

Get cases¶

To get all cases for a tenant, call:

GET cases/v1/cases

Response: This returns a paginated list of cases.

{
    "items": [
      {
        "id": "3-189694",
        "type": "investigation",
        "name": "WIN-PROT-REP-MALWARE-MAL-GENERIC-S",
        "tenant": {
          "id": "c6a7b1a3-ca72-4d6e-b941-7927ed12b8da"
        },
        "managedBy": "self",
        "createdAt": "2024-06-22T20:08:14.138Z",
        "createdBy": {
          "name": "example@example.com"
        },
        "updatedAt": "2024-06-22T20:08:17.17Z",
        "severity": "informational",
        "status": "new",
        "initialDetection": {
          "id": "fe3bebb0f25a39ac39cfea4d1f648e957039df5b8ceb1cd5450d7e95ba9c10ed_e8b5dd542d5f434c2fa0c68c5c1c1260bb692a89",
          "severity": 5,
          "type": "Threat",
          "detectionRule": "WIN-PROT-REP-MALWARE-MAL-GENERIC-S",
          "time": "2024-06-13T13:41:55+00:00",
          "sensor": {
            "type": "endpoint",
            "source": "Sophos"
          }
        },
        "assignee": {
          "name": "Unassigned"
        },
        "overview": "Case created automatically on Mal/Generic detection.",
        "detectionCount": 20
      }
    ],
    "pages": {
        "current": 1,
        "size": 50,
        "total": 1,
        "items": 1,
        "maxSize": 100
    }
}

Get Case by ID¶

To get a case by ID, call:

GET cases/v1/cases/{caseId}

Response: This returns a single case.

{
  "id": "3-189694",
  "type": "investigation",
  "name": "WIN-PROT-REP-MALWARE-MAL-GENERIC-S",
  "tenant": {
    "id": "c6a7b1a3-ca72-4d6e-b941-7927ed12b8da"
  },
  "managedBy": "self",
  "createdAt": "2024-06-22T20:08:14.138Z",
  "createdBy": {
    "name": "example@example.com"
  },
  "updatedAt": "2024-06-22T20:08:17.17Z",
  "severity": "informational",
  "status": "new",
  "initialDetection": {
    "id": "fe3bebb0f25a39ac39cfea4d1f648e957039df5b8ceb1cd5450d7e95ba9c10ed_e8b5dd542d5f434c2fa0c68c5c1c1260bb692a89",
    "severity": 5,
    "type": "Threat",
    "detectionRule": "WIN-PROT-REP-MALWARE-MAL-GENERIC-S",
    "time": "2024-06-13T13:41:55+00:00",
    "sensor": {
      "type": "endpoint",
      "source": "Sophos"
    }
  },
  "assignee": {
    "name": "Unassigned"
  },
  "overview": "Case created automatically on Mal/Generic detection.",
  "detectionCount": 20
}

Get impacted entities for case¶

To get impacted entities for a case, call:

GET cases/v1/cases/{caseId}/impacted-entities

Response:

{
    "items": [
        {
            "id": "16978286-72a7-4bfc-8df4-47e61f23a7b0",
            "name": "EC2AMAZ-V9NNFDA",
            "type": "device",
            "detections": [
                {
                    "id": "001b62655da7acdbcd11766bc114ae02312f50ba7366d1d0479b45df8df3836d_d2cb66db5f30f3b925d2465bdde480ac29e4522e",
                    "detectionRule": "WIN-CRD-PRC-COMSVCS-MINIDUMP-1"
                }
            ],
            "entityAttributes": {
                "id": "16978286-72a7-4bfc-8df4-47e61f23a7b0",
                "os_type": "",
                "hostname": "EC2AMAZ-V9NNFDA",
                "os_platform": "windows",
                "endpoint_type": "server",
                "domain_controller": "False"
            }
        },
        {
            "id": "193dbe6b-3ac3-41ac-8afe-b6fa4448b0b0",
            "name": "EC2AMAZ-V9NNFDA",
            "type": "device",
            "detections": [
                {
                    "id": "001b62655da7acdbcd11766bc114ae02312f50ba7366d1d0479b45df8df3836d_d2cb66db5f30f3b925d2465bdde480ac29e4522e",
                    "detectionRule": "WIN-CRD-PRC-COMSVCS-MINIDUMP-1"
                }
            ],
            "entityAttributes": {
                "id": "193dbe6b-3ac3-41ac-8afe-b6fa4448b0b0",
                "os_type": "",
                "hostname": "EC2AMAZ-V9NNFDA",
                "os_platform": "windows",
                "endpoint_type": "server",
                "domain_controller": "False"
            }
        }
    ],
    "pages": {
        "current": 1,
        "total": 1,
        "size": 10,
        "items": 2,
        "maxSize": 10
    }
}

Get MITRE ATT&CK summary¶

To get MITRE ATT&CK summary for a case, call:

GET cases/v1/cases/{caseId}/mitre-attack-summary

Response:

{
    "tactics": [
        {
            "id": "TA0002",
            "name": "Execution",
            "techniques": [
                {
                    "id": "T1059",
                    "name": "Command and Scripting Interpreter"
                },
                {
                    "id": "T1059.001",
                    "name": "PowerShell"
                }
            ]
        },
        {
            "id": "TA0003",
            "name": "Persistence",
            "techniques": [
                {
                    "id": "T1078.002",
                    "name": "Domain Accounts"
                },
                {
                    "id": "T1078.003",
                    "name": "Local Accounts"
                }
            ]
        }
    ]
}

Get case detections¶

To get detections associated with a case, call:

GET cases/v1/cases/{caseId}/detections

Response: This returns a paginated list of detections associated with the case.

{
    "items": [
        {
            "id": "f05201769d90d627a04acca728dfa9f1efa1f91314cbf0eac89c4ac26bed7547_b5955e0613e159f319d4677231d8edde8b246533",
            "detectionRule": "WIN-PROT-VDL-MALWARE-ATK-ATOMICRED-A",
            "sensorGeneratedAt": "2023-09-26T10:05:36Z",
            "sensor": {
                "type": "endpoint",
                "source": "Sophos Endpoint"
            },
            "mitreAttacks": [],
            "severity": 8,
            "type": "Threat"
        },
        {
            "id": "d613562436aca131a1256a5140af0e3f453033f138376f0e666e960b5b43a64d_479268edab187f67554eb81f4e6277dc2a98748a",
            "detectionRule": "WIN-PROT-VDL-MALWARE-ATK-ATOMICRED-A",
            "sensorGeneratedAt": "2023-09-26T10:05:36Z",
            "sensor": {
                "type": "endpoint",
                "source": "Sophos Endpoint"
            },
            "mitreAttacks": [],
            "severity": 8,
            "type": "Threat"
        }
    ],
    "pages": {
        "current": 1,
        "total": 1,
        "size": 10,
        "items": 2,
        "maxSize": 10
    }
}

Note: See the Limitations section for known issues with this API.

Get case detection by ID¶

To get case detection by ID, call:

GET cases/v1/cases/{caseId}/detections/{detectionId}

Response: A single detection associated with the case.

{
    "id": "62b07f95c260892152398f07bef0b8382e11d4c95b01c4603b6ff08a2920cefa_a1160288b9482d90a9d3fa1096c6130bc9e3f480",
    "detectionRule": "WIN-PROT-VDL-MALWARE-ATK-ATOMICRED-A",
    "sensorGeneratedAt": "2023-09-26T16:18:57Z",
    "sensor": {
        "type": "endpoint",
        "source": "Sophos Endpoint"
    },
    "mitreAttacks": [],
    "severity": 8,
    "type": "Threat"
}

Create a case¶

Cases can be self-managed or managed by Sophos. Only self-managed cases can be created using this API at this time.

Rate limiting policy¶

To ensure fair usage and maintain system performance, this API enforces the following soft rate limits:

Tenant-level limit:

Each tenant is allowed up to 100 requests per 24-hour period.

User-level limit:

Each individual user can make up to 10 requests per minute.

To create a new self-managed case, call:

POST cases/v1/cases

Request body:

{
  "type": "investigation",      // Required. See the API reference for possible values.
  "name": "New Case Name",      // Required.
  "severity": "medium",         // Required. Can be `informational`, `low`, `medium`, `high`, or `critical`.
  "status": "new",              // Required. Can be `new` or `investigating`.
  "initialDetectionId": "<detection-id>", // Required
  "assignee": "john.smith@example.com",   // Optional.
  "overview": "Suspicious network activity detected" // Optional.
}

Response: A new self-managed case object.

{
  "id": "3-189694",
  "tenant": {
    "id": "c0774e80-0af7-4e38-8f8e-552ba241e093"
  },
  "assignee": {
    "name": "john.smith@example.com"
  },
  "type": "investigation",
  "name": "New Case Name",
  "severity": "medium",
  "status": "new",
  "managedBy": "self",
  "overview": "Suspicious network activity detected",
  "initialDetection": {
    "id": "<detection-id>",
    "severity": 5,
    "type": "Threat",
    "detectionRule": "WIN-PROT-REP-MALWARE-MAL-GENERIC-S",
    "time": "2024-06-13T13:41:55+00:00",
    "sensor": {
      "type": "endpoint",
      "source": "Sophos"
    }
  },
  "detectionCount": 1,
  "createdAt": "2024-06-22T20:08:14.138Z",
  "createdBy": {
    "id": "41ffbb6b-b218-47ec-85e0-2ff72c7246fc",
    "type": "service",
    "accountType": "tenant",
    "accountId": "c0774e80-0af7-4e38-8f8e-552ba241e093"
  },
  "updatedAt": "2024-06-22T20:08:15.690Z"
}

Update a case¶

Only self-managed cases can be created using this API at this time.

To update an existing case:

PATCH cases/v1/cases/{caseId}

Request body:

{
  "type": "hunt",
  "name": "Updated Case Name",
  "severity": "high",
  "status": "inProgress",
  "assignee": "jane.doe@example.com",
  "overview": "Suspicious network activity resolved"
}

Response: The updated case object.

{
  "id": "3-189694",
  "tenant": {
    "id": "c0774e80-0af7-4e38-8f8e-552ba241e093"
  },
  "assignee": {
    "name": "jane.doe@example.com"
  },
  "type": "hunt",
  "name": "Updated Case Name",
  "severity": "high",
  "status": "inProgress",
  "managedBy": "self",
  "overview": "Suspicious network activity detected",
  "initialDetection": {
    "id": "<detection-id>",
    "severity": 5,
    "type": "Threat",
    "detectionRule": "WIN-PROT-REP-MALWARE-MAL-GENERIC-S",
    "time": "2024-06-13T13:41:55+00:00",
    "sensor": {
      "type": "endpoint",
      "source": "Sophos"
    }
  },
  "detectionCount": 1,
  "createdAt": "2024-06-22T20:08:14.138Z",
  "createdBy": {
    "id": "41ffbb6b-b218-47ec-85e0-2ff72c7246fc",
    "type": "service",
    "accountType": "tenant",
    "accountId": "c0774e80-0af7-4e38-8f8e-552ba241e093"
  },
  "updatedAt": "2024-06-22T20:11:59.682Z"
}

Delete a case¶

To delete an existing case, call:

DELETE cases/v1/cases/<case-id>

Response:

{
    "deleted": true
}

Limitations¶

When retrieving case detections using the GET /cases/v1/cases/{caseId}/detections API:

Passing pageSize query parameter greater than 50 results in a 400 Bad Request error.

Only self-managed cases can be created or updated at this time.

Conclusion¶

For a comprehensive description of the Cases API, see API reference.