Computer Record Custom Namev2.5 Update - Date Released: 14 Jun 2024

The custom_name attribute is allowed in the Update Computer action.

Changes

  • New update_computer - Set a string value (max 191 characters, less than 30 recommended) for a Computer Record.
  • Change Documentation updated to reflect current headers, which are all lower-case. See Pagination

Computer/Group URLs v2.5 Expansion - Date Released: 11 Sep 2020

Additional attribute with complete URL for the Computer object and Group object.

Changes

  • New computer_url - Complete URL to computer record in the Dashboard
  • New group_url - Complete URL to group in the Dashboard

Computer Object Filters v2.5 Expansion - Date Released: 18 Aug 2020

Additional filters including serial number, added ID, reference email and platform for the Computer object.

Changes

  • New serial_number - Filter computers by Serial Number.
  • New asset_id - Filter computers by Asset ID.
  • New reference_email_computer - Filter computers by reference email address for computer(s).
  • New reference_email_group - Filter computers by reference email address for group.
  • New reference_email - Filter computers by reference email address, searching both computer and group reference email addresses.
  • New platform - Filter computers by platform. Options are: linux, mac, windows

Agent Version Consolidation v2.5 Expansion - Date Released: 22 May 2018

The Linux, Mac, and Windows versions are moving to a single version string. The concept of Build Number will be represented within the last of the four-segment version. To retain backwards compatibility in the API, the version will be printed in the build string. The separate build element will be removed in our next major release.

Changes

  • Deprecation Build is becoming an alias of Version, and will be removed in a future release.

Computer Object Update v2.5 Expansion - Date Released: 20 May 2018

This update also adds access to the Visible attribute on the Plugin Result Object.

Changes

  • New visible boolean attribute for the visible state of service plugins

Computer Object Update v2.5 Expansion - Date Released: 6 Mar 2018

This update deprecates watchman_id in favor of client_id for the Computer object.

Changes

  • New Added a new attribute client_id to the Computer object.
  • Deprecation watchman_id attribute will be sent as an alias for client_id on the Computer object and removed in next API version.

Reference Email, Beacon Controls, User Management v2.5 Expansion - Date Released: 27 Nov 2017

This update surfaces more controls for Groups and Computer Records. The ability to enable or disable Beacon Reporting is granted on a per-computer basis. A new user endpoint is added, allowing the programmatic addition or removal of users in a Company.

Changes

Mute Plugin Result Update v2.5 Expansion - Date Released: 22 Sept 2017

This update adds the ability to optionally pass a ticket_url parameter when muting a plugin result.

Changes

  • New ticket_url parameter can be optionally passed with a timed or ticket mute_type
  • Change A ticket system must be activated to mute a plugin result via a ticket mute_type

Group Object Update v2.5 Expansion - Date Released: 30 Mar 2017

This update adds access to the Description and Contact Menu visibility attributes on the Group Object.

Changes

Group Object Update v2.5 Expansion - Date Released: 28 Dec 2016

This update adds a new Find or Create Endpoint as well as some support for additional attributes on the Group object.

Changes

  • New Added a new Find or Create Endpoint to the Group object.
  • New Added mac_installer_ready to the Group object. This attribute will return a boolean value based on whether its Group-Specific mac installer has been published. (Usually within 20 seconds).
  • New Added mac_installer_url to the Group object. This attribute will return the URL to the Group-Specific Mac pkg installer.
  • New Added windows_installer_ready to the Group object. This attribute will return a boolean value based on whether its Group-Specific windows installer has been published. (Usually within 60 seconds).
  • New Added windows_installer_url to the Group object. This attribute will return the URL to the Group-Specific Windows msi installer.

Computer Object Update v2.5 Expansion - Date Released: 23 Nov 2016

This update adds access to Operating System attributes on the Computer Object.

Changes

  • New Added os_version_number to the computer object. This attribute will return only the numbered version of the os_version. i.e. 10.12.1
  • New Added os_version_number_max to the computer object. This attribute will return the latest, compatible Operating System Number the Computer can support; 0.0.0 will be returned when the computer can support the lastest released Operating System.

V2.5 Major Update Date Released: 20 Nov 2016

This update includes key changes to the universal resource ID's, Computer Object, Plugin Result Object and the removal of support for all previously deprecated elements.

Universal Resource Object ID's will now be referenced as UID

Where the Universal Resource Object ID has been "id": "c_165f745e6b", it will now be "uid": "c_165f745e6b".

Computer Object

In v2.5, This API can now be used to update the asset_id and description of the Computer Object.

Plugin Result Object

In former versions of the API the Plugin Result slug was being passed as the Plugin Result id. In this version, the slug and uid are different attributes.

  • New Added unique identifier for Plugin Result: uid.
  • Change The former ID is now the slug.

Misc Changes

  • New Adds documentation for Character Limits on the various Create and Update Endpoints.

Computer Object Update v2.2 Expansion - Date Released: 07 July 2016

This update adds access to Boot Volume attributes in raw bytes on the computer object.

Changes

  • New Added boot_volume_capacity_in_bytes to the computer object.
  • New Added boot_volume_usage_in_bytes to the computer object.

Computer Object Update v2.2 Expansion - Date Released: 24 May 2016

This update adds access to Boot Volume Usage Percent on the computer object. This is a decimal output of the percentage of volume that is used.

Changes

  • New Added boot_volume_usage_percent to the computer object.

Computer Object Update v2.2 Expansion - Date Released: 29 Apr 2016

This update adds access to Boot Volume attributes on the computer object. Raw values in bytes will be added in a future release.

