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.
Data Types
The following are maximum values for Data Types:
- string - up to 255 characters, unless documented otherwise.
- text - 65,000 characters max
- integers - 32 bit (UIDs could be bigint/64 bit)
- time - numeric value in seconds from epoch
All characters are encoded in utf8.
Special characters are quoted, not escaped.
Strings are quoted by default.
https://your_subdomain.monitoringclient.com/v2.5/
Versioning
New API point versions will be released when new features require changes which are not backward compatible.
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.
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.
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 achieve.
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. |
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 required 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 |
GET https://your_subdomain.monitoringclient.com/v2.5/computers?page=1
Example Request
Example Headers
Change log
View the Change Log to keep up with API changes.
The Group Object
Attribute | Type | Description |
---|---|---|
uid | string | The unique identifier for the Group |
slug | string | The unique dashboard url slug for the Group |
name | string | The Group's name |
description | text | 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.
List Groups
Returns a list of Groups, 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. |
GET https://your_subdomain.monitoringclient.com/v2.5/groups
Example Request
Example Object
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.
GET https://your_subdomain.monitoringclient.com/v2.5/groups/[uid]
Example Request
Example Object
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.
POST https://your_subdomain.monitoringclient.com/v2.5/groups/find_or_create?api_key=This_Example_API_Key
Example Request
Example Object
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.
PUT https://your_subdomain.monitoringclient.com/v2.5/groups/[uid]
Example Request
Example Object
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 |
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.
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. |
GET https://your_subdomain.monitoringclient.com/v2.5/computers
Example Request
Example Object Example Request Limiting results by Group
Example Object Example Request - Filtering results by Platform
Example Object
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.
GET https://your_subdomain.monitoringclient.com/v2.5/computers/[watchman_id]
Example Request
Example Object
Update a Computer
Update the details of a Computer object.
Note: At present, only the following attributes are supported.
Param | Default | Purpose | Character Limit | Required |
---|---|---|---|---|
asset_id | nil | Asset ID assigned to the computer | 191 | No |
custom_name | nil | Name to display in place of the Computer Name | 191 | No |
description | nil | Descriptive text for the Computer | 65535 | No |
reference_email | nil | Reference email | 191 | No |
product_description | nil | Descriptive text for the Computer model | 65535 | No |
estimated_manufacture_date | nil | Estimated manufacture date | No | |
beacon_reporting | nil | Enable/disable beacon reporting | No | |
beacon_missing_threshold_in_minutes | 5 | Minutes before a warning sent. Allowed values are: 2, 5, 10, 15, 20, 15, and 30. | No | |
create_ticket_on_beacon_found | false | If set to true , an alert will be sent when computer comes online | No |
Returns a Computer Object if passed attributes pass validation.
Returns a 500 if passed attribute exceeds Character Limit.
PUT https://your_subdomain.monitoringclient.com/v2.5/computers/[watchman_id]
Example Request
Example Object
The Expiration Object
Attribute | Type | Description |
---|---|---|
uid | string | Unique identifier for the Expiration. |
license_key | string | The Expiration's license, serial number, or other identifier. |
expires_at | integer | The the date the license expires on. |
expiration_manufacturer | string | The UID of the expiration_manufacturer |
expiration_product | string | The UID of the expiration_product |
group | string | The UID of the Group. |
computer | string | The UID of the computer. |
renewable | boolean | Is the Expiration renewable |
notes | text | Any notes for this Expiration. |
created_at | integer | Date the Expiration was created. |
List Expirations
Returns a list of Expirations in the current subscription, sorted by expires_at in descending order.
Param | Default | Purpose |
---|---|---|
uid | nil | Unique identifier for the Expiration |
manufacturer | nil | Filter Expirations by manufacturer UID or slug. |
product | nil | Filter Expirations by product UID or slug. |
group | nil | Filter Expirations by Group UID or slug. |
computer | nil | Filter Expirations by computer UID or slug. |
license_key | nil | Filter Expirations by license_key. |
expires_at_start | nil | Filter Expirations by expires_at. Requires expires_at_end |
expires_at_end | nil | Filter Expirations by expires_at. Requires expires_at_start |
license_key | nil | Filter Expirations by renewable. |
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. |
GET https://your_subdomain.monitoringclient.com/v2.5/expirations
Example Request
Example Object
Retrieving an Expiration
Retrieves the details of an Expiration object.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the Expiration you are looking up. |
Returns an Expiration object if a valid identifier was provided, and returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.5/expirations/[uid]
Example Request
Example Object
Create an Expiration
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 |
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.
POST https://your_subdomain.monitoringclient.com/v2.5/expirations
Example Request
Example Object
Update an Expiration
Update the details of an Expiration object.
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 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 |
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.
PUT https://your_subdomain.monitoringclient.com/v2.5/expirations/[uid]
Example Request
Example Object
Delete an Expiration
Permanently deletes an Expiration. This cannot be undone.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the Expiration you are deleting. |
Returns a 204 no content
DELETE https://your_subdomain.monitoringclient.com/v2.5/expirations/[uid]
Example Request
The Expiration Manufacturer Object
Attribute | Type | Description |
---|---|---|
uid | string | Unique identifier for the Expiration Manufacturer |
slug | string | The dashboard url slug for the Expiration Manufacturer |
name | string | The name of the Expiration Manufacturer |
created_at | integer | Date created |
List Expiration Manufacturers
Returns a list of Expiration Manufactures in your account.
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. Set to 5 to start at record 6. |
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers
Example Request
Example Object
Retrieving an Expiration Manufacturer
Retrieves the details of an Expiration Manufacturer.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the Expiration you are looking up. |
Returns a Expiration Manufacturer object if a valid identifier was provided, and returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/[expiration uid]
Example Request
Example Object
Create an Expiration Manufacturer
Param | Default | Purpose | Character Limit | Required |
---|---|---|---|---|
name | string | The name of the Expiration Manufacturer | 191 | Yes |
Returns a Expiration Manufacturer object if passed attributes pass validation.
Returns a 500 if passed attribute exceeds Character Limit.
POST https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers
Example Request
Example Object
Update an Expiration Manufacturer
Update the details of an Expiration Manufacturer.
Param | Default | Purpose | Character Limit | Required |
---|---|---|---|---|
name | string | The name of the Expiration Manufacturer | 191 | Yes |
Returns a Expiration Manufacturer object if passed attributes pass validation.
Returns a 500 if passed attribute exceeds Character Limit.
PUT https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/[expiration uid]
Example Request
Example Object
Delete an Expiration Manufacturer
Permanently deletes an Expiration Manufacturer. This cannot be undone.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the Expiration you are deleting. |
Returns a 204 no content
DELETE https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/[expiration uid]
Example Request
The Expiration Product Object
Attribute | Type | Description |
---|---|---|
uid | string | Unique identifier for the Expiration Product |
slug | string | The dashboard url slug for the Expiration Product |
name | string | The name of the Expiration Product |
created_at | integer | Date created |
List Expiration Products
Returns a list of Expiration Products in your account.
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. Set to 5 to start at record 6. |
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_products
Example Request
Example Object
Retrieving an Expiration Product
Retrieves the details of an Expiration Product.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the Expiration you are looking up. |
Returns a Expiration Product object if a valid identifier was provided, and returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_products/[expiration uid]
Example Request
Example Object
Create an Expiration Product
Param | Default | Purpose | Character Limit | Required |
---|---|---|---|---|
name | string | The name of the Expiration Product | 191 | Yes |
Returns a Expiration Product object if passed attributes pass validation.
Returns a 500 if passed attribute exceeds Character Limit.
POST https://your_subdomain.monitoringclient.com/v2.5/expiration_products
Example Request
Example Object
Update an Expiration Product
Update the details of an Expiration Product.
Param | Default | Purpose | Character Limit | Required |
---|---|---|---|---|
name | string | The name of the Expiration Product | 191 | Yes |
Returns a Expiration Product object if passed attributes pass validation.
Returns a 500 if passed attribute exceeds Character Limit.
PUT https://your_subdomain.monitoringclient.com/v2.5/expiration_products/[expiration uid]
Example Request
Example Object
Delete an Expiration Product
Permanently deletes an Expiration Product. This cannot be undone.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the Expiration you are deleting. |
Returns a 204 no content
DELETE https://your_subdomain.monitoringclient.com/v2.5/expiration_products/[expiration uid]
Example Request
The Note Object
Attribute | Type | Description |
---|---|---|
uid | string | Unique identifier for the Note |
computer | string | 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 |
null
.
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. |
computer_id
OR group_id
, never both.
GET https://your_subdomain.monitoringclient.com/v2.5/notes
Example Request
Example Object
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
.
GET https://your_subdomain.monitoringclient.com/v2.5/notes/[uid]
Example Request
Example Object
Create a Note
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.
POST https://your_subdomain.monitoringclient.com/v2.5/notes
Example Request
Example Object
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.
PUT https://your_subdomain.monitoringclient.com/v2.5/notes/[uid]
Example Request
Example Object
Delete a Note
Permanently deletes a Note. This cannot be undone.
Param | Default | Purpose |
---|---|---|
uid | nil | The UID for the note you are deleting. |
Returns a 204 no content
DELETE https://your_subdomain.monitoringclient.com/v2.5/notes/[uid]
Example Request
The Plugin Result Object
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 |
GET https://your_subdomain.monitoringclient.com/v2.5/computers/[watchman_id]?api_key=This_Example_API_key&expand[]=plugin_results
Example Object
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
Returns a Plugin Result object if passed attributes pass validation.
PUT https://your_subdomain.monitoringclient.com/v2.5/plugin_results/[uid]
Example Request
Example Object
The User Object
Attribute | Type | Description |
---|---|---|
uid | string | The unique identifier for the User |
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") |
List Users
Returns a list of Users.
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. Set to 5 to start at record 6. |
GET https://your_subdomain.monitoringclient.com/v2.5/users
Example Request
Example Object
Retrieving a User
Retrieves the details of a User. Supply the unique User UID as described in the previous example to receive all details about the corresponding User.
Param | Default | Purpose |
---|---|---|
uid | n/a | The User UID for the User Record you are looking up. |
Returns a User Object If a valid User UID was provided, returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.5/users/[uid]
Example Request
Example Object
Create a User
Create a User. If the user already exists in our system, it will be added to this company.
Param | Type | Purpose | Length | Required |
---|---|---|---|---|
firstname | string | User's first name | 191 | Yes |
lastname | string | User's last name | 191 | Yes |
string | User's email | 191 | Yes | |
role | string | User's role in the company. Allowed values are: admin, employee, and end_user | 191 | Yes |
can_edit_contact_menu | boolean | If user has permission to edit contact menu (not required for admin role) | No | |
can_access_billing | boolean | If user has permission to edit contact menu (not required for admin role) | No | |
permitted_group_uids | array | List of Group UIDs user has access to (only available for end_user role) | No | |
restricted_group_uids | array | List of Group UIDs user does not have access to (only available for employee role) | No |
Returns the newly created User Object.
POST https://your_subdomain.monitoringclient.com/v2.5/groups/find_or_create?api_key=This_Example_API_Key
Example Request
Example Object