Deprecated API Version

Support for version 2.2 of the Watchman API will be discontinued Jan 1st, 2017. Please take whatever steps are necessary to ensure your integrations are updated to Version 2.5 before then.

For more information about the changes from V2.2 to V2.5 read the change log.

Getting Started

The Watchman Monitoring API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

Base URL

All URLs referenced in the documentation use the same base with the desired API version number.

Times

Dates and times are sent in unix epoch. Times sent in plugin result objects will vary based on the accuracy of the monitored computer's clock.

Security and HTTPS

The REST API is served via HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Rate Limiting

All requests are rate limited to 400/minute.

Base URL
https://your_subdomain.monitoringclient.com/v2.2/
 

Versioning

New API point version will be released any time new features require changes which are not backward compatible. The current version is 2.2. View the changelog and read more about API versions

Current Version
The current API version is 2.2 was released 20 Sep 2015.
 

Authentication

You authenticate to the Watchman Monitoring API by providing a valid API key in the api_key parameter of the request. Administrators can manage API keys by navigating to Settings > API, or in related Integration modal windows.

API keys carry all administrative privileges, be sure to keep them secret! API Keys can be reset at any time via the Dashboard

 

Expanding Objects

Many objects contain the ID of another object in their response properties. Those objects can be expanded inline by including an array of one or more keys in the expand request parameter.

This parameter is available on all API requests, and applies to the response of that request only.

GET https://your_subdomain.monitoringclient.com/v2.2/computers?api_key=This_Example_API_key&expand[]=plugin_results
 

Nested Expansion

Expansion requests can be nested with the dot property. For example, requesting computer.plugin_results on an Expiration will expand the computer property into a full computer object, and will then expand the plugin_results property on that computer into an array of plugin result objects.

GET https://your_subdomain.monitoringclient.com/v2.2/expirations?api_key=This_Example_API_key&expand[]=computer.plugin_results
 

Errors

Watchman Monitoring uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error an invalid request (e.g. a required parameter was missing, subdomain or api_key we invalid, etc.), and codes in the 5xx range indicate a failure, and should be reported.

Error Attributes

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 require 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 computers and list groups.

Watchman Monitoring utilizes paged-based pagination, using the parameters page and per_page. Pass page to dictate what page in the list you would like to fetch, per_page to set the quantity of results, and offset to offset your results by a given number.


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
 

Change log

View the Change Log to keep up with API changes.

   

The Group Object

AttributeTypeDescription
idstringThe unique identifier for the Group
slugstringThe unique dashboard url slug for the Group
namestringThe Group's name
descriptiontextDescriptive text for the Group
visible_computer_countintegerThe count of visible computers
hidden_computer_countintegerThe count of hidden computers
created_atintegerThe date the Group was created
createdintegerThe date the Group was created (deprecated)
Example Object
  {
    "id": "g_ac21d783d9",
    "slug": "test-group",
    "name": "Test Group",
    "description": "This is the Group's description",
    "visible_computer_count": 2,
    "hidden_computer_count": 0,
    "created_at": 1442024926
  }
        
 

List Groups

Returns a list of Groups you are monitoring. Groups are returned sorted by name.


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.2/groups

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/groups?api_key=This_Example_API_Key
        
Example Object
[
  {
    "id": "g_ac21d783d9",
    "slug": "test-group",
    "name": "Test Group",
    "description": "This is the Group's description",
    "visible_computer_count": 2,
    "hidden_computer_count": 0,
    "created_at": 1442024926,
  },
  {
    "id": "g_83a21d7cd9",
    "slug": "blank",
    "name": "[Blank]",
    "description": "Sample Group description",
    "visible_computer_count": 1,
    "hidden_computer_count": 0,
    "created_at": 1442024926,
  },
  ...
]
 

Retrieving a Group

Retrieves the details of a Group. Supply the unique Group ID as described in the previous example to receive all details about the corresponding Group.

Parameters
ParamDefaultPurpose
idn/aThe Group ID for the computer you are looking up.
Response

