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.

Base URL
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.

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 achieve.

Error Attributes

AttributeTypeDescription
status_codeintegerThe HTTP response code
codestringThe Watchman Monitoring status code
titlestringThe title of this error
detailsstringThe details of the error
attributestringThis is only sent in the case of 422 :unprocessable_entity errors and reflects the attribute which failed validation.
HTTP Status Code Summary
AttributeDescription
200 OKEverything worked as expected.
400 Bad RequestOften missing a required parameter.
401 UnauthorizedNo valid API Key or Subscriber subdomain provided.
403 ForbiddenValid subdomain and API key provided, but lacks permission to the requested item.
404 Not FoundThe requested item doesn't exist.
422 Unprocessable EntityThere is a validation error on the object you are trying to create.
500, 502, 503, 504 Server errorsAn error was raised within the Watchman Monitoring server.


Codes
AttributeDescription
:missing_parameterA required parameter is missing.
:unpermitted_parameterThere 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.


Parameters
ParamDefaultPurpose
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe 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

Example Request
        curl -I https://your_subdomain.monitoringclient.com/v2.5/computers?page=1&api_key=This_Example_API_Key
      

Example Headers
HTTP/1.1 200 OK
access-control-allow-origin: *
cache-control: max-age=0, private, must-revalidate
content-length: 33853
content-type: application/json
set-cookie: SERVERID=; Expires=Thu, 01-Jan-1970 00:00:01 GMT; path=/; Secure
strict-transport-security: max-age=31536000; includeSubDomains
x-next-page: 2
x-offset: 0
x-page: 1
x-per-page: 50
x-prev-page:
x-rack-cors: miss; no-origin
x-request-id: 101ca44f-269e-418f-9af5-ef309b48feb6
x-runtime: 0.435463
x-total-pages: 28
x-total: 1379
      
 

Change log

View the Change Log to keep up with API changes.

   

The Group Object

AttributeTypeDescription
uidstringThe unique identifier for the Group
slugstringThe unique dashboard url slug for the Group
namestringThe Group's name
descriptiontextOptional descriptive text for the Group, will be included in warnings.
group_urlstringComplete URL to group in the Dashboard
reference_emailstringReference email
contact_email deprecatedstringAlias for reference_email
hiddenbooleanIs the Group hidden?
show_contact_menubooleanShould the Group show the contact menu?
visible_computer_countintegerThe count of visible computers
hidden_computer_countintegerThe count of hidden computers
mac_installer_readybooleanIs the Group-Specific installer ready for macOS? (Typically within 20 seconds of Group creation)
mac_installer_urlstringDownload URL for macOS installer (pkg)
windows_installer_readybooleanIs the Group-Specific installer ready for Windows? (Typically within 60 seconds of Group creation)
windows_installer_urlstringDownload URL for Windows installer (msi)
created_atintegerThe 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.

Example Object
{
  "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",
  "group_url": "https://ors.monitoringclient.com/groups/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"
}
      
 

List Groups

Returns a list of Groups, sorted by name.


Parameters
ParamDefaultPurpose
visibilitynilFilter Groups by visibility. Options are:
["visible", "hidden"]
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe number to offset the results by. Set to 5 to start at record 6.
Definition
GET https://your_subdomain.monitoringclient.com/v2.5/groups

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/groups?page=1&api_key=This_Example_API_Key
      
Example Object
[
  {
    "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.

Parameters
ParamDefaultPurpose
uidn/aThe Group UID for the Computer Record you are looking up.
Response

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]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/groups/test-group?api_key=This_Example_API_Key
      
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
}
      
 

Find or Create a Group

Find or Create a Group based on Group Name.

Parameters
ParamTypePurposeLengthRequired
namestringThe Group's Name255Yes
descriptionstringThe Group's Description65535No
show_contact_menubooleanThe Group's Contact Menu visibility. Default value is defined per-Company.No
build_installersbooleanOptional param to build installers if creating a new Group. Defaults to false.No
Response

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.

