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.
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
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.
Nested Expansion
Expansion requests can be nested with the dot property. For example, requesting computer.plugin_results
on an Expiration will expand the computer property into a full computer object, and will then expand the plugin_results property on that computer into an array of plugin result objects.
Errors
Watchman Monitoring uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error an invalid request (e.g. a required parameter was missing, subdomain or api_key we invalid, etc.), and codes in the 5xx range indicate a failure, and should be reported.
Error Attributes
Attribute | Type | Description |
---|---|---|
status_code | integer | The HTTP response code |
code | string | The Watchman Monitoring status code |
title | string | The title of this error |
details | string | The details of the error |
attribute | string | This is only sent in the case of 422 :unprocessable_entity errors and reflects the attribute which failed validation. |
Attribute | Description |
---|---|
200 OK | Everything worked as expected. |
400 Bad Request | Often missing a required parameter. |
401 Unauthorized | No valid API Key or Subscriber subdomain provided. |
403 Forbidden | Valid subdomain and API key provided, but lacks permission to the requested item. |
404 Not Found | The requested item doesn't exist. |
422 Unprocessable Entity | There is a validation error on the object you are trying to create. |
500, 502, 503, 504 Server errors | An error was raised within the Watchman Monitoring server. |
Codes
Attribute | Description |
---|---|
:missing_parameter | A required parameter is missing. |
:unpermitted_parameter | There is an unpermitted parameter in the object you are trying to create or update. |
Pagination
All top-level Watchman Monitoring API resources have support for bulk fetches — "list" API methods. For instance you can list computers and list groups.
Watchman Monitoring utilizes paged-based pagination, using the parameters page
and per_page
. Pass page
to dictate what page in the list you would like to fetch, per_page
to set the quantity of results, and offset
to offset your results by a given number.
Param | Default | Purpose |
---|---|---|
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Example: set to 5 to start at record 6 |
Change log
View the Change Log to keep up with API changes.
The Group Object
Attribute | Type | Description |
---|---|---|
id | string | The unique identifier for the Group |
slug | string | The unique dashboard url slug for the Group |
name | string | The Group's name |
description | text | Descriptive text for the Group |
visible_computer_count | integer | The count of visible computers |
hidden_computer_count | integer | The count of hidden computers |
created_at | integer | The date the Group was created |
created | integer | The date the Group was created (deprecated) |
{
"id": "g_ac21d783d9",
"slug": "test-group",
"name": "Test Group",
"description": "This is the Group's description",
"visible_computer_count": 2,
"hidden_computer_count": 0,
"created_at": 1442024926
}
List Groups
Returns a list of Groups you are monitoring. Groups are returned sorted by name.
Param | Default | Purpose |
---|---|---|
visibility | nil | Filter Groups by visibility. Options are: ["visible", "hidden"] |
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Set to 5 to start at record 6. |
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
[
{
"id": "g_ac21d783d9",
"slug": "test-group",
"name": "Test Group",
"description": "This is the Group's description",
"visible_computer_count": 2,
"hidden_computer_count": 0,
"created_at": 1442024926,
},
{
"id": "g_83a21d7cd9",
"slug": "blank",
"name": "[Blank]",
"description": "Sample Group description",
"visible_computer_count": 1,
"hidden_computer_count": 0,
"created_at": 1442024926,
},
...
]
Retrieving a Group
Retrieves the details of a Group. Supply the unique Group ID as described in the previous example to receive all details about the corresponding Group.
Param | Default | Purpose |
---|---|---|
id | n/a | The Group ID for the computer you are looking up. |
Returns a Group Object If a valid Group ID was provided, returns an error otherwise.
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
{
"id": "g_ac21d783d9"
"slug": "test-group",
"name": "Test Group",
"description": "This is the Group's description",
"visible_computer_count": 1,
"hidden_computer_count": 0,
"created_at": 1442024926
}
The Computer Object
Attribute | Type | Description |
---|---|---|
id | string | Unique identifier for the Computer |
watchman_id | string | The Watchman ID generated by the computer |
description | text | Descriptive text for the Computer |
agent_version | string | Version number for the installed agent |
build_number deprecated | string | The build number of some outdated agents. |
last_report | integer | Date of the last report to Watchman |
created_at | integer | Date the computer first reported |
group | string | The Group ID that this computer belongs to |
computer_name | string | Computer's Computer Name |
machine_name | string | Computer's Computer Name (deprecated) |
custom_name | string | Computer's custom display name in the dashboard. |
display_name | string | Computer's custom display name in the dashboard. (deprecated) |
last_user | string | Last signed in user |
serial_number | string | Computer's serial number |
os_version | string | Operating system of the computer |
model_identifier | string | Model Identifier of the computer |
model_name | string | Model name of the computer |
applecare_eligibility | boolean | AppleCare eligibility* |
warranty_status | string | Warranty status* |
estimated_purchase_date | integer | Estimated purchase date* |
config_description | string | Computer configuration description* |
ram_installed | string | Amount of RAM installed in the computer (human readable) |
ram_installed_in_bytes | string | Amount of RAM installed in the computer (in bytes) |
ram_speed | string | Type and speed of RAM chips accepted by this computer, if available |
ram_upgradeable | boolean | Indicates if the computer is able to accept a RAM upgrade |
ram_max_apple | string | Maximum RAM according to Apple, if available |
ram_max_actual | string | Maximum RAM addressed by the computer, if available |
installed_ram | string | Amount of RAM installed (deprecated) |
boot_volume_capacity_in_bytes | integer | Boot Volume Capacity in Bytes for the computer |
boot_volume_usage_in_bytes | integer | Boot Volume Usage in Bytes for the computer |
boot_volume_capacity | string | Boot Volume Capacity for the computer |
boot_volume_usage | string | Boot Volume Usage for the computer |
boot_volume_usage_percent | decimal | Boot Volume Usage % for the computer |
processor | string | Processor info for the computer |
current_uptime | string | Last reported uptime for a computer |
smc_version | string | SMC version |
primary_ip | string | Internal IP |
active_mac_address | string | The active (in use) MAC Address |
system_mac_address | string | The system MAC Address |
asset_id | string | Asset ID assigned to the computer |
ard_field_1 | string | ARD Field 1 |
ard_field_2 | string | ARD Field 2 |
ard_field_3 | string | ARD Field 3 |
ard_field_4 | string | ARD Field 4 |
teamviewer_id | string | TeamViewer ID |
teamviewer_release | string | TeamViewer Major Version (12, 13, 14, etc.) |
teamviewer_unattended | boolean | True when TeamViewer is configured for unattended access |
bomgar_url | string | Bomgar URL |
logmein_url | string | LogMeIn URL |
simplehelp_url | string | SimpleHelp URL |
jss_computer_id | string | JSS computer ID |
jss_url | string | JSS URL |
munki_identifier | string | Munki ID |
internal_notes | string | The internal notes for the record |
public_notes | string | The public notes for the record |
updates_enabled | boolean | Are updates enabled for the Watchman Agent |
settings_enabled | boolean | Are settings enabled for the Watchman Agent |
report_if_missing | boolean | Should Watchman warn if this computer stops reporting |
report_missing_after | integer | Time in days before computer is considered missing |
ignore_missing_until | integer | Ignore missing until after this day |
rekey_requested | boolean | Has a re-key been requested |
pending_removal | boolean | True once remote removal has been requested |
agent_removed | boolean | True once the Watchman Agent has reported either remote or manual removal |
has_issue | boolean | True when the computer is reporting errors |
missing | boolean | True if the computer fails to reported within its missing interval (7 days by default) |
hidden | boolean | Is the computer set to hidden in the Dashboard |
platform | string | linux, mac, or windows |
plugin_results | array | Optional array of the latest plugin results if you add &expand[]=plugin_results to your request |
*
null
values will be returned when a fact is unknown.
{
"id": "c_165f745e6b",
"watchman_id": "20140620-S994-7TXF1R",
"description": "This is the computer's description",
"agent_version": "6.6.3.650",
"last_update": 1442026136,
"last_report": "2014-10-13T11:12:51.000-05:00",
"created_at": 1442025819,
"group": "g_ac21d783d9",
"computer_name": "Jonathan's MacBook Pro",
"display_name": "Travel MacBook",
"last_user": "jonathan",
"serial_number": "A12BC345DEF6",
"os_version": "OS X 10.10 (14A343f)",
"model_identifier": "MacBookPro10,1",
"model_name": "MacBook Pro (Retina, Mid 2012)",
"applecare_eligibility": false,
"warranty_status": "AppleCare Protection Plan",
"estimated_purchase_date": 1393718400,
"config_description": "MBP 15.4/2.3/8GB/256GB FLASH",
"ram_installed": "8 GB",
"ram_installed_in_bytes": "8589934592",
"ram_speed": "PC3-12800 DDR3 at 1600MHz",
"ram_upgradeable": true,
"ram_max_apple": "16 GB",
"ram_max_actual": "32 GB",
"boot_volume_capacity_in_bytes": 999695822848,
"boot_volume_usage_in_bytes": 270039891968,
"boot_volume_capacity": "999.70 GB",
"boot_volume_usage": "270.04 GB",
"boot_volume_usage_percent": 27.01,
"processor": "Intel Core i7 2.3 GHz (4 core 1 processor)",
"current_uptime": "0 days, 23 hours, 55 mins",
"smc_version": "2.3f36",
"primary_ip": "11.11.11.95",
"active_mac_address": "a4:5e:60:cf:27:6b",
"system_mac_address": "a4:5e:60:cf:27:6b",
"asset_id": null,
"ard_field1": "",
"ard_field2": "",
"ard_field3": "",
"ard_field4": "",
"teamviewer_id": "123456789",
"teamviewer_release": "10",
"teamviewer_unattended": null,
"bomgar_url": null,
"logmein_url": null,
"simplehelp_url": null,
"jss_computer_id": "",
"jss_url": "",
"munki_identifier": "",
"internal_notes": null,
"public_notes": null,
"updates_enabled": true,
"settings_enabled": true,
"report_if_missing": true,
"report_missing_after": 7,
"ignore_missing_until": null,
"rekey_requested": false,
"pending_removal": false,
"agent_removed": false,
"has_issue": true,
"missing": false,
"hidden": false,
"platform": "mac"
}
List Computers
Returns a list of computers in the current subscription. Computer records are returned sorted by last_report, with the most recent computer appearing first.
Param | Default | Purpose |
---|---|---|
status | nil | Filter the computers by current status. Options are: ["visible", "hidden", "missing", "pending_rekey", "pending_removal", "has_muted_plugin"] |
group_id | nil | Only return computers within this Group. You can use the Group's ID or slug*. |
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Set to 5 to start at record 6. |
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
[
{
"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,
...
},
...
]
curl https://your_subdomain.monitoringclient.com/v2.2/computers?api_key=This_Example_API_Key&group_id=g_ac21d783d9
[
{
"id": "c_165f745e6b",
"watchman_id": "20140620-S994-7TXF1R",
"description": "This is the computer's description",
"agent_version": "6.6.3.650",
"last_update": 1442026136,
"last_report": "2014-10-13T11:12:51.000-05:00",
"created_at": 1442025819,
"group": "g_ac21d783d9",
...
},
{
"id": "c_615fe7465b",
"watchman_id": "20131127-DJ0R-P4NFDF",
"description": "Sample computer description",
"agent_version": "6.6.3.650",
"last_update": 1442026136,
"last_report": "2014-10-13T11:12:51.000-05:00",
"created_at": 1442025819,
"group": "g_ac21d783d9",
...
},
...
]
Retrieving a Computer
Retrieves the details of a computer object.
Param | Default | Purpose |
---|---|---|
id | nil | The Watchman ID for the computer you are looking up. |
Returns a computer object if a valid identifier was provided, and returns an error otherwise.
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
{
"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
Attribute | Type | Description |
---|---|---|
id | string | Unique identifier for the Expiration |
license_key | string | The Expiration's license, serial number, or other identifier |
expires_at | integer | The the date the license expires on |
expiration_manufacturer | string | The ID of the expiration_manufacturer |
expiration_product | string | The ID of the expiration_product |
group | string | The ID of the Group. |
computer | string | The ID of the computer. |
renewable | boolean | Is the Expiration renewable |
notes | text | Any notes for this Expiration. |
created_at | integer | Date the Expiration was created |
{
"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.
Param | Default | Purpose |
---|---|---|
manufacturer | nil | Filter Expirations by manufacturer ID or slug. |
product | nil | Filter Expirations by product ID or slug. |
group | nil | Filter Expirations by Group ID or slug. |
computer | nil | Filter Expirations by computer ID or slug. |
license_key | nil | Filter Expirations by license_key. |
expires_at_start | nil | Filter Expirations by expires_at. Requires expires_at_end |
expires_at_end | nil | Filter Expirations by expires_at. Requires expires_at_start |
license_key | nil | Filter Expirations by renewable. |
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Set to 5 to start at record 6. |
GET https://your_subdomain.monitoringclient.com/v2.2/expirations
Example Request
curl https://your_subdomain.monitoringclient.com/v2.2/expirations?api_key=This_Example_API_Key
[
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Expiration you are looking up. |
Returns an Expiration object if a valid identifier was provided, and returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.2/expirations/[expiration_id]
Example Request
curl https://your_subdomain.monitoringclient.com/v2.2/expirations/e_614b9d8c41?api_key=This_Example_API_Key
{
"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
When creating an Expiration you must provide either a group_id or computer_id for the Expiration to be associated to. Expirations created for a given computer_id will automatically be related to the Group of the assigned computer.
Param | Default | Purpose | Required |
---|---|---|---|
license_key | string | The Expiration's license, serial number, or other identifier | Yes |
expires_at | integer | The date the license expires on | Yes |
expiration_manufacturer_id | string | The ID of the expiration_manufacturer | Yes |
expiration_product_id | string | The ID of the expiration_product | Yes |
group_id | string | The ID of the Group. | Yes* |
computer_id | string | The ID of the computer. | Yes* |
renewable | boolean | Is the Expiration renewable | No |
notes | text | Any notes for this Expiration. | No |
group_id
or computer_id
to associate the Expiration to a computer or Group. Both attributes are not required.
Returns an Expiration object if passed attributes pass validation.
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
{
"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.
Param | Default | Purpose | Required |
---|---|---|---|
license_key | string | The Expiration's license, serial number, or other identifier | Yes |
expires_at | integer | The date the license expires on | Yes |
expiration_manufacturer_id | string | The ID of the expiration_manufacturer | Yes |
expiration_product_id | string | The ID of the expiration_product | Yes |
group_id | string | The ID of the Group. | Yes* |
computer_id | string | The ID of the computer. | Yes* |
renewable | boolean | Is the Expiration renewable | No |
notes | text | Any notes for this Expiration. | No |
group_id
or computer_id
to associate the Expiration to a computer or Group. Both attributes are not required.Returns an Expiration object if passed attributes pass validation.
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
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Expiration you are deleting. |
Returns a 204 no content
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
Attribute | Type | Description |
---|---|---|
id | string | Unique identifier for the Expiration Manufacturer |
name | string | The name of the Expiration Manufacturer |
slug | integer | The dashboard url slug for the Expiration Manufacturer |
created_at | integer | Date created |
{
"id": "em_e77660913d",
"slug": "DNSimple",
"name": "Apple",
"created_at": 1440623142
}
List Expiration Manufacturers
Returns a list of Expiration Manufactures in your account.
Param | Default | Purpose |
---|---|---|
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Set to 5 to start at record 6. |
GET https://your_subdomain.monitoringclient.com/v2.2/expiration_manufacturers
Example Request
curl https://your_subdomain.monitoringclient.com/v2.2/expiration_manufacturers?api_key=This_Example_API_Key
[
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Expiration you are looking up. |
Returns a Expiration Manufacturer object if a valid identifier was provided, and returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.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
{
"id": "em_e77660913d",
"slug": "apple",
"name": "Apple",
"created_at": 1440623142
}
Create an Expiration Manufacturer
Param | Default | Purpose | Required |
---|---|---|---|
name | string | The name of the Expiration Manufacturer | Yes |
Returns a Expiration Manufacturer object if passed attributes pass validation.
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
{
"id": "em_e77660913d",
"slug": "dnsimple",
"name": "DNSimple",
"created_at": 1440623142
}
Update an Expiration Manufacturer
Update the details of an Expiration Manufacturer.
Param | Default | Purpose | Required |
---|---|---|---|
name | string | The name of the Expiration Manufacturer | Yes |
Returns a Expiration Manufacturer object if passed attributes pass validation.
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
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Expiration you are deleting. |
Returns a 204 no content
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
Attribute | Type | Description |
---|---|---|
id | string | Unique identifier for the Expiration Product |
name | string | The name of the Expiration Product |
slug | integer | The dashboard url slug for the Expiration Product |
created_at | integer | Date created |
{
"id": "ep_e77660913d",
"slug": "applecare",
"name": "AppleCare",
"created_at": 1440623142
}
List Expiration Products
Returns a list of Expiration Products in your account.
Param | Default | Purpose |
---|---|---|
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Set to 5 to start at record 6. |
GET https://your_subdomain.monitoringclient.com/v2.2/expiration_products
Example Request
curl https://your_subdomain.monitoringclient.com/v2.2/expiration_products?api_key=This_Example_API_Key
[
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Expiration you are looking up. |
Returns a Expiration Product object if a valid identifier was provided, and returns an error otherwise.
GET https://your_subdomain.monitoringclient.com/v2.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
{
"id": "ep_e77660913d",
"slug": "applecare",
"name": "AppleCare",
"created_at": 1440623142
}
Create an Expiration Product
Param | Default | Purpose | Required |
---|---|---|---|
name | string | The name of the Expiration Product | Yes |
Returns a Expiration Product object if passed attributes pass validation.
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
{
"id": "ep_e77660913d",
"slug": "domain-registration",
"name": "Domain Registration",
"created_at": 1440623142
}
Update an Expiration Product
Update the details of an Expiration Product.
Param | Default | Purpose | Required |
---|---|---|---|
name | string | The name of the Expiration Product | Yes |
Returns a Expiration Product object if passed attributes pass validation.
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
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Expiration you are deleting. |
Returns a 204 no content
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
Attribute | Type | Description |
---|---|---|
id | string | Unique identifier for the Note |
computer | string | ID of the computer to which the note belongs* |
group | string | ID of the Group to which the note belongs* |
body | string | The body content of the note |
created_at | integer | Date created |
private | boolean | True when the note is only internally visible |
include_in_email | boolean | True when note is included in emails |
included_in_report | boolean | True when note is included in Computer/Group Status Reports |
null
.
{
"id": "n_70ab8b7f04",
"computer": "c_812666945e",
"group": "g_713e78ad3a",
"body": "This is the note's content.",
"created_at": 1453135662,
"private": false,
"include_in_email": false,
"include_in_report": false
}
List Notes
Returns a list of Notes. If computer_id
and group_id
are left blank, all notes in your account will be returned.
Param | Default | Purpose |
---|---|---|
computer_id | null | The ID of the computer whose notes you wish to retrieve.* |
group_id | null | The ID of the Group whose notes you wish to retrieve.* |
include_private | false | Set to true (true, yes, or 1) if you wish to include private notes in your results. |
page | 1 | The page number where you wish to begin. |
per_page | 50 | The quantity per page in each request. Up to 100 can be returned per-request. |
offset | nil | The number to offset the results by. Set to 5 to start at record 6. |
computer_id
OR group_id
, never both.
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
[
{
"id": "n_c6a844020d",
"computer": "c_cc342c6cc0",
"group": null,
"body": "This is the note's content.",
"created_at": 1453135662,
"private": false,
"include_in_email": false,
"include_in_report": true
},
{
"id": "n_3e412d7744",
"computer": "c_cc342c6cc0",
"group": null,
"body": "The content of this note.",
"created_at": 1453135662,
"private": false,
"include_in_email": true,
"include_in_report": false
},
...
]
Retrieving a Note
Retrieves the details of a Note.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the Note you are looking up. |
Returns a Note object if a valid identifier was provided, and returns an error otherwise. A Note object will contain either a computer or a Group, the other will be null
.
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
{
"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
When creating a Note you must provide either a group_id or computer_id for the Note to be associated to. Sending both a group_id AND computer_id will result in an error.
Param | Type | Purpose | Required |
---|---|---|---|
computer_id | string | The ID of the Computer to which the note will be assigned. | Yes* |
group_id | string | The ID of the Group to which the note will be assigned. | Yes* |
body | string | The text content of the note. | Yes |
private | boolean | Sets the privacy of the note. Default: false | No |
include_in_email | boolean | Sets whether the note is visible in emails. Default: false | No |
include_in_report | boolean | Sets whether the note is visible in emails. Default: false | No |
* Either computer_id
OR group_id
is required, but never both.
Returns a Note object if passed attributes pass validation.
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
{
"id": "n_2f985c3224",
"computer": "c_cc342c6cc0",
"group": null,
"body": "This is the note content.",
"created_at": 1453411465,
"private": false,
"include_in_email": true,
"include_in_report": false
}
Update a Note
Update the details of a Note.
Param | Default | Purpose | Required |
---|---|---|---|
computer_id | string | The ID of the Computer to which the note will be assigned. | No |
group_id | string | The ID of the Group to which the note will be assigned. | No |
body | string | The text content of the note. | No |
private | boolean | Sets the privacy of the note. | No |
include_in_email | boolean | Sets whether the note is visible in emails. | No |
include_in_report | boolean | Sets whether the note is visible in emails. | No |
As with Creating a Note, supplying both a computer_id AND group_id will result in an error.
Returns a Note object if passed attributes pass validation.
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
{
"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.
Param | Default | Purpose |
---|---|---|
id | nil | The ID for the note you are deleting. |
Returns a 204 no content
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.
Param | Default | Purpose |
---|---|---|
id | integer | The unique ID for the plugin result |
name | string | Name of the plugin |
slug | string | Slug for the plugin |
status | string | Current reported status: [OK, Warning, Alert, Informational] |
details | text | The plugins reported details |
last_run | integer | The last time the plugin ran |
muted | boolean | Whether or not the plugin is muted |
mute_type | string | The type of mute in place: ["muted_forever", "timed_mute", "ticket_muted"] |
mute_description | string | A brief description of the mute Only included if plugin is muted |
ticket_number | string | The ticket number for this mute Only included if plugin mute type is "ticket_muted" |
ticket_url | string | The url to the ticket Only included if plugin mute type is "ticket_muted" |
mute_until | integer | The date this plugin is muted until Only included if plugin mute type is "time_muted" |
{
"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
}