Support for version 2.2 of the Watchman API will be discontinued Jan 1st, 2017. Please take whatever steps are necessary to ensure your integrations are updated to Version 2.5 before then.
For more information about the changes from V2.2 to V2.5 read the change log.
Getting Started
The Watchman Monitoring API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.
Base URL
All URLs referenced in the documentation use the same base with the desired API version number.
Times
Dates and times are sent in unix epoch. Times sent in plugin result objects will vary based on the accuracy of the monitored computer's clock.
Security and HTTPS
The REST API is served via HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
Rate Limiting
All requests are rate limited to 400/minute.
Base URL
https://your_subdomain.monitoringclient.com/v2.2/
Versioning
New API point version will be released any time new features require changes which are not backward compatible. The current version is 2.2. View the changelog and read more about API versions
Current Version
The current API version is 2.2 was released 20 Sep 2015.
Authentication
You authenticate to the Watchman Monitoring API by providing a valid API key in the api_key parameter of the request. Administrators can manage API keys by navigating to Settings > API, or in related Integration modal windows.
API keys carry all administrative privileges, be sure to keep them secret! API Keys can be reset at any time via the Dashboard
Expanding Objects
Many objects contain the ID of another object in their response properties. Those objects can be expanded inline by including an array of one or more keys in the expand request parameter.
This parameter is available on all API requests, and applies to the response of that request only.
GET https://your_subdomain.monitoringclient.com/v2.2/computers?api_key=This_Example_API_key&expand[]=plugin_results
Nested Expansion
Expansion requests can be nested with the dot property. For example, requesting computer.plugin_results on an Expiration will expand the computer property into a full computer object, and will then expand the plugin_results property on that computer into an array of plugin result objects.
GET https://your_subdomain.monitoringclient.com/v2.2/expirations?api_key=This_Example_API_key&expand[]=computer.plugin_results
Errors
Watchman Monitoring uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error an invalid request (e.g. a required parameter was missing, subdomain or api_key we invalid, etc.), and codes in the 5xx range indicate a failure, and should be reported.
Error Attributes
Attribute
Type
Description
status_code
integer
The HTTP response code
code
string
The Watchman Monitoring status code
title
string
The title of this error
details
string
The details of the error
attribute
string
This is only sent in the case of 422 :unprocessable_entity errors and reflects the attribute which failed validation.
HTTP Status Code Summary
Attribute
Description
200 OK
Everything worked as expected.
400 Bad Request
Often missing a required parameter.
401 Unauthorized
No valid API Key or Subscriber subdomain provided.
403 Forbidden
Valid subdomain and API key provided, but lacks permission to the requested item.
404 Not Found
The requested item doesn't exist.
422 Unprocessable Entity
There is a validation error on the object you are trying to create
500, 502, 503, 504 Server errors
an error was raised within the Watchman Monitoring server.
Codes
Attribute
Description
:missing_parameter
A require parameter is missing
:unpermitted_parameter
There is an unpermitted parameter in the object you are trying to create or update
Pagination
All top-level Watchman Monitoring API resources have support for bulk fetches — "list" API methods. For instance you can list computers and list groups.
Watchman Monitoring utilizes paged-based pagination, using the parameters page and per_page. Pass page to dictate what page in the list you would like to fetch, per_page to set the quantity of results, and offset to offset your results by a given number.
Param
Default
Purpose
page
1
The page number where you wish to begin.
per_page
50
The quantity per page in each request. Up to 100 can be returned per-request.
offset
nil
The number to offset the results by. Example: set to 5 to start at record 6
{"id":"g_ac21d783d9","slug":"test-group","name":"Test Group","description":"This is the Group's description","visible_computer_count":2,"hidden_computer_count":0,"created_at":1442024926}
List Groups
Returns a list of Groups you are monitoring. Groups are returned sorted by name.
Param
Default
Purpose
visibility
nil
Filter Groups by visibility. Options are: ["visible", "hidden"]
page
1
The page number where you wish to begin.
per_page
50
The quantity per page in each request. Up to 100 can be returned per-request.
offset
nil
The number to offset the results by. Set to 5 to start at record 6.
Definition GET https://your_subdomain.monitoringclient.com/v2.2/groups
[{"id":"g_ac21d783d9","slug":"test-group","name":"Test Group","description":"This is the Group's description","visible_computer_count":2,"hidden_computer_count":0,"created_at":1442024926,},{"id":"g_83a21d7cd9","slug":"blank","name":"[Blank]","description":"Sample Group description","visible_computer_count":1,"hidden_computer_count":0,"created_at":1442024926,},...]
Retrieving a Group
Retrieves the details of a Group. Supply the unique Group ID as described in the previous example to receive all details about the corresponding Group.
Param
Default
Purpose
id
n/a
The Group ID for the computer you are looking up.
Returns a Group Object If a valid Group ID was provided, returns an error otherwise.
Definition GET https://your_subdomain.monitoringclient.com/v2.2/groups/[watchman_group_id]
{"id":"g_ac21d783d9""slug":"test-group","name":"Test Group","description":"This is the Group's description","visible_computer_count":1,"hidden_computer_count":0,"created_at":1442024926}
The Computer Object
Attribute
Type
Description
id
string
Unique identifier for the Computer
watchman_id
string
The Watchman ID generated by the computer
description
text
Descriptive text for the Computer
agent_version
string
Version number for the installed agent
build_number deprecated
string
The build number of some outdated agents.
last_report
integer
Date of the last report to Watchman
created_at
integer
Date the computer first reported
group
string
The Group ID that this computer belongs to
computer_name
string
Computer's Computer Name
machine_name
string
Computer's Computer Name (deprecated)
custom_name
string
Computer's custom display name in the dashboard.
display_name
string
Computer's custom display name in the dashboard. (deprecated)
last_user
string
Last signed in user
serial_number
string
Computer's serial number
os_version
string
Operating system of the computer
model_identifier
string
Model Identifier of the computer
model_name
string
Model name of the computer
applecare_eligibility
boolean
AppleCare eligibility*
warranty_status
string
Warranty status*
estimated_purchase_date
integer
Estimated purchase date*
config_description
string
Computer configuration description*
ram_installed
string
Amount of RAM installed in the computer (human readable)
ram_installed_in_bytes
string
Amount of RAM installed in the computer (in bytes)
ram_speed
string
Type and speed of RAM chips accepted by this computer, if available
ram_upgradeable
boolean
Indicates if the computer is able to accept a RAM upgrade
ram_max_apple
string
Maximum RAM according to Apple, if available
ram_max_actual
string
Maximum RAM addressed by the computer, if available
installed_ram
string
Amount of RAM installed (deprecated)
boot_volume_capacity_in_bytes
integer
Boot Volume Capacity in Bytes for the computer
boot_volume_usage_in_bytes
integer
Boot Volume Usage in Bytes for the computer
boot_volume_capacity
string
Boot Volume Capacity for the computer
boot_volume_usage
string
Boot Volume Usage for the computer
boot_volume_usage_percent
decimal
Boot Volume Usage % for the computer
processor
string
Processor info for the computer
current_uptime
string
Last reported uptime for a computer
smc_version
string
SMC version
primary_ip
string
Internal IP
active_mac_address
string
The active (in use) MAC Address
system_mac_address
string
The system MAC Address
asset_id
string
Asset ID assigned to the computer
ard_field_1
string
ARD Field 1
ard_field_2
string
ARD Field 2
ard_field_3
string
ARD Field 3
ard_field_4
string
ARD Field 4
teamviewer_id
string
TeamViewer ID
teamviewer_release
string
TeamViewer Major Version (12, 13, 14, etc.)
teamviewer_unattended
boolean
True when TeamViewer is configured for unattended access
bomgar_url
string
Bomgar URL
logmein_url
string
LogMeIn URL
simplehelp_url
string
SimpleHelp URL
jss_computer_id
string
JSS computer ID
jss_url
string
JSS URL
munki_identifier
string
Munki ID
internal_notes
string
The internal notes for the record
public_notes
string
The public notes for the record
updates_enabled
boolean
Are updates enabled for the Watchman Agent
settings_enabled
boolean
Are settings enabled for the Watchman Agent
report_if_missing
boolean
Should Watchman warn if this computer stops reporting
report_missing_after
integer
Time in days before computer is considered missing
ignore_missing_until
integer
Ignore missing until after this day
rekey_requested
boolean
Has a re-key been requested
pending_removal
boolean
True once remote removal has been requested
agent_removed
boolean
True once the Watchman Agent has reported either remote or manual removal
has_issue
boolean
True when the computer is reporting errors
missing
boolean
True if the computer fails to reported within its missing interval (7 days by default)
hidden
boolean
Is the computer set to hidden in the Dashboard
platform
string
linux, mac, or windows
plugin_results
array
Optional array of the latest plugin results if you add &expand[]=plugin_results to your request
* Only included if GSX Integration is enabled.
* null values will be returned when a fact is unknown.
Example Object
{"id":"c_165f745e6b","watchman_id":"20140620-S994-7TXF1R","description":"This is the computer's description","agent_version":"6.6.3.650","last_update":1442026136,"last_report":"2014-10-13T11:12:51.000-05:00","created_at":1442025819,"group":"g_ac21d783d9","computer_name":"Jonathan's MacBook Pro","display_name":"Travel MacBook","last_user":"jonathan","serial_number":"A12BC345DEF6","os_version":"OS X 10.10 (14A343f)","model_identifier":"MacBookPro10,1","model_name":"MacBook Pro (Retina, Mid 2012)","applecare_eligibility":false,"warranty_status":"AppleCare Protection Plan","estimated_purchase_date":1393718400,"config_description":"MBP 15.4/2.3/8GB/256GB FLASH","ram_installed":"8 GB","ram_installed_in_bytes":"8589934592","ram_speed":"PC3-12800 DDR3 at 1600MHz","ram_upgradeable":true,"ram_max_apple":"16 GB","ram_max_actual":"32 GB","boot_volume_capacity_in_bytes":999695822848,"boot_volume_usage_in_bytes":270039891968,"boot_volume_capacity":"999.70 GB","boot_volume_usage":"270.04 GB","boot_volume_usage_percent":27.01,"processor":"Intel Core i7 2.3 GHz (4 core 1 processor)","current_uptime":"0 days, 23 hours, 55 mins","smc_version":"2.3f36","primary_ip":"11.11.11.95","active_mac_address":"a4:5e:60:cf:27:6b","system_mac_address":"a4:5e:60:cf:27:6b","asset_id":null,"ard_field1":"","ard_field2":"","ard_field3":"","ard_field4":"","teamviewer_id":"123456789","teamviewer_release":"10","teamviewer_unattended":null,"bomgar_url":null,"logmein_url":null,"simplehelp_url":null,"jss_computer_id":"","jss_url":"","munki_identifier":"","internal_notes":null,"public_notes":null,"updates_enabled":true,"settings_enabled":true,"report_if_missing":true,"report_missing_after":7,"ignore_missing_until":null,"rekey_requested":false,"pending_removal":false,"agent_removed":false,"has_issue":true,"missing":false,"hidden":false,"platform":"mac"}
List Computers
Returns a list of computers in the current subscription. Computer records are returned sorted by last_report, with the most recent computer appearing first.
Param
Default
Purpose
status
nil
Filter the computers by current status. Options are: ["visible", "hidden", "missing", "pending_rekey", "pending_removal", "has_muted_plugin"]
group_id
nil
Only return computers within this Group. You can use the Group's ID or slug*.
page
1
The page number where you wish to begin.
per_page
50
The quantity per page in each request. Up to 100 can be returned per-request.
offset
nil
The number to offset the results by. Set to 5 to start at record 6.
* Using the slug is not recommended as it will often change and can be unreliable.
Definition GET https://your_subdomain.monitoringclient.com/v2.2/computers
[{"id":"c_165f745e6b","watchman_id":"20140620-S994-7TXF1R","description":"This is the computer's description","agent_version":"6.6.3.650","last_update":1442026136,"last_report":"2014-10-13T11:12:51.000-05:00","created_at":1442025819,...},{"id":"c_615fe7465b","watchman_id":"20131127-DJ0R-P4NFDF","description":"Sample computer description","agent_version":"6.6.3.650","last_update":1442026136,"last_report":"2014-10-13T11:12:51.000-05:00","created_at":1442025819,...},...]
[{"id":"c_165f745e6b","watchman_id":"20140620-S994-7TXF1R","description":"This is the computer's description","agent_version":"6.6.3.650","last_update":1442026136,"last_report":"2014-10-13T11:12:51.000-05:00","created_at":1442025819,"group":"g_ac21d783d9",...},{"id":"c_615fe7465b","watchman_id":"20131127-DJ0R-P4NFDF","description":"Sample computer description","agent_version":"6.6.3.650","last_update":1442026136,"last_report":"2014-10-13T11:12:51.000-05:00","created_at":1442025819,"group":"g_ac21d783d9",...},...]
Retrieving a Computer
Retrieves the details of a computer object.
Param
Default
Purpose
id
nil
The Watchman ID for the computer you are looking up.
Returns a computer object if a valid identifier was provided, and returns an error otherwise.
Definition GET https://your_subdomain.monitoringclient.com/v2.2/computers/[watchman_id]
When creating an Expiration you must provide either a group_id or computer_id for the Expiration to be associated to. Expirations created for a given computer_id will automatically be related to the Group of the assigned computer.
Param
Default
Purpose
Required
license_key
string
The Expiration's license, serial number, or other identifier
Yes
expires_at
integer
The date the license expires on
Yes
expiration_manufacturer_id
string
The ID of the expiration_manufacturer
Yes
expiration_product_id
string
The ID of the expiration_product
Yes
group_id
string
The ID of the Group.
Yes*
computer_id
string
The ID of the computer.
Yes*
renewable
boolean
Is the Expiration renewable
No
notes
text
Any notes for this Expiration.
No
* You only need to specify ONE of group_id or computer_id to associate the Expiration to a computer or Group. Both attributes are not required.
Returns an Expiration object if passed attributes pass validation.
Definition POST https://your_subdomain.monitoringclient.com/v2.2/expirations
The Expiration's license, serial number, or other identifier
Yes
expires_at
integer
The date the license expires on
Yes
expiration_manufacturer_id
string
The ID of the expiration_manufacturer
Yes
expiration_product_id
string
The ID of the expiration_product
Yes
group_id
string
The ID of the Group.
Yes*
computer_id
string
The ID of the computer.
Yes*
renewable
boolean
Is the Expiration renewable
No
notes
text
Any notes for this Expiration.
No
* You only need to specify ONE of group_id or computer_id to associate the Expiration to a computer or Group. Both attributes are not required.
Returns an Expiration object if passed attributes pass validation.
Definition PUT https://your_subdomain.monitoringclient.com/v2.2/expirations/[expiration_id]
Example Request
curl https://your_subdomain.monitoringclient.com/v2.2/expirations/e_614b9d8c41?api_key=This_Example_API_Key \-d expiration[notes]=These are some notes
Example Object
{"id":"e_614b9d8c41","license_key":"A12BC345DEF6","expires_at":null,"expiration_manufacturer":"em_e77660913d","expiration_product":"ep_8a6cf51252","computer":"c_165f745e6b","group":"g_ac21d783d9","renewable":false,"notes":"These are some notes","created_at":1441209663}
Delete an Expiration
Permanently deletes an Expiration. This cannot be undone.
True when note is included in Computer/Group Status Reports
* A Note object will contain either a computer or a Group, the other will be null.
Example Object
{"id":"n_70ab8b7f04","computer":"c_812666945e","group":"g_713e78ad3a","body":"This is the note's content.","created_at":1453135662,"private":false,"include_in_email":false,"include_in_report":false}
List Notes
Returns a list of Notes. If computer_id and group_id are left blank, all notes in your account will be returned.
Param
Default
Purpose
computer_id
null
The ID of the computer whose notes you wish to retrieve.*
group_id
null
The ID of the Group whose notes you wish to retrieve.*
include_private
false
Set to true (true, yes, or 1) if you wish to include private notes in your results.
page
1
The page number where you wish to begin.
per_page
50
The quantity per page in each request. Up to 100 can be returned per-request.
offset
nil
The number to offset the results by. Set to 5 to start at record 6.
* Send only computer_id OR group_id, never both.
Definition GET https://your_subdomain.monitoringclient.com/v2.2/notes
[{"id":"n_c6a844020d","computer":"c_cc342c6cc0","group":null,"body":"This is the note's content.","created_at":1453135662,"private":false,"include_in_email":false,"include_in_report":true},{"id":"n_3e412d7744","computer":"c_cc342c6cc0","group":null,"body":"The content of this note.","created_at":1453135662,"private":false,"include_in_email":true,"include_in_report":false},...]
Retrieving a Note
Retrieves the details of a Note.
Param
Default
Purpose
id
nil
The ID for the Note you are looking up.
Returns a Note object if a valid identifier was provided, and returns an error otherwise. A Note object will contain either a computer or a Group, the other will be null.
Definition GET https://your_subdomain.monitoringclient.com/v2.2/notes/[note_id]
{"id":"n_3e412d7744","computer":"c_cc342c6cc0","group":null,"body":"The content of this note.","created_at":1453135662,"private":false,"include_in_email":true,"include_in_report":false}
Create a Note
About Note ownership.
When creating a Note you must provide either a group_id or computer_id for the Note to be associated to. Sending both a group_id AND computer_id will result in an error.
Param
Type
Purpose
Required
computer_id
string
The ID of the Computer to which the note will be assigned.
Yes*
group_id
string
The ID of the Group to which the note will be assigned.
Yes*
body
string
The text content of the note.
Yes
private
boolean
Sets the privacy of the note. Default: false
No
include_in_email
boolean
Sets whether the note is visible in emails. Default: false
No
include_in_report
boolean
Sets whether the note is visible in emails. Default: false
No
* Either computer_id OR group_id is required, but never both.
Returns a Note object if passed attributes pass validation.
Definition POST https://your_subdomain.monitoringclient.com/v2.2/notes
Example Request
curl https://your_subdomain.monitoringclient.com/v2.2/notes/?api_key=This_Example_API_Key \-d note[computer_id]=c_cc342c6cc0 \-d note[body]="This is the note content."\-d note[include_in_email]=true
Example Object
{"id":"n_2f985c3224","computer":"c_cc342c6cc0","group":null,"body":"This is the note content.","created_at":1453411465,"private":false,"include_in_email":true,"include_in_report":false}
Update a Note
Update the details of a Note.
Param
Default
Purpose
Required
computer_id
string
The ID of the Computer to which the note will be assigned.
No
group_id
string
The ID of the Group to which the note will be assigned.
No
body
string
The text content of the note.
No
private
boolean
Sets the privacy of the note.
No
include_in_email
boolean
Sets whether the note is visible in emails.
No
include_in_report
boolean
Sets whether the note is visible in emails.
No
As with Creating a Note, supplying both a computer_id AND group_id will result in an error.
Returns a Note object if passed attributes pass validation.
Definition PUT https://your_subdomain.monitoringclient.com/v2.2/notes/[note_id]
Plugin results are returned with their related Computer Records.
Param
Default
Purpose
id
integer
The unique ID for the plugin result
name
string
Name of the plugin
slug
string
Slug for the plugin
status
string
Current reported status: [OK, Warning, Alert, Informational]
details
text
The plugins reported details
last_run
integer
The last time the plugin ran
muted
boolean
Whether or not the plugin is muted
mute_type
string
The type of mute in place: ["muted_forever", "timed_mute", "ticket_muted"]
mute_description
string
A brief description of the mute Only included if plugin is muted
ticket_number
string
The ticket number for this mute Only included if plugin mute type is "ticket_muted"
ticket_url
string
The url to the ticket Only included if plugin mute type is "ticket_muted"
mute_until
integer
The date this plugin is muted until Only included if plugin mute type is "time_muted"
Example Object
{"id":224285,"name":"Monitoring Agent","slug":"monitoring-agent","status":"OK","details":"The internal check of the Watchman Monitoring software reports no issues.","last_run":1372324943,"muted":true,"mute_type":"timed_mute","mute_description":"Plugin is muted until Sep 27th 2013.","muted_until":1380258000}
