API Monitors

Base URL: https://api.okstatus.eu/api/v1/monitors — every request needs an Authorization: Bearer oks_live_... header, see Authentication.

List monitors

GET /api/v1/monitors?page=1&per_page=50

Returns a paginated list scoped to your organization.

Response

{
  "monitors": [
    { "id": "...", "name": "...", "url": "...", "type": "http", "interval": 60, "status": "up" }
  ],
  "total": 12,
  "page": 1,
  "perPage": 50
}

Create a monitor

POST /api/v1/monitors
Content-Type: application/json

Field	Type	Required	Description
name	string	✅	Monitor name (1–255 chars)
url	string	✅	URL to monitor
type	enum		http, tcp, ping, dns, grpc, llm, push, group, postgres, mysql, mongodb, smtp, imap, redis — defaults to http
interval	number		Seconds between checks, min 30 — defaults to 60. Your plan’s floor still applies (300 s on Free, 60 s on Pro)
regions	string[]		Region codes, 1–5 of them — defaults to ["fr-dc3"]. See Regions and intervals
acceptedStatusCodes	string[]		e.g. ["200-299"] — defaults to ["200-299"]
basicAuthUser / basicAuthPass	string		Basic auth, and the credential pair of database, SMTP, IMAP and Redis monitors. Stored encrypted
authConfig	object		Non-Basic authentication — see below

Returns 201 with { "data": Monitor }.

Authentication of the monitored endpoint

authConfig carries one method, discriminated by type (full reference: Authentication):

{ "type": "bearer", "token": "…" }
{ "type": "apikey", "in": "header", "name": "X-API-Key", "value": "…" }
{ "type": "apikey", "in": "query", "name": "api_key", "value": "…" }
{ "type": "cookie", "cookie": "session=…; csrf=…" }
{ "type": "oauth2", "tokenUrl": "https://login.example.com/token", "clientId": "…", "clientSecret": "…", "scope": "…", "audience": "…", "authStyle": "basic" }
{ "type": "mtls", "cert": "-----BEGIN CERTIFICATE-----…", "key": "-----BEGIN PRIVATE KEY-----…", "ca": "…" }

Reading a monitor back returns the method and its non-secret settings, with each secret replaced by "***". Sending that mask back on PATCH keeps the stored value — which is what lets you round-trip a monitor through GET then PATCH without wiping its credentials. "authConfig": null clears the authentication.

Get / update / delete a monitor

GET    /api/v1/monitors/:id
PATCH  /api/v1/monitors/:id
DELETE /api/v1/monitors/:id

PATCH accepts the same fields as create (all optional). DELETE returns { "data": { "deleted": true } }.

Check results and uptime

GET /api/v1/monitors/:id/checks?page=1&per_page=50
GET /api/v1/monitors/:id/uptime?range=24h

Errors

404 NOT_FOUND if the monitor doesn’t exist in your org; 4xx/5xx UPSTREAM_ERROR if the request to OKStatus’s monitoring engine itself fails. See Authentication for the shared error format and rate limits.

Plan limits

Plan	Max monitors	Min interval	Regions per monitor
Free	5	300s	1
Pro	20	60s	3
Max	80	30s	5
Enterprise	Unlimited	30s	5

Limits are enforced on create: an organization already above a lowered limit keeps what it has, it just can’t add more.