ClearWatch API reference

Getting started

Read devices and issues, act on issues, and manage the webhooks ClearWatch sends issue events to.

Authenticate with an API key made under Settings, API keys: Authorization: Bearer cwk_.... A key belongs to an organization and reaches it and every organization below it that ClearWatch covers. It holds only the scopes it was given.

Webhooks: each delivery is a POST of one event envelope (schema Event), signed with the endpoint's secret in the ClearWatch-Signature header as t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 over <t>.<raw body>. Reject a timestamp more than 300 seconds from your clock. During a secret rotation a second v1= signed with the previous secret is present for 24 hours; accept either. Answer 2xx to accept. Anything else is retried with backoff for 24 hours. Delivery is at least once and not in order: drop duplicates by event id and order by sequence.

Base URL: https://api.clearwatch.com/v1
Get a key in ClearWatch: Integrations, API keys
The machine-readable description: openapi.json (OpenAPI 3.1)

curl -H "Authorization: Bearer cwk_..." https://api.clearwatch.com/v1/devices

Your API key, to try requests on this pageKept in this page only, and sent only to this API. Requests run with the key's own scopes and reach, and a write is real.

Your key

GET/v1/key

Which key this is, what it may do, and whose it is

Any valid key.

Responses

200 OK Key
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Organizations

GET/v1/organizations

Organizations in reach

Needs the watch:devices:read scope.

Parameter	In	Type	About
cursor	query	string	The `next_cursor` of the previous page.
limit	query	integer	Default 50.

Responses

200 OK Organization
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/organizations/{id}/custom-fields

The custom field values that apply to an organization, inherited or set there

Needs the watch:custom-fields:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

PATCH/v1/organizations/{id}/custom-fields

Set, clear or lock custom field values on an organization; a field left out keeps its value

Needs the watch:custom-fields:write scope.

Parameter	In	Type	About
id *	path	string

Request body

values object, requiredField key (or id) to value. Null or an empty string clears it here.
locks objectField key (or id) to whether the value binds everything below. Organizations and locations only.

Responses

200 OK
400 A value that does not parse, a field that does not apply or is locked above, or a key that is not a field here. Error
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Locations

GET/v1/locations

Locations in reach

Needs the watch:devices:read scope.

Parameter	In	Type	About
organization_id	query	string	Narrow to one organization and those below it.
cursor	query	string	The `next_cursor` of the previous page.
limit	query	integer	Default 50.

Responses

200 OK Location
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/locations/{id}/custom-fields

The custom field values that apply to a location, inherited or set there

Needs the watch:custom-fields:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

PATCH/v1/locations/{id}/custom-fields

Set, clear or lock custom field values on a location; a field left out keeps its value

Needs the watch:custom-fields:write scope.

Parameter	In	Type	About
id *	path	string

Request body

values object, requiredField key (or id) to value. Null or an empty string clears it here.
locks objectField key (or id) to whether the value binds everything below. Organizations and locations only.

Responses

200 OK
400 A value that does not parse, a field that does not apply or is locked above, or a key that is not a field here. Error
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Devices

GET/v1/devices

Managed devices, most recently seen first

Needs the watch:devices:read scope.

Parameter	In	Type	About
organization_id	query	string	Narrow to one organization and those below it.
location_id	query	string	Narrow to one location. Needs organization_id.
cursor	query	string	The `next_cursor` of the previous page.
limit	query	integer	Default 50.

Responses

200 OK Device
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/devices/{id}

One device

Needs the watch:devices:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK Device
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/devices/{id}/custom-fields

The custom field values that apply to a device, inherited or set there

Needs the watch:custom-fields:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

PATCH/v1/devices/{id}/custom-fields

Set, clear or lock custom field values on a device; a field left out keeps its value

Needs the watch:custom-fields:write scope.

Parameter	In	Type	About
id *	path	string

Request body

values object, requiredField key (or id) to value. Null or an empty string clears it here.
locks objectField key (or id) to whether the value binds everything below. Organizations and locations only.

Responses

200 OK
400 A value that does not parse, a field that does not apply or is locked above, or a key that is not a field here. Error
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Issues

GET/v1/issues

