Queries and Mutations

The Jamf Protect API (like most GraphQL APIs) uses the following query types as the entry point of the API:

  • Queries

    Search your Jamf Protect data and return a result in JSON format.

  • Mutations

    Write changes to your Jamf Protect data and return optional results in JSON format.

Queries

GraphQL queries search your Jamf Protect data and return a result in JSON.

The following queries are available:

Query

Description

getAlert

Get a specific Alert

getAnalytic

Get a specific Analytic

getComputer

Get information about a specific Computer

getPlan

Get a specific Plan

getPreventList

Get a specific Custom Prevent List

getUnifiedLoggingFilter

Get a specific Unified Logging Filter

listAlerts

Get one or more Alerts with optional filtering criteria

listAnalytics

Get Analytics

listComputers

Get one or more Computers with optional filtering criteria

listPlans

Get one or more Plans with optional filtering criteria

listPreventLists

Get one or more Custom Prevent Lists with optional filtering criteria

listThreatPreventionVersions

Get Threat Prevention database versions

listUnifiedLoggingFilters

Get one or more Unified Logging Filters with optional filtering criteria

Query Examples

listComputers

To get specific information from multiple computers, use the listComputers query. This example returns the following for each computer in your Jamf Protect tenant:

  • The computer hostname and UUID

  • The last insights check-in date and time

  • An insights scorecard summary that lists the computer's compliance status with each insight.

query listComputers {
  listComputers {
    items {
      hostName
      uuid
      insightsUpdated
      scorecard {
        label
        pass
      }
    }
  }
}

getComputer

To only get information about a single computer, use the getComputer query. The following query returns the same information as the example above (excluding the UUID) but only for a single computer:

query getComputer {
 getComputer(uuid: "ed6553dd-28e7-4ba6-b6e5-2d58b9b37696"){
 hostName
 insightsUpdated
 scorecard{
 label
 pass
   }
  }
 }
Note:

Most queries about a specific object type, such as a Computer or Plan, require the object's ID. You can get the ID of any object type using a list query like in the listComputers example above.

Mutations

GraphQL mutations write changes to your Jamf Protect data. You can create, delete, or update available settings in Jamf Protect. When you write a mutation, you enter an input that defines new values for required fields, and you can specify which fields the mutation returns after it executes.

The following mutations are available:

Mutation

Description

createPreventList

Create a new Custom Prevent List

createUnifiedLoggingFilter

Create a new Unified Logging Filter

deleteComputer

Delete the record of a specific Computer, and associated Logs and Alerts

deletePreventList

Delete a specific Custom Prevent List

deleteUnifiedLoggingFilter

Delete a specific Unified Logging Filter

setComputerPlan

Assign a Plan to a specific Computer during the next agent check-in

setPlanAnalytics

Add Analytics to a specific Plan

updateUnifiedLoggingFilter

Update an Existing Unified Logging Filter

Mutation Examples

createUnifiedLoggingFilter

The following createUnifiedLoggingFilter mutation creates a new Unified Logging Filter called Login Events, which will record each user login on computers in Jamf Protect.

mutation createFilter {
  createUnifiedLoggingFilter(
    input: {
      name: "Login Events"
      filter: "processImagePath contains 'loginwindow` and eventMessage contains `com.apple.sessionDidLogin`
      enabled: true
      tags: "Login"
    }
  ) {
    uuid
    name
    created
    updated
    filter
    tags
    enabled
  }
}

setComputerPlan

To change a computer’s plan, use the setComputerPlan mutation. The following mutation changes a computer (defined by a UUID) to a plan with the ID “1”, and then returns current information about the computer after the computer executes:

Note:

The return information in this example includes the computer's current plan. The computer's plan will not change until it checks in with Jamf Protect.

mutation changePlan {
  setComputerPlan(
    input: { plan: "1" }
    uuid: "ed6553dd-28e7-4ba6-b6e5-2d58b9b37696"
  ) {
    plan {
      id
      name
      created
    }
    configHash
    hostName
    serial
    uuid
    checkin
  }
}