Migrating from the Detections REST API

Audience and scope¶

This guide is for developers with an integration against the Detections REST API who need to move it to the Detections GraphQL API.

If you are building a new GraphQL integration, start with Getting started with the Detections GraphQL API.

This is not a drop-in replacement. The REST API starts a query run, waits for completion, and then returns a separate result page. The GraphQL API sends one search request and returns a selection of fields in its response.

The GraphQL schema uses detection names for the current API surface. Some schema descriptions and older operation aliases still use alert. Treat those names as detections.

This guide covers:

• The equivalent GraphQL operation for each REST workflow.
• Request and response shape changes.
• Filter and pagination changes.
• REST fields without a direct GraphQL equivalent.
• GraphQL operations that add capabilities to the migration.

Mappings are based on the published Detections REST API v1 specification and the vendored Detections GraphQL schema.

What changed¶

Authentication stays the same. Send the token and tenant ID to your configured GraphQL endpoint instead of a regional REST host. See Getting started as a Partner, as an Organization, or as a Tenant.

Endpoint mapping¶

Run a detections query¶

REST: POST /detections/v1/queries/detections

The REST request accepts separate properties for each filter. It returns a run ID, which you use in later requests.

{
  "severity": [4, 8, 9],
  "from": "2021-10-02T14:53:22.017Z",
  "to": "2021-11-01T15:53:22.017Z"
}

GraphQL: Query.detectionSearch

query SearchDetections($in: SearchRequestInput) {
  detectionSearch(in: $in) {
    status
    reason
    alerts {
      total_results
      list {
        id
        status
        metadata {
          title
          severity
          created_at { seconds nanos }
        }
      }
    }
  }
}

{
  "variables": {
    "in": {
      "cql_query": "from alert where severity >= 0.4 and severity <= 0.9 earliest='2021-10-02T14:53:22.017Z' latest='2021-11-01T15:53:22.017Z'",
      "limit": 100,
      "offset": 0
    }
  }
}

GraphQL returns the fields in the selection set. It does not return a full detection unless you request the full selection set. Keep the selection set small for list requests.

Check query status¶

REST: GET /detections/v1/queries/detections/{runId}

GraphQL: No direct equivalent is required. detectionSearch returns the result status in the same response. Check data.detectionSearch.status and the GraphQL errors array.

For large searches, the response can include a search_id. Pass that value to Query.detectionPoll to fetch the next result part.

Get query results¶

REST: GET /detections/v1/queries/detections/{runId}/results?page=1&pageSize=3

GraphQL: Read detectionSearch.alerts.list from the initial response. The GraphQL response contains total_results, which is the number of detections that match the query, not only the number in the current page.

For searches below 10,000 detections, request another page with offset and limit:

query SearchDetections($in: SearchRequestInput) {
  detectionSearch(in: $in) {
    status
    alerts {
      total_results
      list { id status metadata { title severity } }
    }
  }
}

{
  "variables": {
    "in": {
      "cql_query": "from alert where status = 'OPEN' earliest=-1d",
      "limit": 500,
      "offset": 500
    }
  }
}

For a large result set, use the search_id returned by the previous response. The API advances the result part for you. Keep fetching until the response indicates that no next part remains, and confirm that the number of detections received matches total_results.

Get a detection by ID¶

REST: The REST API returns full detection objects in the query result list. It does not expose a separate get-by-ID endpoint.

GraphQL: Query.detectionRetrieveById

query GetDetections($in: GetByIDRequestInput) {
  detectionRetrieveById(in: $in) {
    alerts {
      list {
        id
        status
        metadata {
          title
          description
          severity
          created_at { seconds nanos }
          first_seen_at { seconds nanos }
        }
        sensor_types
        attack_technique_ids
        source_entities { display_name subtype }
        target_entities { display_name subtype }
        event_ids { id }
      }
    }
  }
}

{
  "variables": {
    "in": {
      "iDs": ["<detection-id>"]
    }
  }
}

The input name is iDs, including its capitalization. You can pass more than one detection ID in the same request.

Find detections by host or entity¶

REST: Filter the query request with deviceName or other supported REST properties.

GraphQL: Use Query.detectionRetrieveByHost or Query.detectionRetrieveByEntity.

Both operations use GetByIDRequestInput. Pass the host ID or entity identifier in iDs, then select the detection fields you need from the returned list.

Find detections by group key¶

REST: POST /detections/v1/queries/detection-groups, followed by the group status and result requests.

GraphQL: Query.detectionRetrieveByGroupKey

The GraphQL operation accepts group-key values in iDs. Use it only when your integration needs the deduplication group. For general searches, use detectionSearch instead.

Get detection counts¶

REST: GET /detections/v1/queries/detections/counts

GraphQL: Use Query.detectionAggregatesBySeverity for severity aggregates. Use Query.detectionCountByTenant for a count across a tenant scope.

For severity aggregates, provide the time range as TimestampInput values and select the grouping fields you need:

query DetectionCounts($in: AggregateAlertsBySeverityInputInput) {
  detectionAggregatesBySeverity(in: $in) {
    aggregation {
      key
      count
      severities { info low medium high critical }
    }
  }
}

The GraphQL schema does not provide the REST response shape of a time series grouped by day, hour, or minute. If your integration needs that exact breakdown, use detectionSearch with a QL time range and aggregate the returned results in your application, or confirm the aggregate fields in the generated reference before implementation.

Request and field mapping¶

Filters¶

REST filters become predicates in cql_query. The QL source keyword remains alert for this API. Combine predicates with and. Use or when you need more than one value.

Do not assume that every REST filter has the same QL field name. Validate each predicate against the Detections GraphQL API reference and test it with a small time range.

Response fields¶

Get raw data for a detection event¶

event_ids returns event resource names. It does not return an event payload. Pass each id unchanged to the Events API to get event details.

For a worked example, including the normalized values and MITRE ATT&CK details, see Get event details from cases and detections.

query DetectionEventData($input: EventsInput!) {
  events(input: $input) {
    rn
    values
  }
}

{
  "variables": {
    "input": {
      "rns": ["<event-id-from-detection>"]
    }
  }
}

Mutations, subscriptions, and new capabilities¶

The REST Detections API is read-only. The GraphQL API adds mutations for common detection workflows:

• Mutation.detectionUpdateResolutionInfo adds or updates resolution information for detection IDs.
• Subscription: detectionBulkResolutionProcessor applies a resolution to detections selected by a QL query. The generated reference does not publish Subscription operation pages.

The schema also exposes investigation operations. Use them only when your integration manages investigations and verify the required input fields in the generated reference.

Migration checklist¶

• [ ] Replace the regional REST URL with https://api.taegis.sophos.com/graphql.
• [ ] Keep the bearer token and X-Tenant-ID header.
• [ ] Replace the REST query-run, poll, and results sequence with detectionSearch.
• [ ] Translate each REST filter into a tested QL predicate.
• [ ] Reconcile the REST severity scale with GraphQL metadata.severity. Do not convert between them.
• [ ] Replace REST pagination with offset and limit, or continue with the returned search_id.
• [ ] Update response parsing for nested GraphQL fields and { seconds, nanos } timestamps.
• [ ] Replace group queries with detectionRetrieveByGroupKey when you need group-key lookup.
• [ ] Choose the correct GraphQL count operation for your reporting use case.
• [ ] Add GraphQL error handling. A query error can return HTTP 200 with an errors array.
• [ ] Request only the fields your integration uses, especially for nested entities and enrichment data.