Issues, newest opened first

Needs the watch:issues:read scope.

Parameter	In	Type	About
status	query	open \| closed \| all	Default open.
outcome	query	alert \| attention
device_id	query	string
organization_id	query	string	Narrow to one organization and those below it.
location_id	query	string	Narrow to one location. Needs organization_id.
cursor	query	string	The `next_cursor` of the previous page.
limit	query	integer	Default 50.

Responses

200 OK Issue
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/issues/{id}

One issue

Needs the watch:issues:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK Issue
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/issues/{id}/events

An issue's timeline, oldest first

Needs the watch:issues:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK TimelineEntry
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/issues/{id}/acknowledge

Acknowledge an issue; stops escalation

Needs the watch:issues:write scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK Issue
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
409 The issue is not in a state this applies to. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/issues/{id}/unacknowledge

Take an acknowledgment back

Needs the watch:issues:write scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK Issue
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
409 The issue is not in a state this applies to. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/issues/{id}/notes

Add a note to an issue's timeline

Needs the watch:issues:write scope.

Parameter	In	Type	About
id *	path	string

Request body

text string, required

Responses

201 Added
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/issues/{id}/resolve

Resolve an open issue by hand (ClearPath keys only)

Needs the watch:issues:resolve scope.

Parameter	In	Type	About
id *	path	string

Request body

reason string, required

Responses

200 OK Issue
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
409 The issue is not in a state this applies to. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Webhooks

GET/v1/webhooks

Webhooks in reach

Needs the watch:webhooks:read scope.

Responses

200 OK Webhook
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/webhooks

Make a webhook; the response carries its secret, once

Needs the watch:webhooks:write scope.

Request body (WebhookInput)

organization_id stringOn create only. Defaults to the key's own organization.
name string
url stringHTTPS, on a public address.
subscribe boolean
event_types string[]
enabled booleanOn update only.

Responses

201 Created
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/webhooks/{id}

One webhook

Needs the watch:webhooks:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK Webhook
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

PATCH/v1/webhooks/{id}

Change a webhook; a field left out keeps its value

Needs the watch:webhooks:write scope.

Parameter	In	Type	About
id *	path	string

Request body (WebhookInput)

organization_id stringOn create only. Defaults to the key's own organization.
name string
url stringHTTPS, on a public address.
subscribe boolean
event_types string[]
enabled booleanOn update only.

Responses

200 OK Webhook
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

DELETE/v1/webhooks/{id}

Delete a webhook and its log

Needs the watch:webhooks:write scope.

Parameter	In	Type	About
id *	path	string

Responses

204 Deleted
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/webhooks/{id}/test

Send a ping now and report the answer

Needs the watch:webhooks:write scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/webhooks/{id}/rotate-secret

A new signing secret, returned once

Needs the watch:webhooks:write scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/webhooks/{id}/deliveries

Recent deliveries and attempts

Needs the watch:webhooks:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

IPAM

GET/v1/ipam/subnets

Tracked IPAM subnets and blocks in reach, with utilization and the next free address

Needs the watch:ipam:read scope.

Parameter	In	Type	About
organization_id	query	string	Narrow to one organization and those below it.
location_id	query	string	Narrow to one location. Needs organization_id.
cursor	query	string	The `next_cursor` of the previous page.
limit	query	integer	Default 50.

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/ipam/subnets/{id}/addresses

Every address seen in one subnet, with its status and every source that saw it

Needs the watch:ipam:read scope.

Parameter	In	Type	About
id *	path	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/ipam/reservations

One subnet's reservations

Needs the watch:ipam:read scope.

Parameter	In	Type	About
subnet_id *	query	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

POST/v1/ipam/reservations

Reserve an address or a range inside a subnet

Needs the watch:ipam:write scope.

Request body

subnet_id string, required
first_ip string, required
last_ip stringFor a range. Omit for one address.
kind string
label string
description string
mac string
device_id string
permanent boolean

Responses

201 Created
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

DELETE/v1/ipam/reservations/{id}

Remove a reservation

Needs the watch:ipam:write scope.

Parameter	In	Type	About
id *	path	string

Responses

204 Removed
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/ipam/vlans

