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.
| Object | MRN format | Where to find it |
|---|---|---|
| Organization | //captain.api.mondoo.app/organizations/YOUR_ORG_ID | The Organization MRN field on the organization's Settings > General page |
| Space | //captain.api.mondoo.app/spaces/YOUR_SPACE_ID | The Space MRN field on the space's Settings > General page |
| Asset | //assets.api.mondoo.app/spaces/YOUR_SPACE_ID/assets/YOUR_ASSET_ID | The mrn field that the assets query returns |
| Vulnerability | //vadvisor.api.mondoo.app/cves/CVE-2024-3094 | The 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 pagesedges: the items on this page, each in anodefieldpageInfo:endCursor(a marker for the last item on this page) andhasNextPage(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:
queryTermstakes a list of search terms. For example,queryTerms: ["nginx"]. The schema description of each query says which fields its terms match.filtertakes an input object with the filters a query supports, such as ratings, types, or states. For example,filter: { rating: [CRITICAL, HIGH] }.orderBytakes 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
- Query Spaces and Assets: list the spaces in an organization and the assets in a space.
- Query Findings and Vulnerabilities: list the vulnerabilities in a space and the findings on an asset.
Last updated on