GraphQL API

Overview

The DeviceQuest app is built on a GraphQL API, and you can use the same API for your own tools. GraphQL covers everything the app can do: assets, vulnerabilities, compliance, reports, scanning, flows, administration and more. Use it when the REST API doesn’t cover what you need.

GraphQL authenticates with a user session, not an API key. Every request runs as the signed-in user, so each query and mutation checks that user’s role permissions, exactly as in the app.

Endpoint

Send a JSON body with query and, optionally, variables:

{
  "query": "query Assets($p: PaginationInput) { assets(pagination: $p) { totalCount } }",
  "variables": { "p": { "limit": 10, "offset": 0 } }
}

Authenticate with your session

Send your session token in the Authorization header:

Authorization: Bearer <session token>

The session token is the value of the devicequest_session cookie that DeviceQuest sets when you sign in. Sessions last one hour.

To get a session token from a script, sign in through the auth API and read the cookie:

curl -s -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "<your password>"}' \
  "$DEVICEQUEST_BASE_URL/api/v1/auth/login"

SESSION_TOKEN=$(awk '$6 == "devicequest_session" { print $7 }' cookies.txt)

If your account uses multi-factor authentication, the sign-in response asks for a code instead of setting the cookie. Complete the sign-in as described in Multi-factor authentication, or copy the cookie value from a signed-in browser session.

Then query:

curl -s \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { assets(pagination: {limit: 5, offset: 0}) { totalCount hasNextPage edges { node { id name assetType lastSeen } } } }"}' \
  "$DEVICEQUEST_BASE_URL/graphql"

{
  "data": {
    "assets": {
      "totalCount": 12,
      "hasNextPage": true,
      "edges": [
        { "node": { "id": "6c33a39b-8efd-54eb-8730-27057fc82cb9", "name": "db-01", "assetType": "device", "lastSeen": "2026-10-13T13:27:48Z" } }
      ]
    }
  }
}

A request without a valid token returns 401 with {"error": "unauthorized", "message": "..."}, for example Missing Authorization header - JWT token required or Invalid authorization token.

Mutations through the app endpoint

The app’s own endpoint, /api/graphql, also accepts the devicequest_session cookie instead of the header. Because cookies are sent automatically by browsers, mutations sent to /api/graphql must also pass a CSRF check: send the value of the devicequest_csrf cookie in an X-CSRF-Token header. GET /api/auth/csrf sets the cookie if you don’t have it yet.

curl -s -b cookies.txt -c cookies.txt "$DEVICEQUEST_BASE_URL/api/auth/csrf"
CSRF_TOKEN=$(awk '$6 == "devicequest_csrf" { print $7 }' cookies.txt)

curl -s -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -d '{"query": "mutation($id: ID!) { testWebhook(id: $id) }", "variables": {"id": "<webhook id>"}}' \
  "$DEVICEQUEST_BASE_URL/api/graphql"

Permissions and errors

Each field checks the signed-in user’s permissions, for example assets:read for assets or webhooks:write for createWebhook. Some sensitive mutations (API keys, webhooks) also require multi-factor authentication when your role’s MFA policy asks for it.

Like most GraphQL servers, DeviceQuest returns 200 OK for a request that reached the schema, and reports problems in the errors array, next to any data that could be resolved:

{
  "errors": [
    { "message": "permission denied", "path": ["createWebhook"] }
  ],
  "data": null
}

Always check errors before using data.

Playground

The playground is a GraphiQL editor with schema documentation, autocompletion and query history. Open https://<your DeviceQuest host>/graphql/playground, then add your token in the Headers tab under the query editor:

{ "Authorization": "Bearer <session token>" }

Open the documentation explorer from the sidebar to browse every type, query and mutation.

Query complexity

DeviceQuest limits each operation to a complexity of 1000. Each requested field adds to the complexity, including nested fields. An operation over the limit is rejected before it runs with status 422, and an error such as operation has complexity 1200, which exceeds the limit of 1000. Split large queries into smaller ones, or request fewer nested fields per page.

Pagination

List queries that can return many rows take a PaginationInput:

input PaginationInput {
  limit: Int!
  offset: Int!
}

Without pagination, assets and vulnerabilities return the first 50 rows. Their connection types return totalCount and hasNextPage:

query AssetsPage($offset: Int!) {
  assets(
    filter: { types: ["device"], hasOpenVulns: true }
    sort: { field: "lastSeen", direction: DESC }
    pagination: { limit: 100, offset: $offset }
  ) {
    totalCount
    hasNextPage
    edges {
      node { id name assetType lastSeen tags }
    }
  }
}

Increase offset by limit until hasNextPage is false. A few other lists take plain limit and offset (or first) arguments; the playground shows the arguments of each field.

Schema overview

The schema is grouped by product area. The table lists the main entry points; the playground has the full list.

Related pages

• Authentication
• REST API reference
• Webhooks
• Sign in