Use the DHI API

The DHI API is a GraphQL API for querying Docker Hardened Images data programmatically, for use cases like building automation or dashboards on top of DHI data.

Endpoint#

Send requests as POST requests to:

https://api.dso.docker.com/v1/graphql

Request format#

The API accepts standard GraphQL requests: a JSON body with a query and, optionally, variables.

$ curl https://api.dso.docker.com/v1/graphql \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "...", "variables": { ... }}'

Every query takes a Context argument (conventionally named ctx in the variables object) alongside its query-specific arguments:

Authentication#

An organization access token (OAT) or personal access token (PAT) isn't used directly as the bearer token. Exchange it first for an access token:

$ curl -X POST https://hub.docker.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{"identifier": "<identifier>", "secret": "<token>"}'

For identifier, use your Docker Hub username with a PAT, or the organization name with an OAT. The response contains the access token:

{ "access_token": "..." }

Pass that access_token as Authorization: Bearer <access_token>. Also set ctx.organization in variables to the organization the token belongs to (see Request format).

Response format#

Responses follow the standard GraphQL envelope:

For example, an unauthenticated request, or a request for data your token can't access, returns a null result under data alongside an authorization error in errors, rather than an HTTP-level failure:

{
  "errors": [
    {
      "message": "You are not allowed to read data for this team",
      "path": ["someQuery"],
      "extensions": { "code": "DOWNSTREAM_SERVICE_ERROR", "status": 403 }
    }
  ],
  "data": { "someQuery": null },
  "extensions": { "correlation_id": "..." }
}

Queries#

imagePackagesForImageCoords#

Fetches every package in an image, every CVE reported against it, and whether Docker suppresses that CVE, by digest. See Query VEX for a Docker Hardened Image for a guided example.

Keep the requested response fields limited to what you plan to render. Fields such as locations, description, vulnerableRange, and epss increase response size substantially and aren't needed for a CVE-count or suppressed-CVE view.

Response fields#

vulnerabilityExceptions only contains records that actually suppress a CVE, so it always lines up with isExcepted: an empty array means the CVE is live. Use isExcepted as your filter for "is this CVE suppressed."

Mapping to OpenVEX#

If your pipeline consumes OpenVEX documents (for example, Trivy's --vex flag), each suppressed record maps as follows: