Skip to Content
GraphQL API

Mondoo API Concepts

Understand MRNs, scopes, pagination, filters, errors, and schema introspection in the Mondoo GraphQL API.

These concepts apply to most queries and mutations in the Mondoo API.

MRNs

Every object in Mondoo has a Mondoo Resource Name (MRN), a unique identifier that looks like a path. The API uses MRNs to say which organization, space, asset, or finding a call is about.

ObjectMRN formatWhere to find it
Organization//captain.api.mondoo.app/organizations/YOUR_ORG_IDThe Organization MRN field on the organization's Settings > General page
Space//captain.api.mondoo.app/spaces/YOUR_SPACE_IDThe Space MRN field on the space's Settings > General page
Asset//assets.api.mondoo.app/spaces/YOUR_SPACE_ID/assets/YOUR_ASSET_IDThe mrn field that the assets query returns
Vulnerability//vadvisor.api.mondoo.app/cves/CVE-2024-3094The findingMrn field that the aggregateScores query returns

Other objects, such as checks, exceptions, tickets, and integrations, also have MRNs. The query that lists them returns the MRN in an mrn or findingMrn field. Copy MRNs from API responses rather than building them yourself.

To learn more about organization and space settings, read Space general settings and Organization general settings.

Scopes

Many operations take a scope: an MRN argument, usually named scopeMrn, spaceMrn, or entityMrn, that sets which part of your account the call covers. Pass a space MRN to work with a whole space, or an asset MRN to work with one asset. Some operations also accept an organization MRN to cover every space in the organization. Each recipe in this section says which scopes its operation accepts.

Your token must have access to the scope you pass. A space token can't read another space, even in the same organization.

Pagination

Queries that can return many items return a connection: a page of results plus the information you need to get the next page. A connection has these fields:

  • totalCount: the number of items that match, across all pages
  • edges: the items on this page, each in a node field
  • pageInfo: endCursor (a marker for the last item on this page) and hasNextPage (whether there are more items)

Pass first to set the page size. To get the next page, pass the previous page's endCursor as after, and repeat while hasNextPage is true:

query ListAssetsPage($scopeMrn: String!, $after: String) {
  assets(scopeMrn: $scopeMrn, first: 100, after: $after) {
    totalCount
    edges {
      node {
        mrn
        name
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

This Python loop collects every asset in a space, one page at a time. It uses the run_query function from Make your first request:

QUERY = """
query ListAssetsPage($scopeMrn: String!, $after: String) {
  assets(scopeMrn: $scopeMrn, first: 100, after: $after) {
    totalCount
    edges {
      node {
        mrn
        name
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}
"""

assets = []
after = None
while True:
    data = run_query(QUERY, {"scopeMrn": "//captain.api.mondoo.app/spaces/YOUR_SPACE_ID", "after": after})
    page = data["assets"]
    assets.extend(edge["node"] for edge in page["edges"])
    if not page["pageInfo"]["hasNextPage"]:
        break
    after = page["pageInfo"]["endCursor"]

print(len(assets), "assets")

Filters and sorting

Most list queries accept arguments that narrow and sort the results:

  • queryTerms takes a list of search terms. For example, queryTerms: ["nginx"]. The schema description of each query says which fields its terms match.
  • filter takes an input object with the filters a query supports, such as ratings, types, or states. For example, filter: { rating: [CRITICAL, HIGH] }.
  • orderBy takes a field and a direction. For example, orderBy: { field: RISK_VALUE, direction: DESC }.

The recipes show the filters that are most useful for each task. To see every filter a query supports, explore the schema.

Results that can be errors

Some queries return either their results or an error object, as a GraphQL union. For example, findings and aggregateScores return a connection when they succeed, or a RequestError or NotFoundError when the request can't be served. Use an inline fragment (... on TypeName) for each type you want to handle, and ask for __typename so you can tell them apart:

query FindingsWithErrors($scopeMrn: String!) {
  findings(scopeMrn: $scopeMrn, first: 10) {
    __typename
    ... on FindingsConnection {
      totalCount
    }
    ... on RequestError {
      message
    }
    ... on NotFoundError {
      message
    }
  }
}

The items in a findings connection are also a union, because one list can hold several kinds of findings, such as CveFinding and CheckFinding. Use an inline fragment for each kind you want. To see an example, read List the findings on one asset.

Errors

Check every response for errors. They come in three forms.

The request is rejected before GraphQL runs. If the Authorization header is missing, Mondoo responds with HTTP status 403:

{ "code": 7, "message": "request permission denied" }

If the token is invalid or was deleted, Mondoo responds with HTTP status 401:

{ "code": 16, "message": "request permission unauthenticated" }

The operation fails. The response has HTTP status 200 and an errors array. Each error has a message, a path that says which field failed, and often an extensions.code such as PERMISSION_DENIED, NOT_FOUND, or INVALID_ARGUMENT. Other fields in the same request can still succeed: their values are in data, and the failed field is null. A response for a token that has no access to the space it asked about has this shape:

{
  "errors": [
    {
      "message": "A description of the problem",
      "path": ["assets"],
      "extensions": { "code": "PERMISSION_DENIED" }
    }
  ],
  "data": { "assets": null }
}

The query returns an error object. Queries that return a union, as described in Results that can be errors, report some problems as a RequestError or NotFoundError inside data instead of in errors. Both types have a message and a code.

A PERMISSION_DENIED error usually means the token's role doesn't include the permission the operation needs. To change it, read Change a token's permissions.

Explore the schema

The API supports GraphQL introspection, so you can load the full schema, including every query, mutation, argument, and field description, into any tool that understands GraphQL. Point the tool at your region's /query endpoint and add your Authorization header.

You can also explore the schema and run queries in your browser with the GraphQL playground for your region:

  • US: https://us.api.mondoo.com/playground
  • EU: https://eu.api.mondoo.com/playground

Open Headers at the bottom of the playground and add your token:

{ "Authorization": "Bearer YOUR_API_TOKEN" }

The playground saves headers in your browser. Use a token with the Viewer role for exploring, and delete the token when you're done.

Fields that the schema marks as deprecated still work, but they can be removed in a future release. Don't build new scripts on them. Introspection reports each deprecated field with isDeprecated: true and a deprecationReason, which often names the replacement.

Next steps

Last updated on

On this page