Skip to content

Getting started

What you will build

A GraphQL request that authenticates and lists your tenant's cases — the cases the platform opens around related alerts, events, and other evidence.

Prerequisites

Get credentials

Follow the audience guide above to create a service principal and exchange it for a bearer token, using the same client_credentials grant as every other Sophos API.

First authenticated call

Send a POST request to the GraphQL endpoint, with the token from the previous step in the Authorization header and your tenant ID in X-Tenant-ID. Every tenant shares this same endpoint — there is no per-environment or per-region host to look up.

cases lists cases. Its arguments take a query search string to filter by criteria such as status or severity, and a pagination.offset object to paginate: pages start at 1, and perPage tops out at 100. This call asks for the first page of 10 cases and their status, with no query filter.

For query syntax, filters, and pagination options, see Search and filter cases.

When you omit a sort expression, the API returns cases in createdAt desc (newest first) order. This request therefore asks for the 10 most recent cases.

curl -X POST "https://api.taegis.sophos.com/graphql" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ListCases($arguments: CasesArguments!) { cases(arguments: $arguments) { totalCount cases { id title severity primaryStatus { name } } } }",
    "variables": { "arguments": { "pagination": { "offset": { "page": 1, "perPage": 10 } } } }
  }'

A successful response looks like this:

{
  "data": {
    "cases": {
      "totalCount": 3,
      "cases": [
        {
          "id": "6f1b1e0e-6b1a-4b3a-9c1a-1a2b3c4d5e6f",
          "title": "Suspicious PowerShell activity",
          "severity": 8,
          "primaryStatus": { "name": "open" }
        }
      ]
    }
  }
}

Verify it worked

Check data.cases.totalCount in the response. It's a number — the count of cases matching your request, not only the page you asked for. Each entry in data.cases.cases has the id, title, severity, and primaryStatus fields you selected, in that order.

A request that fails at the GraphQL layer — for example, a query string the schema can't parse — still returns HTTP 200, with an errors array alongside data instead of an HTTP error status. This differs from the status-coded error object described in Errors, which covers this API's transport layer instead. An expired token or a rate limit still fails that way, with a non-2xx status and that error object, before your query ever reaches the GraphQL layer.

What to do next

Selection-set cost

Only ask for the fields you need. Nesting one list-returning field inside another — for example, every case's caseEvidence on a large page of cases — multiplies the amount of data the server has to assemble and return. Keep nested list selections as narrow as the fields you actually use.