Get Started with the Cases GraphQL API๐
Important
Before proceeding, complete the API Authentication steps in order to obtain a working client_id and client_secret.
Regions
The URL to access XDR APIs may differ according to the region your environment is deployed in:
- US1โ
https://api.ctpx.secureworks.com - US2โ
https://api.delta.taegis.secureworks.com - US3โ
https://api.foxtrot.taegis.secureworks.com - EU1โ
https://api.echo.taegis.secureworks.com - EU2โ
https://api.golf.taegis.secureworks.com
The examples in this XDR API documentation use https://api.ctpx.secureworks.com throughout. If you are in a different region substitute appropriately.
Note
The terms Alerts and Investigations have recently been changed to Detections and Cases in Taegis XDR. You may still see references to the old terms while we continue to work towards platform convergence of Sophos and Taegis technologies. For more information, see Taegis Terminology Updates.
Before You Begin๐
Before working with cases, it's important to understand the key building blocks:
Case Types๐
Every case belongs to a type that defines its behavior, available statuses, and verdicts. Case types are managed at the tenant level. Before creating a case, you must:
- Query available case types for your tenant.
- Identify the type ID matching your use case.
- Note the type's supported statuses and verdicts.
Each case type has:
- ID: Required for case creation
- Supported Statuses: Valid states for cases of this type
- Supported Verdicts: Outcomes available when closing cases (Confirmed Threat, Not Determined, etc.)
Statuses and Verdicts๐
Cases move through lifecycle states using statuses (Open, Active, Closed, etc.).
When closing a case, assign a verdict to classify the outcome (Confirmed Threat, Not Determined, etc.).
Get Case Types๐
Before creating a case, query available types for your tenant.
Types are dependent on the licenses your account has, and they will change if upgrading from XDR to Taegis MDR, for example.
Each type defines the behavior and valid statuses or verdicts for cases of that type.
Query๐
query getCaseTypes($arguments: CaseTypesArguments!) {
caseTypes(arguments: $arguments) {
types {
id
name
title
description
supportedPrimaryStatuses {
id
name
title
isClosed
isCaseVisibleToCustomers
}
supportedPrimaryVerdicts {
id
name
title
}
allowedNextTypes {
id
name
}
managedBy
}
}
}
Variables๐
Response Example๐
{
"data": {
"caseTypes": {
"types": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "security_incident",
"title": "Security Incident",
"description": "Cases for security incidents and threats",
"supportedPrimaryStatuses": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Open",
"title": "Case is open and active",
"isClosed": false,
"isCaseVisibleToCustomers": true
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Closed",
"title": "Case investigation complete",
"isClosed": true,
"isCaseVisibleToCustomers": true
}
],
"supportedPrimaryVerdicts": [
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"name": "Confirmed Threat",
"title": "Threat confirmed"
},
{
"id": "550e8400-e29b-41d4-a716-446655440004",
"name": "Not Determined",
"title": "Unable to determine"
}
],
"allowedNextTypes": [],
"managedBy": null
}
]
}
}
}
Get Case Statuses๐
Query available statuses for a specific case type. Statuses define the lifecycle states that a case can transition through.
Like types, statuses are dependent on the licenses your account has and they will change if upgrading from XDR to Taegis MDR, for example.
Query for Primary Statuses๐
query getPrimaryStatuses($arguments: CasePrimaryStatusesArguments!) {
casePrimaryStatuses(arguments: $arguments) {
primaryStatuses {
id
name
title
description
isClosed
isCaseVisibleToCustomers
}
}
}
Variables๐
Filter by case type to get statuses valid for that type:
Response Example๐
{
"data": {
"casePrimaryStatuses": {
"primaryStatuses": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Open",
"title": "Case is open and active",
"description": "Case is actively being investigated",
"isClosed": false,
"isCaseVisibleToCustomers": true
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Closed",
"title": "Case investigation complete",
"description": "Case investigation has concluded",
"isClosed": true,
"isCaseVisibleToCustomers": true
}
]
}
}
}
Notes๐
- Statuses are required when creating or updating a case. Use
typeIdto filter to statuses valid for your case type. - Check the
isClosedfield to identify which statuses represent completed or closed cases.
Get Case Verdicts๐
When closing a case, you assign verdicts that classify the outcome. Query available verdicts for your case type.
Like types, verdicts are dependent on the licenses your account has and they will change if upgrading from XDR to Taegis MDR, for example.
Query for Primary Verdicts๐
query getPrimaryVerdicts($arguments: CasePrimaryVerdictsArguments!) {
casePrimaryVerdicts(arguments: $arguments) {
primaryVerdicts {
id
name
title
description
}
}
}
Variables๐
Response Example๐
{
"data": {
"casePrimaryVerdicts": {
"primaryVerdicts": [
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"name": "Confirmed Threat",
"title": "Threat confirmed",
"description": "Malicious activity was confirmed"
},
{
"id": "550e8400-e29b-41d4-a716-446655440004",
"name": "Not Determined",
"title": "Unable to determine",
"description": "Insufficient evidence to classify"
}
]
}
}
}
Notes๐
- Verdicts are required when closing a case (setting to a closed status).
- Verdicts classify the outcome of your case investigation.
- The Case Type ID is required and must reference a valid type for your tenant. Query
caseTypesto get available IDs. - For Severity, use numeric values only. Numbers map to severity as follows:
2(Informational),4(Low),6(Medium),8(High),10(Critical). - Once Managed By is set (either
PROVIDERorCUSTOMER), it can't be changed. This field determines who controls case operations.
Assigning Cases to Users๐
The assigneeId field accepts several formats:
User and Group IDs๐
- User ID: UUID of a specific user (for example,
550e8400-e29b-41d4-a716-446655440010) - Group ID: UUID of a team or group
- Empty string: Clears the assignee, leaving case unassigned
- Omitted: No assignee by default
Special Mentions๐
Case assignments can also use special mentions, which route cases to specific roles or teams. Availability depends on your tenant type and service level:
| Mention | When Available | Use |
|---|---|---|
@customer |
Non-XDR tenants only | Route to your organization |
@admin |
XDR tenants with Cases API | Route to administrators |
@authorized_contacts |
Taegis MDR tenants only | Route to authorized Taegis MDR contacts |
@sophos |
All tenants (partner-restricted) | Route to Sophos team |
Partner-restricted mentions (@sophos) may not be available depending on your service agreement.
Your service partner may define custom mentions specific to your agreement. Contact your partner or account team for available mention options.
To find user IDs for your tenant, use the Users API to query available users.
Incident Advisor๐
Taegis MDR cases can have an Incident Advisor assigned, which is a Sophos analyst who acts as a point of contact for the case. This field is read-only through the API.
Query๐
query getCase($arguments: CaseArguments!) {
case(arguments: $arguments) {
id
incidentAdvisorId
incidentAdvisor {
id
email
givenName
familyName
}
}
}
Response Example๐
{
"data": {
"case": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"incidentAdvisorId": "550e8400-e29b-41d4-a716-446655440050",
"incidentAdvisor": {
"id": "550e8400-e29b-41d4-a716-446655440050",
"email": "advisor@sophos.com",
"givenName": "Jane",
"familyName": "Doe"
}
}
}
}
Notes๐
- Availability depends on your tenant type and license level โ Incident Advisor is only available for Taegis MDR tenants.
incidentAdvisorIdandincidentAdvisorare read-only through this API. Only your Sophos partner/provider can assign or change the Incident Advisor.incidentAdvisorresolves tonullif no advisor is assigned or the user can't be resolved.
Create a Case๐
Creating a case requires a case type ID, an initial primary status. You don't need to have evidence (detections, events, or assets) at this point, but it can be added at this time.
If you don't know what case types or statuses are available for your tenant, see Get Case Types and Get Case Statuses first.
Workflow๐
The workflow for creating a case is as follows:
- Get Case Types: Query
caseTypesto find available types. - Get Statuses: Query
casePrimaryStatuseswith the type ID to get valid initial statuses. - Create Case: Call
createCasemutation with type ID, status ID, and evidence.
Mutation๐
mutation createCase($input: CreateCaseInput!) {
createCase(input: $input) {
id
shortId
title
severity
type {
id
name
}
primaryStatus {
id
name
}
primaryVerdict {
id
name
}
assigneeId
createdAt
updatedAt
riskScore
}
}
Variables๐
{
"input": {
"typeId": "550e8400-e29b-41d4-a716-446655440000",
"severity": 6,
"title": "Suspicious Activity Detected",
"primaryStatusId": "550e8400-e29b-41d4-a716-446655440001",
"tags": ["malware", "investigation"],
"keyFindings": {
"documentType": "MARKDOWN",
"documentVersion": "1.0",
"content": "Initial findings from automated detection"
},
"assigneeId": "@customer",
"detectionIds": [
"detection://priv:thirdpartyalert:93097:1787242536039:a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c",
"detection://priv:thirdpartyalert:93097:1787242587105:c5d6e7f8-a9b0-41c2-8d3e-4f5a6b7c8d9e"
]
}
}
Response Example๐
{
"data": {
"createCase": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"shortId": "CSE00001",
"title": "Suspicious Activity Detected",
"severity": 6,
"type": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "security_incident"
},
"primaryStatus": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Open"
},
"primaryVerdict": null,
"assigneeId": "@customer",
"createdAt": "2024-08-14T15:52:30Z",
"updatedAt": "2024-08-14T15:52:30Z",
"riskScore": 0
}
}
}
Notes๐
typeIdis required and must reference a valid case type for the tenant.severityis required and must be one of the following: 2 (Informational), 4 (Low), 6 (Medium), 8 (High), 10 (Critical).primaryStatusIdis required and determines the initial state of the case.- Detections, events, and assets added during case creation are considered genesis evidence.
keyFindingsis a typed document with format and version information. The content is always a string (serialize JSON if using rich text).documentTypecurrently only supports"MARKDOWN".documentVersioncurrently only supports"1.0".
Get a Case๐
Retrieve a single case by ID or search for multiple cases using filters.
Query to Get Case by ID๐
query getCase($arguments: CaseArguments!) {
case(arguments: $arguments) {
id
shortId
title
severity
type {
id
name
}
primaryStatus {
id
name
}
primaryVerdict {
id
name
}
tags
assigneeId
managedBy
riskScore
createdAt
updatedAt
closedAt
closedById
closeReason
archivedAt
contributorIds
detectionsCount
eventsCount
assetsCount
links {
id
url
title
type
isInternal
}
}
}
Variables๐
Response Example๐
{
"data": {
"case": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"shortId": "CSE00001",
"title": "Suspicious Activity Detected",
"severity": 6,
"type": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "security_incident"
},
"primaryStatus": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Open"
},
"primaryVerdict": null,
"tags": ["malware", "investigation"],
"assigneeId": "@customer",
"managedBy": "CUSTOMER",
"riskScore": 75.5,
"createdAt": "2024-08-14T15:52:30Z",
"updatedAt": "2024-08-14T16:00:00Z",
"closedAt": null,
"closedById": null,
"closeReason": null,
"archivedAt": null,
"contributorIds": ["550e8400-e29b-41d4-a716-446655440010"],
"detectionsCount": 5,
"eventsCount": 12,
"assetsCount": 2,
"links": []
}
}
}
Notes๐
- Short ID: The
shortId(e.g., CSE00001) is a human-readable identifier. Use the fullidfor API operations. - Managed By:
managedByreturnsCUSTOMERorPROVIDER.CUSTOMERmaps to self-managed cases;PROVIDERmaps to cases managed by Sophos (named generically to accommodate other providers in the future). The UI translates these values to their display names. This field only applies to Taegis MDR customers โ Taegis MDR cases can havemanagedByset to eitherCUSTOMERorPROVIDER, since a customer or Sophos can manage the case. XDR customers manage all cases themselves, somanagedByis alwaysCUSTOMERand not relevant to XDR workflows. Once set,managedBycannot be changed. - Verdicts: Empty until the case is closed. Assign verdicts when setting the case to a closed status.
- Contributors:
contributorIdslists users who have contributed to the case (comments, evidence, etc.). - Closed By:
closedByIdis set only once the case has been closed, and reflects the most recent closer if the case was reopened and closed again. - Archived:
archivedAtis set only when the case has been archived. See Archive a Case. - Links: See Case Links for managing linked resources.
Search and Filter Cases๐
For detailed search and filtering documentation, see Search and Filter Cases. You can query cases by title, severity, status, dates, tags, assignee, and more using the Cases query language.
Update a Case๐
Updates are partial (PATCH semantics) โ only provided fields are modified.
Mutation๐
mutation updateCase($input: UpdateCaseInput!) {
updateCase(input: $input) {
id
shortId
title
severity
primaryStatus {
id
name
}
assigneeId
updatedAt
riskScore
}
}
Variables๐
{
"input": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"title": "Updated Case Title",
"severity": 8,
"primaryStatusId": "550e8400-e29b-41d4-a716-446655440002",
"assigneeId": "@sophos",
"riskScore": 85.5,
"closeReason": "Case resolved successfully",
"primaryVerdictId": "550e8400-e29b-41d4-a716-446655440003"
}
}
Response Example๐
{
"data": {
"updateCase": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"shortId": "CSE00001",
"title": "Updated Case Title",
"severity": 8,
"primaryStatus": {
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Closed"
},
"assigneeId": "@sophos",
"updatedAt": "2024-08-14T16:30:45Z",
"riskScore": 85.5
}
}
}
Notes๐
- Only provided fields will be updated (PATCH semantics).
idis the only required field.- Once
managedByis set, it cannot be changed. - When closing a case (setting to a closed status), provide a
primaryVerdictIdto classify the outcome. - To close a case with a verdict, update both
primaryStatusId(to a closed status) andprimaryVerdictIdin the same request.
Archive a Case๐
Archiving lets you move closed cases out of your active view without deleting them.
Mutation๐
mutation archiveCase($input: UpdateCaseInput!) {
updateCase(input: $input) {
id
shortId
primaryStatus {
id
name
}
archivedAt
}
}
Variables๐
Archive a closed case:
Unarchive a case:
Response Example๐
{
"data": {
"updateCase": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"shortId": "CSE00001",
"primaryStatus": {
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Closed"
},
"archivedAt": "2024-08-14T17:00:00Z"
}
}
}
Notes๐
isArchived: trueis only allowed for cases in a closed status.isArchived: falseunarchives the case;archivedAtis cleared back tonull.- Omitting
isArchivedleaves the archive state unchanged.
Add Evidence to a Case๐
Mutation๐
mutation addEvidenceToCase($input: AddEvidenceToCaseInput!) {
addEvidenceToCase(input: $input) {
caseId
detectionIds
detectionsSearchQuery
eventIds
searchQueries
hostIds
}
}
Variables๐
{
"input": {
"caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"detectionIds": [
"detection://priv:thirdpartyalert:93097:1787242536039:a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c",
"detection://priv:thirdpartyalert:93097:1787242587105:c5d6e7f8-a9b0-41c2-8d3e-4f5a6b7c8d9e"
],
"eventIds": [
"event://priv:scwx.cloudaudit:11772:1787243648000:f99385d1-ae24-557d-965c-a5e096e193fc"
],
"detectionsSearchQuery": "severity >= 6",
"searchQueries": [
"550e8400-e29b-41d4-a716-446655440200"
],
"hostIds": [
"host://priv:scwx.cloudaudit:11772:1787243648000:e5f6g7h8-3456-7890-2bcd-ef0123456789"
]
}
}
Response Example๐
{
"data": {
"addEvidenceToCase": {
"caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"detectionIds": [
"detection://priv:thirdpartyalert:93097:1787242536039:a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c",
"detection://priv:thirdpartyalert:93097:1787242587105:c5d6e7f8-a9b0-41c2-8d3e-4f5a6b7c8d9e"
],
"eventIds": [
"event://priv:scwx.cloudaudit:11772:1787243648000:f99385d1-ae24-557d-965c-a5e096e193fc"
],
"hostIds": [
"host://priv:scwx.cloudaudit:11772:1787243648000:e5f6g7h8-3456-7890-2bcd-ef0123456789"
]
}
}
}
Notes๐
- Adding evidence is an asynchronous operation.
- The API returns the evidence that will be attempted to be added.
detectionsSearchQueryaccepts a QUERY expression and will attach up to 50,000 detections.- Evidence added through this mutation is NOT considered genesis evidence.
Remove Evidence from a Case๐
Mutation๐
mutation removeEvidenceFromCase($input: RemoveEvidenceFromCaseInput!) {
removeEvidenceFromCase(input: $input) {
caseId
detectionIds
eventIds
assetIds
searchQueries
}
}
Variables๐
{
"input": {
"caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"detectionIds": [
"detection://priv:thirdpartyalert:93097:1787242536039:a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c"
],
"eventIds": [
"event://priv:scwx.cloudaudit:11772:1787243648000:f99385d1-ae24-557d-965c-a5e096e193fc"
],
"assetIds": [
"asset://priv:scwx.cloudaudit:11772:1787243648000:g7h8i9j0-5678-9012-4def-012345678901"
],
"searchQueries": [
"550e8400-e29b-41d4-a716-446655440200"
]
}
}
Response Example๐
{
"data": {
"removeEvidenceFromCase": {
"caseId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"detectionIds": [
"detection://priv:thirdpartyalert:93097:1787242536039:a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c"
],
"eventIds": [
"event://priv:scwx.cloudaudit:11772:1787243648000:f99385d1-ae24-557d-965c-a5e096e193fc"
],
"assetIds": [
"asset://priv:scwx.cloudaudit:11772:1787243648000:g7h8i9j0-5678-9012-4def-012345678901"
]
}
}
}
Notes๐
- Removing evidence is an asynchronous operation.
- Evidence can be removed independently (removing a detection does not remove related events or assets).
Get Case Evidence๐
Retrieve evidence (such as detections, events, and assets) attached to a case.
Query๐
query caseEvidence($arguments: CaseEvidenceArguments!) {
caseEvidence(arguments: $arguments) {
id
detectionsEvidence {
id
detectionId
createdAt
isGenesis
}
detectionsEvidenceCount
eventsEvidence {
id
eventId
createdAt
isGenesis
}
eventsEvidenceCount
assetsEvidence {
id
assetId
createdAt
}
assetsEvidenceCount
searchQueriesEvidence {
id
searchQueryId
createdAt
}
searchQueriesEvidenceCount
}
}
Variables๐
Response Example๐
{
"data": {
"caseEvidence": {
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"detectionsEvidence": [
{
"id": "550e8400-e29b-41d4-a716-446655440100",
"detectionId": "detection://priv:thirdpartyalert:93097:1787242536039:a1b2c3d4-e5f6-47a8-9b0c-1d2e3f4a5b6c",
"createdAt": "2024-08-14T15:52:30Z",
"isGenesis": true
}
],
"detectionsEvidenceCount": 5,
"eventsEvidence": [
{
"id": "550e8400-e29b-41d4-a716-446655440101",
"eventId": "event://evt001",
"createdAt": "2024-08-14T15:52:25Z",
"isGenesis": true
}
],
"eventsEvidenceCount": 12,
"assetsEvidence": [
{
"id": "550e8400-e29b-41d4-a716-446655440102",
"assetId": "host://asset001",
"createdAt": "2024-08-14T15:52:20Z"
}
],
"assetsEvidenceCount": 2,
"searchQueriesEvidence": [],
"searchQueriesEvidenceCount": 0
}
}
}
Notes๐
- Returns evidence entry IDs and source IDs (
detectionId,eventId,assetId). isGenesisindicates evidence used to initially create the case.- Evidence counts show total attached to case.
- Use to verify what evidence supports a case investigation.
Search Cases๐
For detailed search and filtering documentation, including pagination options and query syntax, see Search and Filter Cases.
Query Example๐
query cases($arguments: CasesArguments!) {
cases(arguments: $arguments) {
cases {
id
shortId
title
severity
type {
id
name
}
primaryStatus {
id
name
}
tags
assigneeId
createdAt
updatedAt
}
totalCount
}
}
Variables Example๐
Response Example๐
{
"data": {
"cases": {
"cases": [
{
"id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"shortId": "CSE00001",
"title": "Suspicious Activity Detected",
"severity": 8,
"type": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "security_incident"
},
"primaryStatus": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Open"
},
"tags": ["malware", "critical"],
"assigneeId": "@customer",
"createdAt": "2024-08-14T15:52:30Z",
"updatedAt": "2024-08-14T16:30:45Z"
}
],
"totalCount": 1
}
}
}
File Management๐
For uploading, retrieving, downloading, and deleting case files, see Manage Case Files.
Comments๐
For comprehensive comment management including adding, updating, searching, and deleting case comments, see Manage Case Comments.
Case Links๐
For creating, updating, and deleting links to external systems or internal resources on a case, see Manage Case Links.