Parameters
ParamDefaultPurposeCharacter LimitRequired
namestringThe Group's Name255Yes
descriptionstringThe Group's Description65535No
reference_emailstringReference email191No
show_contact_menubooleanOptional param to set the Group's Contact Menu visibility during creation.No
Response

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" \
-d api_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

AttributeTypeDescription
uidstringUnique identifier for the Computer
client_idstringThe Client ID generated by the computer
watchman_id deprecatedstringDeprecated in favor of client_id
descriptiontextDescriptive text for the Computer Record, will be included in warnings.
agent_versionstringVersion number for the installed agent
build_number deprecatedstringDeprecated in favor of agent_version
last_reportintegerDate of the last report to Watchman Monitoring, in seconds since epoch.
created_atintegerDate the computer first reported
groupstringThe Group ID that this computer belongs to
computer_namestringComputer's Computer Name
custom_namestringComputer's custom display name in the dashboard
computer_urlstringComplete URL to computer record in the Dashboard
reference_emailstringReference email as stored on the Computer Record, or its Group
contact_email deprecatedstringDeprecated in favor of reference_email
reference_email_computerstringReference email as stored on the Computer Record
reference_email_groupstringReference email as stored on the Group Record
last_userstringLast signed in user
serial_numberstringComputer's serial number
os_versionstringOperating System of the Computer
os_version_numberstringOperating System Number of the Computer
os_version_number_maxstringThe most recent compatible Operating System the computer can support.**
model_identifierstringModel Identifier of the computer
model_namestringModel name of the computer
apple_product_description deprecatedstringDeprecated in favor of product_description
product_descriptionstringModel name of the computer, editable
estimated_manufacture_dateintegerEstimated Manufacturer Date
applecare_eligibilitybooleanAppleCare eligibility*
warranty_statusstringWarranty status*
estimated_purchase_dateintegerEstimated purchase date*
config_descriptionstringComputer configuration description*
ram_installedstringAmount of RAM installed in the computer (human readable)
ram_installed_in_bytesstringAmount of RAM installed in the computer (in bytes)
ram_speedstringType and speed of RAM chips accepted by this computer, if available
ram_upgradeablebooleanIndicates if the computer is able to accept a RAM upgrade
ram_max_applestringMaximum RAM according to Apple, if available
ram_max_actualstringMaximum RAM addressed by the computer, if available
boot_volume_capacity_in_bytesintegerBoot Volume Capacity in Bytes for the computer
boot_volume_usage_in_bytesintegerBoot Volume Usage in Bytes for the computer
boot_volume_capacitystringBoot Volume Capacity for the computer
boot_volume_usagestringBoot Volume Usage for the computer
boot_volume_usage_percentdecimalBoot Volume Usage % for the computer
processorstringProcessor info for the computer
current_uptimestringLast reported uptime for a computer
smc_versionstringSMC version
primary_ipstringInternal IP
active_mac_addressstringThe active (in use) MAC Address
system_mac_addressstringThe system MAC Address
asset_idstringAsset ID assigned to the computer
ard_field_1stringARD Field 1
ard_field_2stringARD Field 2
ard_field_3stringARD Field 3
ard_field_4stringARD Field 4
teamviewer_idstringTeamViewer ID
teamviewer_releasestringTeamViewer Major Version (12, 13, 14, etc.)
teamviewer_unattendedbooleanTrue when TeamViewer is configured for unattended access
bomgar_urlstringBomgar URL
logmein_urlstringLogMeIn URL
simplehelp_urlstringSimpleHelp URL
jss_computer_idstringJSS computer ID
jss_urlstringJSS URL
munki_identifierstringMunki ID
internal_notesstringThe internal notes for the record
public_notesstringThe public notes for the record
updates_enabledbooleanAre updates enabled for the Watchman Agent
settings_enabledbooleanAre settings enabled for the Watchman Agent
report_if_missingbooleanShould Watchman warn if this computer stops reporting
report_missing_afterintegerTime in days before computer is considered missing
ignore_missing_untilintegerIgnore missing until after this day
rekey_requestedbooleanHas a re-key been requested
pending_removalbooleanTrue once remote removal has been requested
agent_removedbooleanTrue once the Watchman Agent has reported either remote or manual removal
has_issuebooleanTrue when the computer is reporting errors
missingbooleanTrue if the computer fails to reported within its missing interval (7 days by default)
hiddenbooleanIs the computer set to hidden in the Dashboard
platformstringmac, linux, or windows
plugin_resultsarrayOptional array of the latest plugin results if you add &expand[]=plugin_results to the request
beacon_reportingbooleanIs beacon reporting enabled
beacon_missing_threshold_in_minutesintegerMinutes before a warning sent
create_ticket_on_beacon_foundbooleanIf 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.


