Acting on incidents and scans

Besides reading, the API can do three things you do by hand in the console: acknowledge an incident, resolve an incident and run a scan of a domain now. A key can do them only with the incidents.edit or domains.edit scope, and only while your role holds the same permission; see authentication and keys.

Each call is a POST with no body. The organisation is the key’s, never a parameter. A write counts in the same rate limits as a read, and appears in the audit trail with the key that made it.

Call	Scope	Answers
POST /v1/incidents/{incident_uuid}/acknowledge	incidents.edit	200, the incident
POST /v1/incidents/{incident_uuid}/resolve	incidents.edit	200, the incident and its resolution
POST /v1/domains/{domain_uuid}/scans/{scan_type}	domains.edit	202, the queued scan
GET /v1/scans/{scan_uuid}	domains.view	200, the scan’s progress

An uuid that does not exist, or belongs to another organisation, answers 404 not_found: the two cannot be told apart. A scope or permission the key lacks answers 403 forbidden.

Acknowledge and resolve an incident

curl -X POST -H "Authorization: Bearer $WT15_API_KEY" \
  https://rest.watchtower15.com/v1/incidents/$INCIDENT_UUID/acknowledge

Both calls do what the console’s buttons do, including the notifications they send, which name the member the key acts as. They answer the incident after the call:

{
  "data": {
    "uuid": "…",
    "status": "acknowledged",
    "changed": true,
    "acknowledged_at": 1793000000000,
    "acknowledged_by": { "name": "…" }
  }
}

• changed says whether this call did anything. An incident that is already acknowledged or resolved answers 200 with changed false and is left as it was, so a script can call again safely.
• Resolve answers resolved_at, resolved_by and resolution. resolution is null when changed is false. Otherwise it is checked_again, which means the next alarm pass opens a new incident if the condition still holds, or accepted, which means WatchTower15 accepted the change (a closed port, a stopped service) and the alarm returns only when the port or service comes back and stops again.

Run a scan now

curl -X POST -H "Authorization: Bearer $WT15_API_KEY" \
  https://rest.watchtower15.com/v1/domains/$DOMAIN_UUID/scans/ssl

scan_type is dns, expiry, information (WHOIS) or ssl, on any domain of the organisation, as the console’s Trigger a scan now accepts them. The call queues the scan and answers at once with 202:

{
  "data": {
    "scan_uuid": "…",
    "scan_type": "ssl",
    "status": "queued",
    "queued_at": 1793000000000,
    "domain_uuid": "…"
  }
}

Follow the scan

GET /v1/scans/{scan_uuid} answers the scan’s progress until it ends:

• uuid, scan_type and domain_uuid;
• status: queued, running, completed, failed or timeout. The set is open, so a script treats a value it does not know as “not finished yet”;
• outcome: what a finished scan found, for example data_found or no_data; null until it ends;
• queued_at, started_at, completed_at and execution_time_ms;
• error_message: why a scan failed, as the console shows it.

It does not return what the scan found. The findings of a DNS, expiry or SSL scan are on GET /v1/domains/{domain_uuid}/scans; the findings of a WHOIS (information) scan, which hold registrant data, stay in the console.

The cooldown

A scan costs money and load, so a domain can be scanned at most once every 10 minutes for each scan type. A second call inside that time answers 429 rate_limited with Retry-After, the seconds left, and starts nothing:

{ "type": "…/api/errors/rate_limited/", "status": 429, "code": "rate_limited",
  "detail": "This domain's SSL certificate scan was started less than 10 minutes ago. Retry after 412 s." }

Back off for Retry-After seconds; do not retry at once. It holds for every key and every caller of the API, and also after a 500 from this call: the scan may have been queued, so a script waits for the next answer’s Retry-After instead of calling again.

Billing

A scan is billed as it is in the console. When the organisation has no payment method, or an invoice is overdue, the call answers 402 payment_required or invoice_overdue: nothing is billed and no cooldown starts, so the call can be repeated once the billing is settled.