Returns a Group Object If a valid Group ID was provided, returns an error otherwise.

Definition
GET https://your_subdomain.monitoringclient.com/v2.2/groups/[watchman_group_id]

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/groups/test-group?api_key=This_Example_API_Key
        
Example Object
  {
    "id": "g_ac21d783d9"
    "slug": "test-group",
    "name": "Test Group",
    "description": "This is the Group's description",
    "visible_computer_count": 1,
    "hidden_computer_count": 0,
    "created_at": 1442024926
  }
        
   

The Computer Object

AttributeTypeDescription
idstringUnique identifier for the Computer
watchman_idstringThe Watchman ID generated by the computer
descriptiontextDescriptive text for the Computer
agent_versionstringVersion number for the installed agent
build_number deprecatedstringThe build number of some outdated agents.
last_reportintegerDate of the last report to Watchman
created_atintegerDate the computer first reported
groupstringThe Group ID that this computer belongs to
computer_namestringComputer's Computer Name
machine_namestringComputer's Computer Name (deprecated)
custom_namestringComputer's custom display name in the dashboard.
display_namestringComputer's custom display name in the dashboard. (deprecated)
last_userstringLast signed in user
serial_numberstringComputer's serial number
os_versionstringOperating system of the computer
model_identifierstringModel Identifier of the computer
model_namestringModel name of the computer
applecare_eligibility*booleanAppleCare eligibility*
warranty_status*stringWarranty status*
estimated_purchase_dateintegerEstimated purchase date
config_description*stringComputer 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
installed_ramstringAmount of RAM installed (deprecated)
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 (8,9,10,11,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
platformstringlinux, mac, or windows
plugin_resultsarrayOptional array of the latest plugin results if you add &expand[]=plugin_results to your request
* Only included if GSX Integration is enabled.
* null values will be returned when a fact is unknown.
Example Object
{
  "id": "c_165f745e6b",
  "watchman_id": "20140620-S994-7TXF1R",
  "description": "This is the computer's description",
  "agent_version": "6.6.3.650",
    "last_update": 1442026136,
  "last_report": "2014-10-13T11:12:51.000-05:00",
  "created_at": 1442025819,
  "group": "g_ac21d783d9",
  "computer_name": "Jonathan's MacBook Pro",
  "display_name": "Travel MacBook",
  "last_user": "jonathan",
  "serial_number": "A12BC345DEF6",
  "os_version": "OS X 10.10 (14A343f)",
  "model_identifier": "MacBookPro10,1",
  "model_name": "MacBook Pro (Retina, Mid 2012)",
  "applecare_eligibility": false,
  "warranty_status": "AppleCare Protection Plan",
  "estimated_purchase_date": 1393718400,
  "config_description": "MBP 15.4/2.3/8GB/256GB FLASH",
  "ram_installed": "8 GB",
  "ram_installed_in_bytes": "8589934592",
  "ram_speed": "PC3-12800 DDR3 at 1600MHz",
  "ram_upgradeable": true,
  "ram_max_apple": "16 GB",
  "ram_max_actual": "32 GB",
  "boot_volume_capacity_in_bytes": 999695822848,
  "boot_volume_usage_in_bytes": 270039891968,
  "boot_volume_capacity": "999.70 GB",
  "boot_volume_usage": "270.04 GB",
  "boot_volume_usage_percent": 27.01,
  "processor": "Intel Core i7 2.3 GHz (4 core 1 processor)",
  "current_uptime": "0 days, 23 hours, 55 mins",
  "smc_version": "2.3f36",
  "primary_ip": "11.11.11.95",
  "active_mac_address": "a4:5e:60:cf:27:6b",
  "system_mac_address": "a4:5e:60:cf:27:6b",
  "asset_id": null,
  "ard_field1": "",
  "ard_field2": "",
  "ard_field3": "",
  "ard_field4": "",
  "teamviewer_id": "123456789",
  "teamviewer_release": "10",
  "teamviewer_unattended": null,
  "bomgar_url": null,
  "logmein_url": null,
  "simplehelp_url": null,
  "jss_computer_id": "",
  "jss_url": "",
  "munki_identifier": "",
  "internal_notes": null,
  "public_notes": null,
  "updates_enabled": true,
  "settings_enabled": true,
  "report_if_missing": true,
  "report_missing_after": 7,
  "ignore_missing_until": null,
  "rekey_requested": false,
  "pending_removal": false,
  "agent_removed": false,
  "has_issue": true,
  "missing": false,
  "hidden": false,
  "platform": "mac"
}
        
 

List Computers

Returns a list of computers in the current subscription. Computer records are returned sorted by last_report, with the most recent computer appearing first.


Parameters
ParamDefaultPurpose
statusnilFilter the computers by current status. Options are:
["visible", "hidden", "missing", "pending_rekey", "pending_removal", "has_muted_plugin"]
group_idnilOnly return computers within this Group. You can use the Group's ID or slug*.
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.2/computers

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/computers?api_key=This_Example_API_Key
        
Example Object
[
  {
    "id": "c_165f745e6b",
    "watchman_id": "20140620-S994-7TXF1R",
    "description": "This is the computer's description",
    "agent_version": "6.6.3.650",
    "last_update": 1442026136,
    "last_report": "2014-10-13T11:12:51.000-05:00",
    "created_at": 1442025819,
    ...
  },
  {
    "id": "c_615fe7465b",
    "watchman_id": "20131127-DJ0R-P4NFDF",
    "description": "Sample computer description",
    "agent_version": "6.6.3.650",
    "last_update": 1442026136,
    "last_report": "2014-10-13T11:12:51.000-05:00",
    "created_at": 1442025819,
    ...
  },
  ...
]
Example Request Limiting results by Group
          curl https://your_subdomain.monitoringclient.com/v2.2/computers?api_key=This_Example_API_Key&group_id=g_ac21d783d9
        
Example Object
[
  {
    "id": "c_165f745e6b",
    "watchman_id": "20140620-S994-7TXF1R",
    "description": "This is the computer's description",
    "agent_version": "6.6.3.650",
    "last_update": 1442026136,
    "last_report": "2014-10-13T11:12:51.000-05:00",
    "created_at": 1442025819,
    "group": "g_ac21d783d9",
    ...
  },
  {
    "id": "c_615fe7465b",
    "watchman_id": "20131127-DJ0R-P4NFDF",
    "description": "Sample computer description",
    "agent_version": "6.6.3.650",
    "last_update": 1442026136,
    "last_report": "2014-10-13T11:12:51.000-05:00",
    "created_at": 1442025819,
    "group": "g_ac21d783d9",
    ...
  },
  ...
]
 

Retrieving a Computer

Retrieves the details of a computer object.

Parameters
ParamDefaultPurpose
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.2/computers/[watchman_id]

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/computers/20110712-9DZA-8DUIV3?api_key=This_Example_API_Key
        
Example Object
{
  "id": "c_165f745e6b",
  "watchman_id": "20140620-S994-7TXF1R",
  "description": "This is the computer's description",
  "agent_version": "6.6.3.650",
    "last_update": 1442026136,
  "last_report": "2014-10-13T11:12:51.000-05:00",
  "created_at": 1442025819,
  "group": "g_ac21d783d9",
  "machine_name": "Jonathan's MacBook Pro",
  "display_name": "Travel MacBook",
  "last_user": "jonathan",
  "serial_number": "A12BC345DEF6",
  "os_version": "OS X 10.10 (14A343f)",
  "model_identifier": "MacBookPro10,1",
  "model_name": "MacBook Pro (Retina, Mid 2012)",
  "applecare_eligibility": false,
  "warranty_status": "AppleCare Protection Plan",
  "estimated_purchase_date": 1393718400,
  "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"
}
        
   

The Expiration Object

AttributeTypeDescription
idstringUnique identifier for the Expiration
license_keystringThe Expiration's license, serial number, or other identifier
expires_atintegerThe the date the license expires on
expiration_manufacturerstringThe ID of the expiration_manufacturer
expiration_productstringThe ID of the expiration_product
groupstringThe ID of the Group.
computerstringThe ID of the computer.
renewablebooleanIs the Expiration renewable
notestextAny notes for this Expiration.
created_atintegerDate the Expiration was created
Example Object
{
  "id": "e_614b9d8c41",
  "license_key": "A12BC345DEF6",
  "expires_at": null,
  "expiration_manufacturer": "em_e77660913d",
  "expiration_product": "ep_8a6cf51252",
  "computer": "c_165f745e6b",
  "group": "g_ac21d783d9",
  "renewable": false,
  "notes": null,
  "created_at": 1441209663,
  "updated_at": 1441209663
}
        
 

List Expirations

Returns a list of Expirations in the current subscription.


Parameters
ParamDefaultPurpose
manufacturernilFilter Expirations by manufacturer ID or slug.
productnilFilter Expirations by product ID or slug.
groupnilFilter Expirations by Group ID or slug.
computernilFilter Expirations by computer ID 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.2/expirations

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/expirations?api_key=This_Example_API_Key
        
Example Object
[
  {
    "id": "e_614b9d8c41",
    "license_key": "A12BC345DEF6",
    "expires_at": null,
    "expiration_manufacturer": "em_e77660913d",
    "expiration_product": "ep_8a6cf51252",
    "computer": "c_165f745e6b",
    "group": "g_ac21d783d9",
    "renewable": false,
    "notes": null,
    "created_at": 1441209663,
  },
  {
    "id": "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
idnilThe ID 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.2/expirations/[expiration_id]

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/expirations/e_614b9d8c41?api_key=This_Example_API_Key
        
Example Object
{
  "id": "e_614b9d8c41",
  "license_key": "A12BC345DEF6",
  "expires_at": null,
  "expiration_manufacturer": "em_e77660913d",
  "expiration_product": "ep_8a6cf51252",
  "computer": "c_165f745e6b",
  "group": "g_ac21d783d9",
  "renewable": false,
  "notes": 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
ParamDefaultPurposeRequired
license_keystringThe Expiration's license, serial number, or other identifierYes
expires_atintegerThe date the license expires onYes
expiration_manufacturer_idstringThe ID of the expiration_manufacturerYes
expiration_product_idstringThe ID of the expiration_productYes
group_idstringThe ID of the Group.Yes*
computer_idstringThe ID of the computer.Yes*
renewablebooleanIs the Expiration renewableNo
notestextAny notes for this Expiration.No
* You only need to specify ONE of group_id or computer_id to associate the Expiration to a computer or Group. Both attributes are not required.
Response

Returns an Expiration object if passed attributes pass validation.

Definition
POST https://your_subdomain.monitoringclient.com/v2.2/expirations

Example Request
  curl https://your_subdomain.monitoringclient.com/v2.2/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
{
  "id": "e_614b9d8c41",
  "license_key": "A12BC345DEF6",
  "expires_at": null,
  "expiration_manufacturer": "em_e77660913d",
  "expiration_product": "ep_8a6cf51252",
  "computer": "c_165f745e6b",
  "group": "g_ac21d783d9",
  "renewable": false,
  "notes": null,
  "created_at": 1441209663
}
        
 

Update an Expiration

Update the details of an Expiration object.

Parameters
ParamDefaultPurposeRequired
license_keystringThe Expiration's license, serial number, or other identifierYes
expires_atintegerThe date the license expires onYes
expiration_manufacturer_idstringThe ID of the expiration_manufacturerYes
expiration_product_idstringThe ID of the expiration_productYes
group_idstringThe ID of the Group.Yes*
computer_idstringThe ID of the computer.Yes*
renewablebooleanIs the Expiration renewableNo
notestextAny notes for this Expiration.No
* You only need to specify ONE of group_id or computer_id to associate the Expiration to a computer or Group. Both attributes are not required.

Response

Returns an Expiration object if passed attributes pass validation.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.2/expirations/[expiration_id]

Example Request
  curl https://your_subdomain.monitoringclient.com/v2.2/expirations/e_614b9d8c41?api_key=This_Example_API_Key \
  -d expiration[notes]=These are some notes
Example Object
{
  "id": "e_614b9d8c41",
  "license_key": "A12BC345DEF6",
  "expires_at": null,
  "expiration_manufacturer": "em_e77660913d",
  "expiration_product": "ep_8a6cf51252",
  "computer": "c_165f745e6b",
  "group": "g_ac21d783d9",
  "renewable": false,
  "notes": "These are some notes",
  "created_at": 1441209663
}
        
 

Delete an Expiration

Permanently deletes an Expiration. This cannot be undone.

Parameters
ParamDefaultPurpose
idnilThe ID for the Expiration you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.2/expirations/[expiration_id]

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

The Expiration Manufacturer Object

AttributeTypeDescription
idstringUnique identifier for the Expiration Manufacturer
namestringThe name of the Expiration Manufacturer
slugintegerThe dashboard url slug for the Expiration Manufacturer
created_atintegerDate created
Example Object
{
  "id": "em_e77660913d",
  "slug": "DNSimple",
  "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.2/expiration_manufacturers

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

Retrieving an Expiration Manufacturer

Retrieves the details of an Expiration Manufacturer.

Parameters
ParamDefaultPurpose
idnilThe ID 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.2/expiration_manufacturers/[expiration_id]

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

Create an Expiration Manufacturer

Parameters
ParamDefaultPurposeRequired
namestringThe name of the Expiration ManufacturerYes
Response

Returns a Expiration Manufacturer object if passed attributes pass validation.

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

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

Update an Expiration Manufacturer

Update the details of an Expiration Manufacturer.

Parameters
ParamDefaultPurposeRequired
namestringThe name of the Expiration ManufacturerYes
Response

Returns a Expiration Manufacturer object if passed attributes pass validation.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.2/expiration_manufacturers/[expiration_id]

Example Request
  curl https://your_subdomain.monitoringclient.com/v2.2/expiration_manufacturers/em_763d6e7091?api_key=This_Example_API_Key \
  -d expiration_manufacturer[name]=DNSimple Squared
Example Object
{
  "id": "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
idnilThe ID for the Expiration you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.2/expiration_manufacturers/[expiration_id]

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

The Expiration Product Object

AttributeTypeDescription
idstringUnique identifier for the Expiration Product
namestringThe name of the Expiration Product
slugintegerThe dashboard url slug for the Expiration Product
created_atintegerDate created
Example Object
{
  "id": "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.2/expiration_products

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

Retrieving an Expiration Product

Retrieves the details of an Expiration Product.

Parameters
ParamDefaultPurpose
idnilThe ID 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.2/expiration_products/[expiration_id]

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

Create an Expiration Product

Parameters
ParamDefaultPurposeRequired
namestringThe name of the Expiration ProductYes
Response

Returns a Expiration Product object if passed attributes pass validation.

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

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

Update an Expiration Product

Update the details of an Expiration Product.

Parameters
ParamDefaultPurposeRequired
namestringThe name of the Expiration ProductYes
Response

Returns a Expiration Product object if passed attributes pass validation.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.2/expiration_products/[expiration_id]

Example Request
  curl https://your_subdomain.monitoringclient.com/v2.2/expiration_products/ep_e5159ae11d?api_key=This_Example_API_Key \
  -d expiration_product[name]=Domain Registrations
Example Object
{
  "id": "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
idnilThe ID for the Expiration you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.2/expiration_products/[expiration_id]

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

The Note Object

AttributeTypeDescription
idstringUnique identifier for the Note
computer*stringID of the computer to which the note belongs
group*stringID 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
{
  "id": "n_70ab8b7f04",
  "computer": "c_812666945e",
  "group": "g_713e78ad3a",
  "body": "This is the note's content.",
  "created_at": 1453135662,
  "private": false,
  "include_in_email": false,
  "include_in_report": false
}
        
 

List Notes

Returns a list of Notes. If computer_id and group_id are left blank, all notes in your account will be returned.


Parameters
ParamDefaultPurpose
computer_id*nullThe ID of the computer whose notes you wish to retrieve.
group_id*nullThe ID 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.2/notes

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/notes?api_key=This_Example_API_Key&computer_id=c_cc342c6cc0
        
Example Object
[
  {
    "id": "n_c6a844020d",
    "computer": "c_cc342c6cc0",
    "group": null,
    "body": "This is the note's content.",
    "created_at": 1453135662,
    "private": false,
    "include_in_email": false,
    "include_in_report": true
  },
  {
    "id": "n_3e412d7744",
    "computer": "c_cc342c6cc0",
    "group": null,
    "body": "The content of this note.",
    "created_at": 1453135662,
    "private": false,
    "include_in_email": true,
    "include_in_report": false
  },
  ...
]
 

Retrieving a Note

Retrieves the details of a Note.

Parameters
ParamDefaultPurpose
idnilThe ID 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.2/notes/[note_id]

Example Request
          curl https://your_subdomain.monitoringclient.com/v2.2/notes/n_3e412d7744?api_key=This_Example_API_Key
        
Example Object
{
  "id": "n_3e412d7744",
  "computer": "c_cc342c6cc0",
  "group": null,
  "body": "The content of this note.",
  "created_at": 1453135662,
  "private": false,
  "include_in_email": true,
  "include_in_report": false
}
        
 

Create a Note

About Note ownership.

When creating a Note you must provide either a group_id or computer_id for the Note to be associated to. Sending both a group_id AND computer_id will result in an error.

Parameters
ParamTypePurposeRequired
computer_idstringThe ID of the Computer to which the note will be assigned.Yes*
group_idstringThe ID of the Group to which the note will be assigned.Yes*
bodystringThe text content of the note.Yes
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.

Definition
POST https://your_subdomain.monitoringclient.com/v2.2/notes

Example Request
  curl https://your_subdomain.monitoringclient.com/v2.2/notes/?api_key=This_Example_API_Key \
  -d note[computer_id]=c_cc342c6cc0 \
  -d note[body]="This is the note content." \
  -d note[include_in_email]=true
Example Object
{
  "id": "n_2f985c3224",
  "computer": "c_cc342c6cc0",
  "group": null,
  "body": "This is the note content.",
  "created_at": 1453411465,
  "private": false,
  "include_in_email": true,
  "include_in_report": false
}
        
 

Update a Note

Update the details of a Note.

Parameters
ParamDefaultPurposeRequired
computer_idstringThe ID of the Computer to which the note will be assigned.No
group_idstringThe ID of the Group to which the note will be assigned.No
bodystringThe text content of the note.No
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.

Definition
PUT https://your_subdomain.monitoringclient.com/v2.2/notes/[note_id]

Example Request
  curl https://your_subdomain.monitoringclient.com/v2.2/notes/n_2f985c3224?api_key=This_Example_API_Key \
  -d note[body]="Updated note content." \
  -d note[private]=true
Example Object
{
  "id": "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
idnilThe ID for the note you are deleting.
Response

Returns a 204 no content

Definition
DELETE https://your_subdomain.monitoringclient.com/v2.2/notes/[note_id]

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

The Plugin Result Object

Plugin results are returned with their related Computer Records.


Attributes
ParamDefaultPurpose
idintegerThe unique ID 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"
Example Object
{
    "id": 224285,
    "name": "Monitoring Agent",
    "slug": "monitoring-agent",
    "status": "OK",
    "details": "The internal check of the Watchman Monitoring software reports no issues.",
    "last_run": 1372324943,
    "muted": true,
    "mute_type": "timed_mute",
    "mute_description": "Plugin is muted until Sep 27th 2013.",
    "muted_until": 1380258000
}