The API
A read-only HTTP API over your workspace — clients, sites, incidents and uptime — for putting your own dashboard, status board or export on top of it. Keys are created in the console under API.
Getting a key#
In the console: API in the sidebar, then Create key. The key is shown once. Only a hash of it is stored, so it cannot be shown again — if it is lost, revoke it and make another. Revoking takes effect on the next request.
A key reads the whole workspace, so only an owner or admin can create one. It is not a per-person credential: give each integration its own key with a name that says what it is, and the “last used” column will tell you which ones are safe to turn off.
Authorization header and nowhere else. There is deliberately no ?api_key= parameter: a key in a URL is copied into nginx’s access log, the browser’s history and every Referer header that leaves the page.Calling it#
curl https://zutpralik.click/api/v1/sites \
-H "Authorization: Bearer zk_YOUR_KEY"Every response is JSON. Lists are plain arrays, with the total in an X-Total-Count header so a caller can page without unwrapping an envelope. Dates are ISO 8601 in UTC. A value that was never measured is null — never zero, and never a made-up default.
GET /api/v1 answers with the version, which key you are using and the list of endpoints. It is the cheapest way to check a key works.
The endpoints#
- GET /api/v1/clients
- Every client in the workspace, with how many sites each has.
- GET /api/v1/sites
- Sites, newest first.
?clientId=narrows it;?page=and?pageSize=page it, up to 200 a page. Each site carries its current status, check interval, last check, and the certificate and domain expiry dates when they are known. - GET /api/v1/sites/:id
- One site. 404 if it is not yours.
- GET /api/v1/incidents
- Incidents, newest first. Filter with
?siteId=,?status=,?from=and?to=(any date JavaScript can parse; an unparseable one is ignored rather than read as 1970). - GET /api/v1/uptime
- Uptime per site over
?days=(30 by default, 365 at most). The figure is computed exactly as the console and the status page compute it, including leaving out checks taken inside a maintenance window — an API that disagreed with the dashboard about the same month would be worse than none.
Why it only reads#
Version 1 cannot create, change or delete anything, and that is a decision rather than an unfinished edge.
Everything this product changes is attributed to a person. The work history records who renamed a site, the activity log records who paused monitoring, an invoice says which operator raised it. A key is not a person. Making keys write would mean either inventing a user for them — putting something false in the audit trail — or teaching every writing path to record “this key, minted by this person, acting now”. The second is the right answer and it is a real change to how attribution works, so it is not being smuggled in beside a read API.
Until then the console keeps the writes, where every one of them already has a name attached. If writing through the API is what you need, say so — it changes what gets built next.
When it says no#
- 401 — no key, or not a key
- A console session token will not work here, and the message says so. The two credentials are separate on purpose: a session token belongs to a person and expires; a key belongs to an integration and does not.
- 401 — revoked, or expired
- Different messages, because they mean different things: somebody took the key away, or nobody renewed it.
- 404 — not yours
- A site in another workspace is a 404, not a 403. A 403 would confirm that the id exists to anybody guessing them.