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.
Data Types
The following are maximum values for Data Types:
string - up to 255 characters, unless documented otherwise.
All characters are encoded in utf8.
Special characters are quoted, not escaped.
Strings are quoted by default.
Base URL
https://your_subdomain.monitoringclient.com/v2.5/
Stay Up-to-Date
Subscribe to our newsletters to receive news, release notes, and status updates.
Versioning
New API point versions will be released when new features require changes which are not backward compatible.
Current Version
The current API version is 2.5 was released in November 2016.
Authentication
Authentication to the Watchman Monitoring API is performed by providing a valid API key in the api_key parameter of each request. Administrators can manage API keys by navigating to Settings > API.
Note that each API keys grants all administrative privileges! API Keys can be revoked and regenerated at any time by administrators in your account.
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.5/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.5/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 and 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.). Responses in the 5xx range indicate a failure, and will be forwarded to our team for review. If you are receiving an errors, please contact our support team with the error message, time the message was received, and a description of the outcome you trying to acheive.
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 Computer Records 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.
The returned HTTP headers of any API request show current page status, including X-Next-Page, X-Total record count, and X-Total-Pages total page count.
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
Definition GET https://your_subdomain.monitoringclient.com/v2.5/computers?page=1
Optional descriptive text for the Group, will be included in warnings.
group_url
string
Complete URL to group in the Dashboard
reference_email
string
Reference email
contact_email deprecated
string
Alias for reference_email
hidden
boolean
Is the Group hidden?
show_contact_menu
boolean
Should the Group show the contact menu?
visible_computer_count
integer
The count of visible computers
hidden_computer_count
integer
The count of hidden computers
mac_installer_ready
boolean
Is the Group-Specific installer ready for macOS? (Typically within 20 seconds of Group creation)
mac_installer_url
string
Download URL for macOS installer (pkg)
windows_installer_ready
boolean
Is the Group-Specific installer ready for Windows? (Typically within 60 seconds of Group creation)
windows_installer_url
string
Download URL for Windows installer (msi)
created_at
integer
The date the Group was created
Group-Specific installers are "thin" installers. This package URL will reflect any custom package name, which is editable as a part of our Custom Branding. They are smaller than traditional installers and require an active internet connection. These "shill installers" set the desired Group name, then download the latest version of the full installer from our servers.
[{"contact_email":null,"created_at":1504211891,"description":"This is the Group's Description","hidden":false,"hidden_computer_count":0,"mac_installer_ready":false,"mac_installer_url":"https://monitoringclient.s3.amazonaws.com/SubscriberInstallers/ors/MonitoringClient-group-name.pkg","name":"[Blank]","reference_email":null,"show_contact_menu":true,"slug":"blank","uid":"g_56257078ed","visible_computer_count":2,"windows_installer_ready":false,"windows_installer_url":"https://monitoringclient.s3.amazonaws.com/SubscriberInstallers/ors/MonitoringClient-group-name.msi"},{"contact_email":"hello@example.com","created_at":1515536395,"description":"Example Group","hidden":false,"hidden_computer_count":1,"mac_installer_ready":false,"mac_installer_url":"https://monitoringclient.s3.amazonaws.com/SubscriberInstallers/ors/MonitoringClient-group-name.pkg","name":"Example Group","reference_email":null,"show_contact_menu":true,"slug":"example-group","uid":"g_a7b330ed88","visible_computer_count":1,"windows_installer_ready":false,"windows_installer_url":"https://monitoringclient.s3.amazonaws.com/SubscriberInstallers/ors/MonitoringClient-group-name.msi"}]
Retrieving a Group
Retrieves the details of a Group. Supply the unique Group UID as described in the previous example to receive all details about the corresponding Group.
Param
Default
Purpose
uid
n/a
The Group UID for the Computer Record you are looking up.
Returns a Group Object If a valid Group UID was provided, returns an error otherwise.
Definition GET https://your_subdomain.monitoringclient.com/v2.5/groups/[uid]
{"uid":"g_ac21d783d9""slug":"test-group","name":"Test Group","description":"This is the Group's description","reference_email":"hello@example.com","hidden":false,"show_contact_menu":true,"visible_computer_count":1,"hidden_computer_count":0,"mac_installer_ready":true,"mac_installer_url":"https://your_subdomain.monitoringclient.com/path/to/MonitoringClient-group-name.pkg","windows_installer_ready":false,"windows_installer_url":"https://your_subdomain.monitoringclient.com/path/to/MonitoringClient-group-name.msi","created_at":1442024926}
Find or Create a Group
Find or Create a Group based on Group Name.
Param
Type
Purpose
Length
Required
name
string
The Group's Name
255
Yes
description
string
The Group's Description
65535
No
show_contact_menu
boolean
The Group's Contact Menu visibility. Default value is defined per-Company.
No
build_installers
boolean
Optional param to build installers if creating a new Group. Defaults to false.
No
Returns an existing Group Object if one is found, otherwise will return a new Group Object, based on the name that is passed.
Definition POST https://your_subdomain.monitoringclient.com/v2.5/groups/find_or_create?api_key=This_Example_API_Key
Example Request
curl https://your_subdomain.monitoringclient.com/v2.5/groups/find_or_create?api_key=This_Example_API_Key \-d group[name]="Test Group"\-d group[description]="This is the Group's description"\-d group[show_contact_menu]=true-d group[build_installers]=false
Example Object
{"uid":"g_ac21d783d9""slug":"test-group","name":"Test Group","description":"This is the Group's description","reference_email":"hello@example.com","hidden":false,"show_contact_menu":true,"visible_computer_count":1,"hidden_computer_count":0,"mac_installer_ready":true,"mac_installer_url":"https://your_subdomain.monitoringclient.com/path/to/MonitoringClient-group-name.pkg","windows_installer_ready":false,"windows_installer_url":"https://your_subdomain.monitoringclient.com/path/to/MonitoringClient-group-name.msi","created_at":1442024926}
Update a Group
Update the details of a Group.
Param
Default
Purpose
Character Limit
Required
name
string
The Group's Name
255
Yes
description
string
The Group's Description
65535
No
reference_email
string
Reference email
191
No
show_contact_menu
boolean
Optional param to set the Group's Contact Menu visibility during creation.
No
Returns a Group object if passed attributes pass validation.
Definition PUT https://your_subdomain.monitoringclient.com/v2.5/groups/[uid]
Example Request
curl -X PUT --header"Content-Type: application/x-www-form-urlencoded"\-dapi_key="This_Example_API_Key"\-d group[name]="Accounting Department"\-d group[description]="About the accounting Group"\-d group[reference_email]="hello@example.com"\-d group[show_contact_menu]=true\
https://your_subdomain.monitoringclient.com/v2.5/groups/g_ac21d783d9
Example Object
{"uid":"g_ac21d783d9""slug":"accounting-department","name":"Accounting Department","description":"About the accounting Group","reference_email":"hello@example.com","hidden":false,"show_contact_menu":true,"visible_computer_count":1,"hidden_computer_count":0,"mac_installer_ready":true,"mac_installer_url":"https://your_subdomain.monitoringclient.com/path/to/MonitoringClient-group-name.pkg","windows_installer_ready":false,"windows_installer_url":"https://your_subdomain.monitoringclient.com/path/to/MonitoringClient-group-name.msi","created_at":1442024926}
The Computer Object
Attribute
Type
Description
uid
string
Unique identifier for the Computer
client_id
string
The Client ID generated by the computer
watchman_id deprecated
string
Deprecated in favor of client_id
description
text
Descriptive text for the Computer Record, will be included in warnings.
agent_version
string
Version number for the installed agent
build_number deprecated
string
Deprecated in favor of agent_version
last_report
integer
Date of the last report to Watchman Monitoring, in seconds since epoch.
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
custom_name
string
Computer's custom display name in the dashboard
computer_url
string
Complete URL to computer record in the Dashboard
reference_email
string
Reference email as stored on the Computer Record, or its Group
contact_email deprecated
string
Deprecated in favor of reference_email
reference_email_computer
string
Reference email as stored on the Computer Record
reference_email_group
string
Reference email as stored on the Group Record
last_user
string
Last signed in user
serial_number
string
Computer's serial number
os_version
string
Operating System of the Computer
os_version_number
string
Operating System Number of the Computer
os_version_number_max
string
The most recent compatible Operating System the computer can support.**
model_identifier
string
Model Identifier of the computer
model_name
string
Model name of the computer
apple_product_description deprecated
string
Deprecated in favor of product_description
product_description
string
Model name of the computer, editable
estimated_manufacture_date
integer
Estimated Manufacturer Date
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
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
mac, linux, or windows
plugin_results
array
Optional array of the latest plugin results if you add &expand[]=plugin_results to the request
beacon_reporting
boolean
Is beacon reporting enabled
beacon_missing_threshold_in_minutes
integer
Minutes before a warning sent
create_ticket_on_beacon_found
boolean
If an alert will be sent when computer comes online
Note:null values will be returned when a fact is unknown.
* Only included if GSX Integration is enabled.
** os_version_number_max will return 0.0.0 when the computer can support the lastest released Operating System.
Example Object
{"uid":"c_165f745e6b","client_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","custom_name":"Travel MacBook","computer_url":"https://ors.monitoringclient.com/computers/20140620-S994-7TXF1R","reference_email":"hello@example.com","last_user":"jonathan","serial_number":"A12BC345DEF6","os_version":"OS X 10.10.1 (14A343f)","os_version_number":"10.10.1","os_version_number_max":"10.12.1","model_identifier":"MacBookPro10,1","model_name":"MacBook Pro (Retina, Mid 2012)","applecare_eligibility":false,"warranty_status":"AppleCare Protection Plan","apple_product_description":"MacBook Pro (Retina, Mid 2012)","product_description":"MacBook Pro (Retina, Mid 2012)","estimated_manufacture_date":1393718400,"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","beacon_reporting":true,"beacon_missing_threshold_in_minutes":10,"create_ticket_on_beacon_found":true}
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, and has_muted_plugin
group_id
nil
Only return computers within this Group. You can use the Group's UID or slug*.
created_after
nil
Only return computers which are created after this date. Dates are in YYYY-MM-DD format. E.g., 2018-12-25.
serial_number
nil
Filter computers by Serial Number.
asset_id
nil
Filter computers by Asset ID.
reference_email_computer
nil
Filter computers by reference email address for computer(s).
reference_email_group
nil
Filter computers by reference email address for group.
reference_email
nil
Filter computers by reference email address, searching both computer and group reference email addresses.
platform
nil
Filter computers by platform. Options are: linux, mac, windows
order
last_reported_desc
Order of computers. Options are: reported_desc and created_desc
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.5/computers
[{"uid":"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,...},{"uid":"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,...},...]
[{"uid":"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",...},{"uid":"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",...},...]
[{"uid":"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":"2019-10-13T11:12:51.000-05:00","created_at":1442025819,"platform":"mac",...},{"uid":"c_615fe7465b","watchman_id":"20131127-DJ0R-P4NFDF","description":"Sample computer description","agent_version":"6.6.3.650","last_update":1442026136,"last_report":"2019-10-13T11:12:51.000-05:00","created_at":1442025819,"platform":"windows",...},...]
Retrieving a Computer
Retrieves the details of a computer object.
Param
Default
Purpose
watchman_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.5/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
Character Limit
Required
license_key
string
The Expiration's license, serial number, or other identifier
191
Yes
expires_at
integer
The date the license expires on
Yes
expiration_manufacturer_id
string
The UID of the expiration_manufacturer
191
Yes
expiration_product_id
string
The UID of the expiration_product
191
Yes
group_id
string
The UID of the Group.
191
Yes*
computer_id
string
The UID of the computer.
191
Yes*
renewable
boolean
Is the Expiration renewable
No
notes
text
Any notes for this Expiration.
65535
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.
Returns a 500 if passed attribute exceeds Character Limit.
Definition POST https://your_subdomain.monitoringclient.com/v2.5/expirations
The Expiration's license, serial number, or other identifier
191
Yes
expires_at
integer
The date the license expires on
Yes
expiration_manufacturer_id
string
The ID of the expiration_manufacturer
191
Yes
expiration_product_id
string
The ID of the expiration_product
191
Yes
group_id
string
The ID of the Group.
191
Yes*
computer_id
string
The ID of the computer.
191
Yes*
renewable
boolean
Is the Expiration renewable
No
notes
text
Any notes for this Expiration.
65535
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.
Returns a 500 if passed attribute exceeds Character Limit.
Definition PUT https://your_subdomain.monitoringclient.com/v2.5/expirations/[uid]
Example Request
curl -X PUT https://your_subdomain.monitoringclient.com/v2.5/expirations/e_614b9d8c41?api_key=This_Example_API_Key \-d expiration[notes]=These are some notes
Example Object
{"uid":"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.
The UID of the computer to which the note belongs.*
group
string
The UID of the Group to which the note belongs.*
body
string
The body content of the note
created_at
integer
Date created
private
boolean
True when the note is only internally visible
include_in_email
boolean
True when note is included in emails
included_in_report
boolean
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
{"uid":"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
null
The UID of the computer whose notes you wish to retrieve.*
group
null
The UID 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.5/notes
[{"uid":"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},{"uid":"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
uid
nil
The UID 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.5/notes/[uid]
{"uid":"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
Character Limit
Required
computer_id
string
The UID of the Computer to which the note will be assigned.
191
Yes*
group_id
string
The UID of the Group to which the note will be assigned.
191
Yes*
body
text
The text content of the note.
16777215
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.
Returns a 500 if passed attribute exceeds Character Limit.
Definition POST https://your_subdomain.monitoringclient.com/v2.5/notes
Example Request
curl https://your_subdomain.monitoringclient.com/v2.5/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
{"uid":"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
Character Limit
Required
computer_id
string
The UID of the Computer to which the note will be assigned.
191
No
group_id
string
The UID of the Group to which the note will be assigned.
191
No
body
text
The text content of the note.
16777215
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.
Returns a 500 if passed attribute exceeds Character Limit.
Definition PUT https://your_subdomain.monitoringclient.com/v2.5/notes/[uid]
Example Request
curl -X PUT https://your_subdomain.monitoringclient.com/v2.5/notes/n_2f985c3224?api_key=This_Example_API_Key \-d note[body]="Updated note content."\-d note[private]=true
Plugin Results are returned with their related Computer Records. Within Watchman Monitoring there is a concept of "service plugins". These show in Plugin Results with visible set to false. They would not be displayed in the Dashboard and should be hidden in any alternate UI you build for your users.
Note: In former versions of the API the slug was being passed as the id. In version 2.5 and above, the slug and uid are different attributes.
Param
Default
Purpose
uid
string
The unique UID 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"
visible
boolean
The visible state of service plugins
Definition GET https://your_subdomain.monitoringclient.com/v2.5/computers/[watchman_id]?api_key=This_Example_API_key&expand[]=plugin_results
Example Object
{"uid":"pr_28d2c37b9a","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,"visible":true}
Mute a Plugin Result
Mute a plugin result by days or by a ticket ID.
Param
Default
Purpose
mute_type
string
Mute type. Available values are ignored, timed, ticket, and none. Passing none will clear all existing mutes.
mute_until
integer
Unix timestamp in future when a timed mute will expire. Required if mute_type is timed
ticket_number
string
Ticket number. Required if mute_type is ticket
ticket_url
string
Ticket URL. Optional when mute_type is timed or ticket
Note: A ticket system must be activated to send ticket as a mute_type. i.e. Autotask, Zendesk
Definition PUT https://your_subdomain.monitoringclient.com/v2.5/plugin_results/[uid]
Example Request
curl -X PUT https://your_subdomain.monitoringclient.com/v2.5/plugin_results/pr_28d2c37b9a?api_key=This_Example_API_Key \-d plugin_result[mute_type]="timed"\-d plugin_result[mute_until]=1380258000
Example Object
{"uid":"pr_28d2c37b9a","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}
The User Object
Attribute
Type
Description
uid
string
The unique identifier for the User
email
string
User's email address
firstname
string
First name
lastname
string
Last name
tfa_status
boolean
Does User has two-factor authentication enabled?
role
string
User's role in the company
can_edit_contact_menu
boolean
Can the User edit contact-menu?
can_access_billing
boolean
Does the User have access to billing?
last_subdomain
string
Subdomain of the company user accessed last
last_signin
integer
User's last sign-in time
created_at
integer
The date the User was created
restricted_group_uids
integer
Groups that can't be accessed by User (only available if user's role is "employee")
permitted_group_uids
integer
Groups that can be accessed by User (only available if user's role is "end_user")