Parameters
ParamDefaultPurpose
status nil Filter the computers by current status. Options are:
visible, hidden, missing, pending_rekey, pending_removal, and has_muted_plugin
group_idnilOnly return computers within this Group. You can use the Group's UID or slug*.
created_afternilOnly return computers which are created after this date. Dates are in YYYY-MM-DD format. E.g., 2018-12-25.
serial_numbernilFilter computers by Serial Number.
asset_idnilFilter computers by Asset ID.
reference_email_computernilFilter computers by reference email address for computer(s).
reference_email_groupnilFilter computers by reference email address for group.
reference_emailnilFilter computers by reference email address, searching both computer and group reference email addresses.
platformnilFilter computers by platform. Options are: linux, mac, windows
orderlast_reported_descOrder of computers. Options are:
reported_desc and created_desc
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe 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

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/computers?page=1&api_key=This_Example_API_Key
      
Example Object
[
  {
    "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,
    ...
  },
...
]
Example Request Limiting results by Group
        curl https://your_subdomain.monitoringclient.com/v2.5/computers?page=1&api_key=This_Example_API_Key&group_id=g_ac21d783d9
      
Example Object
[
  {
    "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",
    ...
  },
...
]
Example Request - Filtering results by Platform
        curl https://your_subdomain.monitoringclient.com/v2.5/computers?page=1&api_key=This_Example_API_Key&platform[]=mac&platform[]=windows
      
Example Object
[
  {
    "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.

Parameters
ParamDefaultPurpose
watchman_idnilThe Watchman ID for the computer you are looking up.
Response

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]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/computers/20110712-9DZA-8DUIV3?api_key=This_Example_API_Key
      
Example Object
{
"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",
"computer_name": "Jonathan's MacBook Pro",
"custom_name": "Travel MacBook",
"reference_email": "hello@example.com",
"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",
"apple_product_description": "MacBook Pro (Retina, Mid 2012)",
"product_description": "MacBook Pro (Retina, Mid 2012)",
"estimated_manufacture_date": 1393718400,
"estimated_purchase_date": 1393718400,
"registration_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
}
      
 

Update a Computer

Update the details of a Computer object.

Note: At present, only the following attributes are supported.

Parameters
ParamDefaultPurposeCharacter LimitRequired
asset_idnilAsset ID assigned to the computer191No
custom_namenilName to display in place of the Computer Name191No
descriptionnilDescriptive text for the Computer65535No
reference_emailnilReference email191No
product_descriptionnilDescriptive text for the Computer model65535No
estimated_manufacture_datenilEstimated manufacture dateNo
beacon_reportingnilEnable/disable beacon reportingNo
beacon_missing_threshold_in_minutes5Minutes before a warning sent. Allowed values are: 2, 5, 10, 15, 20, 15, and 30. No
create_ticket_on_beacon_foundfalseIf set to true, an alert will be sent when computer comes onlineNo

Response

Returns a Computer Object if passed attributes pass validation.

Returns a 500 if passed attribute exceeds Character Limit.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.5/computers/[watchman_id]

Example Request
curl -X PUT --header "Content-Type: application/x-www-form-urlencoded" \
-d api_key="This_Example_API_Key" \
-d computer[asset_id]="macbook1234" \
-d computer[custom_name]="Travel MacBook" \
-d computer[description]="Jonathan's other computer" \
-d computer[reference_email]="hello@example.com" \
-d computer[product_description]="MacBook Pro (Retina, Mid 2012)" \
-d computer[estimated_manufacture_date]="2012-06-10" \
-d computer[beacon_reporting]=true \
-d computer[beacon_missing_threshold_in_minutes]=10 \
-d computer[create_ticket_on_beacon_found]=true \
https://your_subdomain.monitoringclient.com/v2.5/computers/20140620-S994-7TXF1R
Example Object
{
"uid": "c_165f745e6b",
"watchman_id": "20140620-S994-7TXF1R",
"description": "Jonathan's other computer",
"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",
"reference_email": "hello@example.com",
"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",
"apple_product_description": "MacBook Pro (Retina, Mid 2012)",
"product_description": "MacBook Pro (Retina, Mid 2012)",
"estimated_manufacture_date": 1339266600,
"estimated_purchase_date": 1393718400,
"registration_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": "macbook1234",
"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
}
      
   

The Expiration Object

AttributeTypeDescription
uidstringUnique identifier for the Expiration.
license_keystringThe Expiration's license, serial number, or other identifier.
expires_atintegerThe the date the license expires on.
expiration_manufacturerstringThe UID of the expiration_manufacturer
expiration_productstringThe UID of the expiration_product
groupstringThe UID of the Group.
computerstringThe UID of the computer.
renewablebooleanIs the Expiration renewable
notestextAny notes for this Expiration.
created_atintegerDate the Expiration was created.
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": null,
  "created_at": 1441209663,
  "updated_at": 1441209663
}
      
 