Tracked VLANs in reach

Needs the watch:ipam:read scope.

Parameter	In	Type	About
organization_id	query	string	Narrow to one organization and those below it.
location_id	query	string	Narrow to one location. Needs organization_id.
cursor	query	string	The `next_cursor` of the previous page.
limit	query	integer	Default 50.

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

GET/v1/ipam/next-free

The first free address in a subnet; does not reserve it

Needs the watch:ipam:read scope.

Parameter	In	Type	About
subnet_id *	query	string

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
404 Not found, or not in this key's reach (one answer for both). Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Custom fields

GET/v1/custom-fields

Custom field definitions in reach

Needs the watch:custom-fields:read scope.

Responses

200 OK
401 No key, or a key that is unknown, revoked or expired. Error
403 The key does not have the scope this needs. Error
429 More than 120 requests this minute for this key. See Retry-After. Error

Schemas

Error

error object, required
- code string, required
- message string, required

Scope

watch:devices:read: Organizations, locations and devices, with their status and last check-in.

watch:issues:read: Open and closed issues (Alerts and Needs attention) and their timelines.

watch:issues:write: Acknowledge an issue, take an acknowledgment back, and add a note to its timeline.

watch:issues:resolve: Close an open issue with a reason. ClearPath keys only, as in the console.

watch:webhooks:read: Webhook endpoints and their delivery logs. Never a signing secret.

watch:webhooks:write: Create, change, test and delete webhook endpoints.

watch:custom-fields:read: Custom field definitions, and the values that apply to devices, locations and organizations. A secret reads as set or not set, never its value.

watch:custom-fields:write: Set, change, clear and lock custom field values on devices, locations and organizations, secrets included (write only).

watch:ipam:read: Tracked subnets and blocks, the addresses in a subnet with their status, reservations, VLANs and the next free address.

watch:ipam:write: Create and remove IPAM reservations, for a provisioning tool that takes the next free address.

Key

id string
name string
organization Named
scopes Scope
reaches_every_client boolean

Named

id string, required
name string, required

Organization

id string
name string
parent_id string or null

Location

id string
organization_id string
parent_location_id string or null
name string
address string or null
timezone string or null

Device

id string
organization Named
location Named or null
name string
hostname string
kind stringagent or bridge (watched by a ClearBridge, no agent).
device_type string or null
os string or null
os_version string or null
agent_version string or null
manufacturer string or null
model string or null
serial_number string or null
address string or null
status string
last_seen_at string or null
enrolled_at string (date-time)
url string

Issue

id string
organization Named
device object
- id string
- name string
- label_when_opened string
subject string
source string
outcome stringalert is on the Alerts list; attention is Needs attention.
state stringwarning or critical, now.
worst_state stringThe worst state reached while open.
headline string
detail string
status string
opened_at string (date-time)
last_seen_at string (date-time)
closed_at string or null
close_reason string or null
closed_by string or null
acknowledged_at string or null
acknowledged_by string or null
url string

TimelineEntry

id string
at string (date-time)
kind string
detail string
actor string or null

Webhook

id string
organization Named
name string
url string
enabled boolean
subscribe booleanSent every event of event_types, not only what policy steps send it.
event_types string[]
disabled_at string or null
disabled_reason string or null
failing_since string or null
last_success_at string or null
last_failure_at string or null
rotating_secret boolean
created_at string (date-time)
created_by string

WebhookInput

organization_id stringOn create only. Defaults to the key's own organization.
name string
url stringHTTPS, on a public address.
subscribe boolean
event_types string[]
enabled booleanOn update only.

Event

issue.opened: An issue opened

issue.updated: An issue got worse or better while open

issue.acknowledged: Somebody said they are on it

issue.unacknowledged: An acknowledgment was taken back

issue.resolved: An issue closed (recovered, or resolved by hand)

issue.note_added: A note was added

issue.routed: A policy step sent the issue here

ping: A test from the Send test button

id string, required
type string, required
version integer, required
sequence integer, required
occurred_at string (date-time), required
organization Named or null, required
data object, required
- issue object or null
- device object or null
- change object
  - kind string
  - detail string
  - actor string or null