Outage Clock REST API
Manage followed vendors and read the latest poll from your own scripts. JSON over HTTPS. Business plan only.
Authentication
Create a key in Settings. It is shown once; we store only a hash. Send it as a bearer token:
curl -H "Authorization: Bearer ocl_..." https://www.outageclock.com/api/v1/monitorsRevoke a key in Settings at any time. Keys act on the account they were created in.
Rate limits
Keep to 60 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you may get 429 with Retry-After; back off and retry.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/monitors | List followed vendors with the latest status. |
| POST | /api/v1/monitors | Follow a vendor. Body {"hostname": "github.com"} or a catalog name. Returns 201, 402 over the plan limit, or 409 if it already exists. |
| GET | /api/v1/monitors/{id} | One followed vendor. |
| GET | /api/v1/monitors/{id}/checks | The last 50 polls. |
| POST | /api/v1/monitors/{id}/check | Poll now and return the result. |
| DELETE | /api/v1/monitors/{id} | Stop following. Returns 204. |
| GET | /api/catalog | Public catalog of vendors (id, name, domain, format). |
Vendor object
{
"id": "...", "hostname": "github", "port": 443, "paused": false,
"status": "ok" | "problem" | "pending",
"error_code": null | "incident" | "unreachable" | "too_large",
"overall_status": "operational",
"open_incidents": 0,
"subject": null,
"reachability_ok": true,
"components": [],
"last_checked_at": "...",
"created_at": "..."
}overall_status is operational, degraded, partial_outage, major_outage or maintenance. open_incidents is the count of current incidents. error_code is incident, unreachable or too_large when status is problem.
Errors
Errors return {"error": "code", "message": "..."} with codes unauthorized, invalid_json, invalid_hostname, plan_limit, plan_required, duplicate, not_found and rate_limited.
Signed webhooks
Add a webhook URL in Settings to receive alerts as JSON. Starter and up. Custom payload templates start on Business. Each POST has X-OutageClock-Event and X-OutageClock-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + raw body with your signing secret. Reject requests older than five minutes. Events include vendor.incident, vendor.update, vendor.resolved, vendor.maintenance, vendor.reachability and vendor.digest.