List Expirations

Returns a list of Expirations in the current subscription, sorted by expires_at in descending order.


Parameters
ParamDefaultPurpose
uidnilUnique identifier for the Expiration
manufacturernilFilter Expirations by manufacturer UID or slug.
productnilFilter Expirations by product UID or slug.
groupnilFilter Expirations by Group UID or slug.
computernilFilter Expirations by computer UID or slug.
license_keynilFilter Expirations by license_key.
expires_at_startnilFilter Expirations by expires_at. Requires expires_at_end
expires_at_endnilFilter Expirations by expires_at. Requires expires_at_start
license_keynilFilter Expirations by renewable.
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe number to offset the results by. Set to 5 to start at record 6.
Definition
GET https://your_subdomain.monitoringclient.com/v2.5/expirations

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/expirations?api_key=This_Example_API_Key
      
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": null,
    "created_at": 1441209663
  },
  {
    "uid": "e_f7ffeaffd9",
    "license_key": "C02J60ZCF51R",
    "expires_at": 1533531600,
    "expiration_manufacturer": "em_e77660913d",
    "expiration_product": "ep_8a6cf51252",
    "computer": "c_7f80c0a74d",
    "group": "g_b7b31660cd",
    "renewable": false,
    "notes": null,
    "created_at": 1441209621
  },
...
]
 

Retrieving an Expiration

Retrieves the details of an Expiration object.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Expiration you are looking up.
Response

Returns an Expiration object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://your_subdomain.monitoringclient.com/v2.5/expirations/[uid]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/expirations/e_614b9d8c41?api_key=This_Example_API_Key
      
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": null,
  "created_at": 1441209663
}
      
 

Create an Expiration

Note about Expiration ownership.

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.

Parameters
ParamDefaultPurposeCharacter LimitRequired
license_keystringThe Expiration's license, serial number, or other identifier191Yes
expires_atintegerThe date the license expires onYes
expiration_manufacturer_idstringThe UID of the expiration_manufacturer191Yes
expiration_product_idstringThe UID of the expiration_product191Yes
group_idstringThe UID of the Group.191Yes*
computer_idstringThe UID of the computer.191Yes*
renewablebooleanIs the Expiration renewableNo
notestextAny notes for this Expiration.65535No
* 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.
Response

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

