Getting started with the API

The WatchTower15 API is a versioned REST API for your scripts, CI jobs and integrations. It reads what you see in the console — servers, domains, services, incidents, alarms, logs, custom metrics and databases — as a member of your organisation, with a key you control. Version 1 also does three things you do by hand: it acknowledges an incident, resolves an incident and runs a domain scan. See acting on incidents and scans.

https://rest.watchtower15.com/v1

Every call is HTTPS, every answer is JSON, and the reference lists every operation with its parameters and answers. It is generated from the API’s OpenAPI 3.1 document.

Who can create a key

A key acts as the member who creates it, in one organisation. You can create one when your role holds the API access permission, api_access.view. Admins hold it; another role holds it only when your organisation grants it (see roles & permissions). api_access.edit is the permission for keys that may change things: acknowledge and resolve incidents, run domain scans.

A key can only be given scopes that you hold yourself, and it never sees more than your role does. See authentication and keys.

Create a key

1. Open your Profile and go to its API tab.
2. Choose the organisation, name the key, tick the areas it may read or change and set how long it lives (the dialog suggests 90 days).
3. Copy the key when it is shown. It is shown once, and WatchTower15 keeps only a one-way hash of it, so a lost key is replaced, not recovered.

Keep it in a secret store — an environment variable in your CI, a secrets manager — never in source control.

Make the first call

curl -H "Authorization: Bearer $WT15_API_KEY" https://rest.watchtower15.com/v1/me

GET /v1/me answers who the key acts as: the key (its name, scopes and expiry), the member and the organisation. If it answers 401, see errors.

{
  "data": {
    "key": { "uuid": "…", "name": "CI deploy", "scopes": ["servers.view"], "expires_at": 1793000000000 },
    "user": { "uuid": "…", "name": "…", "email": "…" },
    "organisation": { "uuid": "…", "name": "…" }
  }
}

A list is GET /v1/servers, and the first row’s uuid opens it: GET /v1/servers/{server_uuid}. The organisation is never a parameter: it is the key’s.

Good to know

• Not from a browser. The API sends no CORS headers, so a browser page cannot call it, and a key in a web page is a leaked key. Call it from a server, a script or a CI job.
• Pace yourself. A key may make 60 calls a minute, and a domain can be scanned once every 10 minutes for each scan type; see rate limits.
• Errors are structured. Every failure is a problem document with a stable code; see errors.
• Pages. Lists return a cursor for the next page; see pagination.
• Times. Windows and instants have one shape everywhere; see times and windows.
• It will not break under you. See versioning.

The same ingest endpoints for logs and custom metrics use their own per-source tokens and are separate from API keys.