The public API is included in the Team and Stack plans. Keys created on other plans return 403 PLAN_REQUIRED.

​
Overview

Every request to the public API is authenticated with an API key that belongs to your account. A key:
  • Sees the same monitors you see in the dashboard, including team and shared monitors
  • Can only do what its permissions (scopes) allow
  • Stays active until you revoke it
  • Has its own rate limit

​
Base URL

https://api.watchmantower.com/public/v1

​
Sending the key

Send the secret key in the Authorization header with the Bearer prefix: 
GET /public/v1/site HTTP/1.1
Host: api.watchmantower.com
Authorization: Bearer wt_sk_live_...

curl https://api.watchmantower.com/public/v1/site \
  -H "Authorization: Bearer $WATCHMAN_API_KEY"
No other header or query parameter is accepted.

​
Key format

Creating a key returns two values:
ValueFormatUse
Secret keywt_sk_live_ followed by 64 hex charactersSent in the Authorization header. Shown only once.
Public keywt_pk_live_ followed by 16 hex charactersIdentifies the key in the dashboard. Not a credential.
Watchman Tower stores only a hash of the secret. If you lose it, revoke the key and create a new one.

​
Creating keys

  1. Open the dashboard and go to API Keys from the account menu.
  2. Click Create API Key.
  3. Enter a name (3 to 64 characters) and select at least one permission.
  4. Copy the secret key. It is not shown again.
An account can have up to 10 active keys.

​
Permissions (scopes)

Each endpoint requires one scope. A key without the required scope gets 403 INSUFFICIENT_SCOPE.
ScopeAllows
uptime.readList and view monitors, response times
uptime.writeCreate and delete monitors
Your role still applies on top of scopes: a key cannot read or change a monitor that your account cannot access. Give each key only the scopes it needs. A reporting script needs uptime.read, not uptime.write.

​
Rate limits

Each key can make 60 requests per minute by default. Every response includes: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1760190000
X-RateLimit-Reset is a Unix timestamp in seconds. When the limit is exceeded the API returns 429 RATE_LIMITED with a Retry-After header. Repeated requests with invalid keys from the same IP address are blocked for 10 minutes (429 TOO_MANY_AUTH_FAILURES).

​
Errors

Errors use the same JSON shape as successful responses, with a machine-readable error code: 
{
  "success": false,
  "message": "Invalid API key",
  "code": 401,
  "error": "INVALID_API_KEY"
}
StatuserrorMeaning
401INVALID_API_KEYMissing, malformed, unknown or revoked key
403PLAN_REQUIREDYour plan does not include API access
403INSUFFICIENT_SCOPEThe key lacks the scope this endpoint needs (requiredScope names it)
404NOT_FOUNDThe resource does not exist or your account cannot access it
429RATE_LIMITEDPer-key rate limit exceeded
429TOO_MANY_AUTH_FAILURESToo many invalid-key attempts from your IP address

​
Security best practices

Environment Variables

Store keys in environment variables or a secret manager, never in source code

Separate Keys

Use a separate key for each integration so you can revoke one without breaking the others

Minimum Scopes

Select only the scopes the integration needs

Revoke Unused Keys

Check “Last used” on the API Keys page and revoke keys you no longer need

​
Next Steps

API Overview

Learn about the API

Create Site

Create a new monitoring site

Dashboard

Use the dashboard to manage API-related workflows

Alerts

Learn how alerts are delivered