Example Request
curl https://your_subdomain.monitoringclient.com/v2.5/expirations/?api_key=This_Example_API_Key \
-d expiration[license_key]=isghds-firugs-sdfsdig \
-d expiration[expires_at]=2015-03-30 \
-d expiration[expiration_manufacturer_id]=em_e77660913d \
-d expiration[expiration_product_id]=ep_8a6cf51252 \
-d expiration[group_id]=g_ac21d783d9 \
-d expiration[computer_id]=c_165f745e6b \
-d expiration[renewable]=false
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": null,
  "created_at": 1441209663
}
      
 

Update an Expiration

Update the details of an Expiration object.

Parameters
ParamDefaultPurposeCharacter LimitRequired
license_keystringThe Expiration's license, serial number, or other identifier191Yes
expires_atintegerThe date the license expires onYes
expiration_manufacturer_idstringThe ID of the expiration_manufacturer191Yes
expiration_product_idstringThe ID of the expiration_product191Yes
group_idstringThe ID of the Group.191Yes*
computer_idstringThe ID of the computer.191Yes*
renewablebooleanIs the Expiration renewableNo
notestextAny notes for this Expiration.65535No
* 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.

Response

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.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Expiration you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.5/expirations/[uid]

Example Request
curl -X DELETE https://your_subdomain.monitoringclient.com/v2.5/expirations/e_614b9d8c41?api_key=This_Example_API_Key
   

The Expiration Manufacturer Object

AttributeTypeDescription
uidstringUnique identifier for the Expiration Manufacturer
slugstringThe dashboard url slug for the Expiration Manufacturer
namestringThe name of the Expiration Manufacturer
created_atintegerDate created
Example Object
{
  "uid": "em_e77660913d",
  "slug": "apple",
  "name": "Apple",
  "created_at": 1440623142
}
      
 

List Expiration Manufacturers

Returns a list of Expiration Manufactures in your account.


Parameters
ParamDefaultPurpose
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe number to offset the results by. Set to 5 to start at record 6.
Definition
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers?api_key=This_Example_API_Key
      
Example Object
[
  {
    "uid": "em_e77660913d",
    "slug": "apple",
    "name": "Apple",
    "created_at": 1440623142
  },
  {
    "uid": "em_e5159ae11d",
    "slug": "backblaze",
    "name": "Backblaze",
    "created_at": 1440630004
  },
...
]
 

Retrieving an Expiration Manufacturer

Retrieves the details of an Expiration Manufacturer.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Expiration you are looking up.
Response

Returns a Expiration Manufacturer object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/[expiration uid]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/em_e77660913d?api_key=This_Example_API_Key
      
Example Object
{
  "uid": "em_e77660913d",
  "slug": "apple",
  "name": "Apple",
  "created_at": 1440623142
}
      
 

Create an Expiration Manufacturer

Parameters
ParamDefaultPurposeCharacter LimitRequired
namestringThe name of the Expiration Manufacturer191Yes
Response

Returns a Expiration Manufacturer object if passed attributes pass validation.

Returns a 500 if passed attribute exceeds Character Limit.

Definition
POST https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers

Example Request
curl https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/?api_key=This_Example_API_Key \
-d expiration_manufacturer[name]=DNSimple
Example Object
{
  "uid": "em_e77660913d",
  "slug": "dnsimple",
  "name": "DNSimple",
  "created_at": 1440623142
}
      
 

Update an Expiration Manufacturer

Update the details of an Expiration Manufacturer.

Parameters
ParamDefaultPurposeCharacter LimitRequired
namestringThe name of the Expiration Manufacturer191Yes
Response

Returns a Expiration Manufacturer object if passed attributes pass validation.

Returns a 500 if passed attribute exceeds Character Limit.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/[expiration uid]

Example Request
curl -X PUT https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/em_763d6e7091?api_key=This_Example_API_Key \
-d expiration_manufacturer[name]=DNSimple Squared
Example Object
{
  "uid": "em_763d6e7091",
  "slug": "dnsimple-squared",
  "name": "DNSimple Squared",
  "created_at": 1540623142
}
      
 

Delete an Expiration Manufacturer

Permanently deletes an Expiration Manufacturer. This cannot be undone.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Expiration you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/[expiration uid]

