Jamf Pro API Patterns
Overview
WYRE's Jamf Pro sidecar exposes 45 tools over one Jamf Pro tenant per Conduit connection. Most read tools wrap the modern Jamf Pro API (paged, RSQL-filterable). A few wrap the older Classic API, which has no server-side search, so the sidecar filters those by name itself. Knowing which family a tool belongs to tells you how to page and filter it.
Connection and Authentication
Each Conduit connection holds one Jamf Pro API client (Settings → System → API Roles and Clients), entered once in the Conduit web UI (/connect/jamf). Conduit stores the fields and passes three headers to the sidecar. Nothing is set on the client, and Conduit drops any X-Jamf-* header a client sends:
| Conduit field | Header |
|---|---|
| Jamf Pro URL | X-Jamf-Base-Url |
| Client ID | X-Jamf-Client-Id |
| Client Secret | X-Jamf-Client-Secret |
The sidecar exchanges the client ID and secret for a short-lived bearer token, caches it, and retries once with a fresh token on HTTP 401. The base URL must be public https://. Private, loopback, and placeholder URLs are refused by both Conduit and the sidecar.
The API client's API Role is the real permission boundary. A tool that is listed can still fail with 403 if the role lacks the privilege. Use one API client per client tenant, scoped to the tiers that client needs.
One tenant per connection. If an MSP runs one Jamf Pro instance for several clients, those clients are usually separated by sites. Use jamf_list_sites, then scope by site (for example the computerFilter example general.site.name=="Contoso" that jamf_backup_check documents).
Tool Tiers and Gating
| Tier | Count | Sidecar default | Conduit requirement |
|---|---|---|---|
| read | 21 | on | read |
| write | 11 | on | write |
| admin | 13 | off | admin |
Two gates apply, and both must pass:
- The sidecar deployment lists only the tiers it enables. Admin is off unless the deployment turns it on.
- Conduit forwards only the tiers your access grant allows for Jamf Pro. A read grant forwards
read; a write grant forwardsread,write; an admin grant forwards all three. The sidecar intersects that with its own tiers. An empty result means no tools at all.
Conduit classifies all 45 Jamf tools at exactly the tier the sidecar declares, so the two gates agree. The write tier includes jamf_remove_computers_from_static_group. The admin tier is jamf_prepare_computer_lock, jamf_wipe_computer, jamf_unmanage_computer, jamf_delete_computer, jamf_lock_mobile_device, jamf_wipe_mobile_device, jamf_unmanage_mobile_device, jamf_delete_user, jamf_delete_computer_group, jamf_list_api_roles, jamf_list_api_integrations, jamf_create_api_role, and jamf_delete_api_role.
jamf_list_api_roles and jamf_list_api_integrations are reads that Conduit gates at admin because they expose API access configuration. jamf_prepare_computer_lock is flagged both write and admin in Conduit. It sends nothing to the device (it returns a console link for a human operator), but it still needs an admin grant and the sidecar's admin tier.
Every admin-tier tool except jamf_prepare_computer_lock requires "confirm": true. Set it only after the user has confirmed the exact action and target in this conversation.
Paging and Filtering
Jamf Pro API tools (paged)
jamf_search_computers, jamf_search_mobile_devices, jamf_search_users, jamf_get_patch_report, jamf_list_software_update_plans, jamf_list_computer_prestages, jamf_list_mobile_device_prestages, jamf_list_buildings, and jamf_list_departments take:
| Arg | Meaning |
|---|---|
page |
Zero-based page number. Default 0. |
pageSize |
1-200. Default 50 (100 for buildings and departments). |
sort |
Up to 5 entries like "general.name:asc" |
filter |
Raw RSQL, up to 2,000 characters |
Responses carry totalCount and results. Keep paging until you have read totalCount results before you call a list complete.
The search tools also take convenience args that the sidecar turns into RSQL and ANDs with filter. All support * wildcards:
jamf_search_computers:name,serialNumber,usernamejamf_search_mobile_devices:name,serialNumber,username,emailjamf_search_users:username,realname,email(e.g.email: "*@contoso.com")
RSQL examples from the sidecar's own tool descriptions: general.name=="MBP-*", version!="120.0" (patch report), device.deviceId=="42" (update plans). Jamf answers an unknown filter field with an HTTP 4xx error. Fall back to the convenience args or sort and page.
Classic API tools (sidecar-filtered)
jamf_list_policies has no paging. It takes contains (case-insensitive substring of the name) and limit (1-500, default 100), and returns totalMatched and returned. When totalMatched is larger than returned, narrow contains or raise limit.
jamf_list_computer_groups, jamf_list_mobile_device_groups, jamf_list_patch_titles, jamf_list_available_os_updates, and jamf_list_sites take no arguments and return everything.
Inventory sections
jamf_search_computers and jamf_get_computer take a sections array. Search defaults to GENERAL, HARDWARE, OPERATING_SYSTEM, USER_AND_LOCATION. Get adds DISK_ENCRYPTION and SECURITY. jamf_search_mobile_devices defaults to GENERAL, HARDWARE, USER_AND_LOCATION. Request only what you need: APPLICATIONS and PACKAGE_RECEIPTS are large.
Response Limits
- Each tool response is capped (60,000 characters by default) after redaction. Large pages with many sections get truncated. Lower
pageSizeor drop sections. - Responses are redacted before you see them: secret-named fields, recovery-key-shaped values, bearer tokens, and the caller's client secret are masked.
- IDs are numeric strings (
"42"). Path-like or non-numeric IDs are rejected before any call to Jamf. - Only arguments declared in a tool's schema reach Jamf. Extra arguments are dropped silently.
Errors
| Error text | Cause | What to do |
|---|---|---|
No Jamf Pro credentials on this request |
Conduit connection missing or incomplete | Reconnect Jamf Pro in Conduit |
rejected the access token ... after one retry (401) |
Client secret rotated or API client disabled | Update the Conduit connection |
denied ... (HTTP 403). The API client's role is missing the privilege |
API Role lacks a privilege | Add the privilege for that endpoint in Jamf |
returned 404 ... object not found |
Wrong id, or the record was deleted | Re-search, then retry with the new id |
rate-limited ... (HTTP 429). Retry after Ns. |
Jamf Pro throttling | Wait the stated seconds, then retry with smaller pages |
redirected ... refusing to follow |
Base URL points at a redirecting host | Use the canonical https://<org>.jamfcloud.com URL |
did not respond in time |
Jamf Pro slow or unreachable | Retry once, then narrow the query |
Unknown tool: <name> |
Tool not in your effective tiers | See Tool Tiers and Gating above |
Gotchas
- A missing tool is not a bug. Check the tier tables above before telling the user a capability doesn't exist.
jamf_backup_checkis not a backup check. Jamf Pro is not a backup product. The tool reports Jamf-native data-protection signals and says so in itsdisclaimer. Confirm actual backups in the backup product.jamf_get_computer_groupreturns current members for static and smart groups. Smart-group membership is criteria-driven, andjamf_add_computers_to_static_grouprefuses smart groups.
Related Skills
- device-compliance: fleet compliance and data-protection review
- patch-management: OS and third-party patch posture
- user-onboarding: new-hire users and device assignment
- device-offboarding: lost devices and departing users