API Reference

Watchdog exposes two HTTPS endpoints on port 8900. Both endpoints are rate-limited; the default limit is configured in watchdog.conf and can be changed there.

Check License

Validates a controller's license, registers the controller if not already known, and returns the matched configuration.

Endpoint: POST /api/check-license/

Request fields (all required):

Field	Type	Notes
`guid`	UUIDv4 string	Controller GUID. Must parse as UUID version 4.
`hostname`	string	Controller hostname.
`version`	string	Controller version.
`ip_addresses`	list of strings	Controller-side IP addresses (used for department `address` matching).
`mac_address`	string	Controller MAC address.
`os`	string	Operating system identifier.
`label`	string	Optional grouping label set on the controller.
`logdir`	string	Controller log directory. Required in the request but not used server-side.

Success response — 200 OK:

{
  "message": "Valid License",
  "default": { ... matched department configuration from browsermon-watchdog.conf ... }
}

If no department matches, default is returned as {}.

Error responses:

Status	`message` body	Cause
`400`	`<Field> is required`	A required field was missing from the request.
`400`	`Invalid GUID format`	`guid` did not parse as UUIDv4.
`403`	`Invalid license`	The Watchdog license itself is not valid.
`403`	`Controller is blacklisted`	The controller's GUID or source IP matches an entry in `watchdog-blacklist.conf`. See Configuration Reference.
`403`	`No devices available`	The licensed controller cap has been reached and this GUID is not yet registered.

Note: When blacklist=ip, the blacklist is checked against the controller's connection source IP as seen by Watchdog — not against the ip_addresses payload field. Controllers behind a NAT or proxy will share the same source IP.

Get Active Controllers

Returns the list of controllers currently registered against the license.

Endpoint: GET /api/get-licenses/

Success response — 200 OK:

{
  "active_controllers": [
    {
      "guid": "00000000-0000-4000-8000-000000000000",
      "timestamp": "2026-04-29 14:32:01",
      "ip_addr": "10.1.2.3",
      "hostname": "endpoint-01"
    }
  ]
}

Field	Description
`guid`	Controller GUID.
`timestamp`	First registration time (server local time, `YYYY-MM-DD HH:MM:SS`).
`ip_addr`	Source IP recorded at registration time.
`hostname`	Hostname recorded at registration time.

ip_addr and hostname were added in 4.1.0.

Error responses:

Status	`message` body	Cause
`403`	`Invalid license`	The Watchdog license itself is not valid.

Rate Limiting

Both endpoints have a default request rate limit. The limit is configured in watchdog.conf:

rate=100/m
limit=True

rate follows the <count>/<unit> format (s, m, h, d).
limit=True blocks requests over the threshold; limit=False only counts them.

Adjust both values to match your deployment scale.