Skip to content

Get Started with the Detections API🔗

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.

The Detections API offers aliases you can use so that your integrations match the Detection terminology used in the Secureworks® Taegis™ XDR UI.

Detection Operation Aliases🔗

Every operation in the Alerts GraphQL API is also available under a detection* alias. Aliases accept the same inputs, return the same response types, and use the same authentication as their alertsService* counterparts. They exist so integrations can use the Detection terminology that matches the Secureworks® Taegis™ XDR UI. Use whichever naming your integration prefers.

Note

For full request and response field definitions, see the Alerts GraphQL API schema reference.

Access the Detections Gateway Directly🔗

The Detections API can be reached in the following ways:

  • Through the GraphQL federation gateway at https://api.<region>.secureworks.com/graphql, alongside every other XDR GraphQL API. See API Authentication for details.
  • Directly through the /detections/query gateway, which routes straight to the Detections service without going through the federation gateway. Use this if your integration calls the API directly rather than through federation.

Both accept the same detection* operations, use the same authentication (Authorization: Bearer {token} plus an X-Tenant-Context header), and return the same GraphQL responses.

Regions

The URL to access the Detections gateway directly may differ according to the region your environment is deployed in:

  • US1— https://api.ctpx.secureworks.com/detections/query
  • US2— https://api.delta.taegis.secureworks.com/detections/query
  • US3— https://api.foxtrot.taegis.secureworks.com/detections/query
  • EU1— https://api.echo.taegis.secureworks.com/detections/query
  • EU2— https://api.golf.taegis.secureworks.com/detections/query

The examples here use https://api.ctpx.secureworks.com/detections/query. If you are in a different region, substitute appropriately.

Example Request🔗

The following sends a detectionSearch query directly to the /detections/query gateway. It returns critical- and high-severity detections created within the last day.

export ACCESS_TOKEN="your_access_token"
export TENANT_ID="your_tenant_id"
curl -g \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Tenant-Context: $TENANT_ID" \
-H "Content-type: application/json" \
-X POST \
-d '{"query": "query { detectionSearch(in: { cql_query: \"FROM alert WHERE severity >= 0.6 EARLIEST=-1d\", limit: 10 }) { reason search_id status alerts { total_results list { id status tenant_id metadata { title severity confidence } } } } }"}' \
https://api.ctpx.secureworks.com/detections/query

your_access_token is the access token obtained during API authentication and your_tenant_id is the ID of the tenant you want to access.

Query Aliases🔗

Detection alias Alerts equivalent
detectionRetrieveById alertsServiceRetrieveAlertsById
detectionRetrieveByHost alertsServiceRetrieveAlertsByHost
detectionRetrieveByEntity alertsServiceRetrieveAlertsByEntity
detectionRetrieveByGroupKey alertsServiceRetrieveAlertsByGroupKey
detectionCountByTenant alertsCountByTenant
detectionSearch alertsServiceSearch
detectionPoll alertsServicePoll
detectionAggregatesBySeverity alertsServiceAggregateAlertsBySeverity

Mutation Aliases🔗

Detection alias Alerts equivalent
detectionUpdateInvestigationInfo alertsServiceUpdateInvestigationInfo
detectionUpdateResolutionInfo alertsServiceUpdateResolutionInfo
detectionBulkInvestigationsProcessor alertsServiceBulkInvestigationsProcessor
detectionUpdateThreatScore alertsServiceUpdateThreatScore
detectionUpdateThreatScoreV2 alertsServiceUpdateThreatScoreV2

Subscription Aliases🔗

Detection alias Alerts equivalent
detectionBulkResolutionProcessor alertsServiceBulkResolutionProcessor