Example Request
curl -X DELETE https://your_subdomain.monitoringclient.com/v2.5/expiration_manufacturers/em_763d6e7091?api_key=This_Example_API_Key
   

The Expiration Product Object

AttributeTypeDescription
uidstringUnique identifier for the Expiration Product
slugstringThe dashboard url slug for the Expiration Product
namestringThe name of the Expiration Product
created_atintegerDate created
Example Object
{
  "uid": "ep_e77660913d",
  "slug": "applecare",
  "name": "AppleCare",
  "created_at": 1440623142
}
      
 

List Expiration Products

Returns a list of Expiration Products in your account.


Parameters
ParamDefaultPurpose
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe number to offset the results by. Set to 5 to start at record 6.
Definition
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_products

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/expiration_products?api_key=This_Example_API_Key
      
Example Object
[
  {
    "uid": "ep_e77660913d",
    "slug": "applecare",
    "name": "AppleCare",
    "created_at": 1440623142
  },
  {
    "uid": "ep_e5159ae11d",
    "slug": "domain-registration",
    "name": "Domain Registration",
    "created_at": 1440630004
  },
...
]
 

Retrieving an Expiration Product

Retrieves the details of an Expiration Product.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Expiration you are looking up.
Response

Returns a Expiration Product object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://your_subdomain.monitoringclient.com/v2.5/expiration_products/[expiration uid]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/expiration_products/ep_e77660913d?api_key=This_Example_API_Key
      
Example Object
{
  "uid": "ep_e77660913d",
  "slug": "applecare",
  "name": "AppleCare",
  "created_at": 1440623142
}
      
 

Create an Expiration Product

Parameters
ParamDefaultPurposeCharacter LimitRequired
namestringThe name of the Expiration Product191Yes
Response

Returns a Expiration Product object if passed attributes pass validation.

Returns a 500 if passed attribute exceeds Character Limit.

Definition
POST https://your_subdomain.monitoringclient.com/v2.5/expiration_products

Example Request
curl https://your_subdomain.monitoringclient.com/v2.5/expiration_products/?api_key=This_Example_API_Key \
-d expiration_product[name]=Domain Registration
Example Object
{
  "uid": "ep_e77660913d",
  "slug": "domain-registration",
  "name": "Domain Registration",
  "created_at": 1440623142
}
      
 

Update an Expiration Product

Update the details of an Expiration Product.

Parameters
ParamDefaultPurposeCharacter LimitRequired
namestringThe name of the Expiration Product191Yes
Response

Returns a Expiration Product object if passed attributes pass validation.

Returns a 500 if passed attribute exceeds Character Limit.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.5/expiration_products/[expiration uid]

Example Request
curl -X PUT https://your_subdomain.monitoringclient.com/v2.5/expiration_products/ep_e5159ae11d?api_key=This_Example_API_Key \
-d expiration_product[name]=Domain Registrations
Example Object
{
  "uid": "ep_e5159ae11d",
  "slug": "domain-registrations",
  "name": "Domain Registrations",
  "created_at": 1440623142
}
      
 

Delete an Expiration Product

Permanently deletes an Expiration Product. This cannot be undone.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Expiration you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.5/expiration_products/[expiration uid]

Example Request
curl -X DELETE https://your_subdomain.monitoringclient.com/v2.5/expiration_products/ep_e5159ae11d?api_key=This_Example_API_Key
   

The Note Object

AttributeTypeDescription
uidstringUnique identifier for the Note
computerstringThe UID of the computer to which the note belongs.*
groupstringThe UID of the Group to which the note belongs.*
bodystringThe body content of the note
created_atintegerDate created
privatebooleanTrue when the note is only internally visible
include_in_emailbooleanTrue when note is included in emails
included_in_reportbooleanTrue 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.


Parameters
ParamDefaultPurpose
computernullThe UID of the computer whose notes you wish to retrieve.*
groupnullThe UID of the Group whose notes you wish to retrieve.*
include_privatefalseSet to true (true, yes, or 1) if you wish to include private notes in your results.
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe 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

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/notes?api_key=This_Example_API_Key&computer=c_cc342c6cc0
      