Changes

  • New Added boot_volume_capacity to the computer object.
  • New Added boot_volume_usage to the computer object.

Computer Object Update v2.2 Expansion - Date Released: 22 Apr 2016

This update changes the Computer Name attribute on the computer object.

Changes

  • change Replaces machine_name with computer_name. The old value will be sent until API v2.3

Computer Object Update v2.2 Expansion - Date Released: 11 Apr 2016

This update adds some RAM related attributes on the computer object.

Changes

  • New Added ram_installed_in_bytes to the computer object.
  • New Added ram_speed to the computer object.
  • New Added ram_upgradeable to the computer object.
  • New Added ram_max_apple to the computer object.
  • New Added ram_max_actual to the computer object.
  • change Replaces installed_ram with ram_installed. The old value will be sent until API v2.3

Notes Update v2.2 Expansion - Date Released: 25 Feb 2016

This update coincides with the release of the new Notes feature in the Watchman UI. Previously, notes on Groups and computers were limited to a single, editable field. Now, notes have been moved out to their own resource which gives you greater flexibility on how Notes are seen and used. The old notes have been moved to a new field called `description`.

With this API update, Notes can now be managed through API access as well.

Changes

  • New Added Notes resource.
  • Fix CURL examples for the create and update methods for several resources have been corrected.
  • Fix Added a missing created_at of the Group's creation date. The old value will be sent until API v2.3
  • change Replaces Display Name with Custom Name. The old value will be sent until API v2.3

V2.2 Major Release Date Released: 29 Sep 2015

This update is the start of some enhancements to the Watchman Monitoring API to prepare for future expansion. Key changes include universal resource ID's, expandable resources and better JSON error responses.

Universal Resource Object ID's

This is going to be the largest change as you move form v2.1 to v2.2.

As we move towards expanding our API we've added uniform resource IDs. As of API v2.2 each resource returned in our API will have a unique ID with a similar structure. For example the a computer's ID might look something like c_165f745e6b and a Group's ID might be g_ac21d783d9.

These changes mean that you will no longer lookup computers by their Watchman ID, nor Groups by their slug. Instead always use this new ID structure.

Expandable Resources

In v2.1, when a resource had a nested resource we expended it by default. We found that this was causing a fair amount of load for users who didn't "need" all of that info. As of v2.2 we will not auto expand any related resource but rather we'll just return its ID. This change resulted in almost a 2 second response time increase in cases where you don't need the expanded resources.

How it works

Many resource objects contain the ID of another object in their response properties. Those objects can now 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. You can nest expand requests 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 a full customer object.

Example
Let's use a computer record as an example. Say we wanted to get the computer with the ID of c_165f745e6b. Our request would look something like this:

GET https://your_subdomain.monitoringclient.com/v2.2/computers/c_165f745e6b?api_key=This_Example_API_Key

{
  "id": "c_165f745e6b",
  "watchman_id": "20140620-S994-7TXF1R",
  "agent_version": "6.3.1",
  "build_number": "7D306",
  "last_report": 1442026136,
  "date_created": 1442025819,
  "group": "g_ac21d783d9",
  ...
}
You can see in the example above that only the Group ID is returned when we requested the computer. We can use the expansion API to expand that Group with the request like this:

GET https://your_subdomain.monitoringclient.com/v2.2/computers/c_165f745e6b&expand[]=group?api_key=This_Example_API_Key

{
  "id": "c_165f745e6b",
  "watchman_id": "20140620-S994-7TXF1R",
  "agent_version": "6.3.1",
  "build_number": "7D306",
  "last_report": 1442026136,
  "date_created": 1442025819,
  "group": {
    "id": "g_ac21d783d9",
    "slug": "test-group",
    "name": "Test Group",
    "notes": "Sample note text",
    "visible_computer_count": 2,
    "hidden_computer_count": 0,
    "created_at": 1442025819
  },
  ...
}

Better JSON Errors

We've modified the error response to be more than the string description provided in v2.1. The new JSON errors array will provide you with more detail than before about the error you've encountered. Whenever the API returns an error you'll receive a JSON array of one or more errors. These errors consist of the following keys:

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

Misc Changes

  • Fix Fixed an issue where the Plugin Result mute values sent didn't match the documentation.
  • Change Removed the ID key on the Plugin Result
  • Change Removed the version key on the Plugin Result
  • Change Changed the status key on the Plugin Result to all lowercase.
  • Change Changed computers date_created key to created key for uniformity with other resources.
  • Change Timestamps are now being sent as integers as seconds since epoch.
  • Change Updated the ID for computer object.
  • New Added watchman_id to the computer object.
  • Change Updated the ID for Group object.
  • New Added slug to the Group object.
  • New Added Expirations.
  • New Added Expiration Manufacturers.
  • New Added Expiration Products.

Attribute updates v2.1 Expansion - Date Released: 30 July 2015

Text Change v2.1 Expansion - Date Released: 03 June 2015

  • Change Changed "Error" as a plugin status to "Warning" to be more accurate.

Attribute updates v2.1 Expansion - Date Released: 02 Apr 2015

Attribute updates v2.1 Expansion - Date Released: 06 Mar 2015

2.1 Major Release Date Released: 18 Dec 2014

  • Change Updated resource names for Clients and ClientGroups to Computers and Groups respectively.
  • Change Updated the Authentication token parameter to api_key for clarity.
  • New We've introduced point versioning for non-backwards compatible changes.
  • New Complex pagination.
  • New List objects. The API will now always return a resource object or array of resource objects.