Errors
After making the call to apiutil, your script can check the value of the "$?" exit code shell variable. If the exit code is 0, apiutil did not report any errors. If it's 1, an error occurred.
If there's an error, the utility will return a message to stderr and you'll see it in your terminal output.
% apiutil --path "/api/v1/nosuch"
GET httpStatusCode: 404In scripts, however, stderr isn't going to be saved to a variable by default. You have to ask for it. The construct 2>&1 at the end of a command tells the shell to redirect stderr to stdout.
#!/bin/bash
# The output of this script will be "GET httpStatusCode: 404"
JSON=$(apiutil --path "/api/v1/nosuch" 2>&1)
echo "Return code: $?"
echo "$JSON"
# Output will be:
# Return code: 1
# GET httpStatusCode: 404"This script reads a mobile device group, parses the device IDs from the returned JSON using jq, and prints out the number of devices in the group. Note the "Check for errors" following the API call:
#!/bin/sh
# Gets a list of devices belonging to a given group
# The Jamf Pro API returns object data in JSON format.
# The JSON data is parsed using jq, a command line program that comes pre-installed with modern version of macOS.
# The $? variable is checked to see if an API error occurred.
TARGET="pro"
GROUP_NAME="students"
PATH="/JSSResource/mobiledevicegroups/name/${GROUP_NAME}"
# Make an API call
group_json=$(apiutil --target "$TARGET" --path "$PATH" 2>&1)
LAST_STATUS=$? # Capture the exit code to a variable.
# Check for error
if [[ ${LAST_STATUS} -ne 0 ]]; then
echo "❌ Error. The API returned:"
echo "${group_json}"
exit ${LAST_STATUS}
fi
# If we're still running, then the API call worked.
# Extract the device IDs from the JSON into an array
device_ids=($(jq '.mobile_device_group.mobile_devices[].id' <<< "$group_json"))
if [ ${#device_ids[@]} -eq 0 ]; then
echo "⚠️ No devices found in group: $GROUP_NAME"
exit 9
fi
echo "✅ Found ${#device_ids[@]} devices"
If we have a group called "students" with two members, the script will output:
✅ Found 2 devicesBut if we tried to look up a group name that doesn't exist, the script will return:
❌ Error running apiutil. The API returned:
GET httpStatusCode: 404
Most API errors are going to be things that were returned by your server instance but there are a couple of cases where you might get an error generated by the API Utility.
For Jamf Pro, all paths need to start with /JSSResource or /api. If yours doesn't, the app won't bother sending the request. It will just return an error immediately. HTTP Status 404 means "Not found."
$ apiutil --target "mytarget" --path "/computer-groups"
Unrecognized endpoint: '/computer-groups'. Failed with status code: 404
$ echo $?
1If you only have one target set up in API Util, you don't need to specify it when you make an API call. But if you have more than one target, you do. In this example, the developer has a couple targets available but didn't specify which one they wanted.
$ PATH="/JSSResource/no-such-path"
$ apiutil --path "${PATH}"
more than one environment found. Please specify one using the --target flag
$ echo $?
1