Example Object
[
  {
    "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.

Parameters
ParamDefaultPurpose
uidnilThe UID for the Note you are looking up.
Response

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]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/notes/n_3e412d7744?api_key=This_Example_API_Key
      
Example Object
{
  "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.

Parameters
ParamTypePurposeCharacter LimitRequired
computer_idstringThe UID of the Computer to which the note will be assigned.191Yes*
group_idstringThe UID of the Group to which the note will be assigned.191Yes*
bodytextThe text content of the note.16777215Yes
privatebooleanSets the privacy of the note.
Default: false
No
include_in_emailbooleanSets whether the note is visible in emails. Default: falseNo
include_in_reportbooleanSets whether the note is visible in emails. Default: falseNo

* Either computer_id OR group_id is required, but never both.

Response

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.

Parameters
ParamDefaultPurposeCharacter LimitRequired
computer_idstringThe UID of the Computer to which the note will be assigned.191No
group_idstringThe UID of the Group to which the note will be assigned.191No
bodytextThe text content of the note.16777215No
privatebooleanSets the privacy of the note.No
include_in_emailbooleanSets whether the note is visible in emails.No
include_in_reportbooleanSets 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.

Response

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
Example Object
{
  "uid": "n_2f985c3224",
  "computer": "c_cc342c6cc0",
  "group": null,
  "body": "Updated note content.",
  "created_at": 1453411465,
  "private": true,
  "include_in_email": true,
  "include_in_report": false
}
      
 

Delete a Note

Permanently deletes a Note. This cannot be undone.

Parameters
ParamDefaultPurpose
uidnilThe UID for the note you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.5/notes/[uid]

Example Request
curl -X DELETE https://your_subdomain.monitoringclient.com/v2.5/notes/n_2f985c3224?api_key=This_Example_API_Key
   

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.


Attributes
ParamDefaultPurpose
uidstringThe unique UID for the plugin result
namestringName of the plugin
slugstringSlug for the plugin
statusstringCurrent reported status: [OK, Warning, Alert, Informational]
detailstextThe plugins reported details
last_runintegerThe last time the plugin ran
mutedbooleanWhether or not the plugin is muted
mute_typestringThe type of mute in place: ["muted_forever", "timed_mute", "ticket_muted"]
mute_descriptionstringA brief description of the mute Only included if plugin is muted
ticket_numberstringThe ticket number for this mute Only included if plugin mute type is "ticket_muted"
ticket_urlstringThe url to the ticket Only included if plugin mute type is "ticket_muted"
mute_untilintegerThe date this plugin is muted until Only included if plugin mute type is "time_muted"
visiblebooleanThe 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.

Parameters
ParamDefaultPurpose
mute_typestringMute type. Available values are ignored, timed, ticket, and none. Passing none will clear all existing mutes.
mute_untilintegerUnix timestamp in future when a timed mute will expire. Required if mute_type is timed
ticket_numberstringTicket number. Required if mute_type is ticket
ticket_urlstringTicket 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

Response

Returns a Plugin Result object if passed attributes pass validation.

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

AttributeTypeDescription
uidstringThe unique identifier for the User
emailstringUser's email address
firstnamestringFirst name
lastnamestringLast name
tfa_statusbooleanDoes User has two-factor authentication enabled?
rolestringUser's role in the company
can_edit_contact_menubooleanCan the User edit contact-menu?
can_access_billingbooleanDoes the User have access to billing?
last_subdomainstringSubdomain of the company user accessed last
last_signinintegerUser's last sign-in time
created_atintegerThe date the User was created
restricted_group_uidsintegerGroups that can't be accessed by User (only available if user's role is "employee")
permitted_group_uidsintegerGroups that can be accessed by User (only available if user's role is "end_user")
Example Object
{
  "uid": "u_edb3d7fbfb",
  "email": "john.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "tfa_status": false,
  "role": "employee",
  "can_edit_contact_menu": true,
  "can_access_billing": true,
  "last_subdomain": "your_subdomain",
  "last_signin": 1503713667,
  "created_at": 1503713667,
  "restricted_group_uids":["g_68d5a5d898","g_273f848c2e"]
}
      
 

List Users

Returns a list of Users.


Parameters
ParamDefaultPurpose
page1The page number where you wish to begin.
per_page50The quantity per page in each request. Up to 100 can be returned per-request.
offsetnilThe number to offset the results by. Set to 5 to start at record 6.
Definition
GET https://your_subdomain.monitoringclient.com/v2.5/users

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/users?api_key=This_Example_API_Key
      
Example Object
[
  {
    "uid": "u_6dcc1106f7",
    "email": "admin@example.com",
    "firstname": "Admin",
    "lastname": "User",
    "tfa_status": true,
    "role": "admin",
    "can_edit_contact_menu": true,
    "can_access_billing": true,
    "last_subdomain": "your_subdomain",
    "last_signin": 1502881547,
    "created_at": 1459116995
  },
  {
    "uid": "u_edb3d7fbfb",
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "tfa_status": false,
    "role": "employee",
    "can_edit_contact_menu": true,
    "can_access_billing": true,
    "last_subdomain": "your_subdomain",
    "last_signin": 1503713667,
    "created_at": 1503713667,
    "restricted_group_uids":["g_68d5a5d898","g_273f848c2e"]
  },
  ...
]
 

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.

Parameters
ParamDefaultPurpose
uidn/aThe User UID for the User Record you are looking up.
Response

Returns a User Object If a valid User UID was provided, returns an error otherwise.

Definition
GET https://your_subdomain.monitoringclient.com/v2.5/users/[uid]

Example Request
        curl https://your_subdomain.monitoringclient.com/v2.5/users/u_6dcc1106f7?api_key=This_Example_API_Key
      
Example Object
{
  "uid": "u_edb3d7fbfb",
  "email": "john.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "tfa_status": false,
  "role": "employee",
  "can_edit_contact_menu": true,
  "can_access_billing": true,
  "last_subdomain": "your_subdomain",
  "last_signin": null,
  "created_at": 1503713667,
  "restricted_group_uids":["g_68d5a5d898","g_273f848c2e"]
}
      
 

Create a User

Create a User. If the user already exists in our system, it will be added to this company.

Parameters
ParamTypePurposeLengthRequired
firstnamestringUser's first name191Yes
lastnamestringUser's last name191Yes
emailstringUser's email191Yes
rolestringUser's role in the company. Allowed values are: admin, employee, and end_user191Yes
can_edit_contact_menubooleanIf user has permission to edit contact menu (not required for admin role)No
can_access_billingbooleanIf user has permission to edit contact menu (not required for admin role)No
permitted_group_uidsarrayList of Group UIDs user has access to (only available for end_user role)No
restricted_group_uidsarrayList of Group UIDs user does not have access to (only available for employee role)No
Response

Returns the newly created User Object.

Definition
POST https://your_subdomain.monitoringclient.com/v2.5/groups/find_or_create?api_key=This_Example_API_Key

Example Request
        curl -X POST https://your_subdomain.monitoringclient.com/v2.5/users?api_key=This_Example_API_Key \
-d user[firstname]="John" \
-d user[lastname]="Doe" \
-d user[email]="john.doe@example.com" \
-d user[role]="employee" \
-d user[can_edit_contact_menu]=true \
-d user[can_access_billing]=true \
-d user[restricted_group_uids][]="g_68d5a5d898" \
-d user[restricted_group_uids][]="g_273f848c2e"
      
Example Object
{
  "uid": "u_edb3d7fbfb",
  "email": "john.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "tfa_status": false,
  "role": "employee",
  "can_edit_contact_menu": true,
  "can_access_billing": true,
  "last_subdomain": "your_subdomain",
  "last_signin": null,
  "created_at": 1503713667,
  "restricted_group_uids":["g_68d5a5d898","g_273f848c2e"]
}