API reference

Base URL https://sysops247.io. Everything is under /api/v1, takes and returns JSON, and needs an API key.

Prefer to try before you read? The API console lets you paste a key and send any of these requests from your browser.

This is the same API the dashboard uses. There is no reduced “public API” — if you can do it in the UI, you can do it here, under the same permissions and the same plan limits.

Conventions

Collections

json

{
  "data": [ ... ],
  "pagination": { "total": 132, "limit": 50, "offset": 0 }
}

?limit= (default 50, max 200) and ?offset=. Most list endpoints also take ?search=.

Errors

json

{
  "error": {
    "code": "validation",
    "message": "monitor limit reached for the free plan",
    "fields": { "target": "must be a valid URL" },
    "request_id": "01HQ..."
  }
}

Quote the request_id if you ever need to ask us what happened — it is how we find your request in the logs.

Field	Type	Notes
400 / 422	validation	The request was malformed, or it hit a plan limit.
401	unauthorized	Missing, invalid, revoked or expired credential.
403	forbidden	Authenticated, but your role does not allow it.
404	not_found	No such resource — or it belongs to another organization. The two are indistinguishable by design.
429	rate_limited	Slow down; honour `Retry-After`.

Tenancy

Every resource is scoped to the organization the credential belongs to. Another tenant's monitor is not found, never “forbidden” — telling you it exists would be the leak.

Monitors

GET/api/v1/monitors

List. Filters: search, status, type, project_id.

POST/api/v1/monitors

Create one.

GET/api/v1/monitors/{id}

Fetch one.

PATCH/api/v1/monitors/{id}

Update. Send only what changes.

DELETE/api/v1/monitors/{id}

Delete, with its history.

POST/api/v1/monitors/{id}/pause

Stop probing without deleting.

POST/api/v1/monitors/{id}/resume

Start again.

GET/api/v1/monitors/{id}/metrics

Recent uptime and response times.

GET/api/v1/monitors/usage

How many monitors you have, against your plan.

Create a monitor

bash

curl -X POST https://sysops247.io/api/v1/monitors \
  -H "Authorization: Bearer $BEACON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "b1f2...",
    "name": "api",
    "type": "https",
    "target": "https://api.example.com",
    "interval_seconds": 60,
    "settings": { "valid_status_codes": [200], "body_keyword": "ok" }
  }'

Field	Type	Notes
project_idrequired	uuid	Which project it belongs to.
namerequired	string	How you will recognise it.
typerequired	string	See monitor types.
target	string	Required for everything except `heartbeat`.
interval_seconds	number	How often to check. Floor depends on your plan.
timeout_seconds	number	How long to wait before calling it a failure.
grace_seconds	number	Heartbeat only: slack before a missed ping alerts.
enabled	boolean	Defaults to true.
public	boolean	Publish on your status page. Defaults to false — nothing is exposed by accident.
settings	object	Per-type options; see monitor types.

Sync (declarative)

POST/api/v1/sync

Apply a whole set of monitors at once. Idempotent.

The endpoint to use from CI. It takes the monitors you want and works out the difference, so running it on every push is safe. Full guide →

Projects

GET/api/v1/projects

List.

POST/api/v1/projects

Create. { "name", "description?", "environment?" }

PATCH/api/v1/projects/{id}

Update.

DELETE/api/v1/projects/{id}

Delete.

Alerts

GET/api/v1/alerts

Everything firing right now. Filter with ?severity=critical.

What is broken right now?

curl -s "https://sysops247.io/api/v1/alerts" \
  -H "Authorization: Bearer $BEACON_API_KEY" \
  | jq -r '.data[] | "\(.severity)\t\(.monitor_name)\t\(.target)"'

Notification channels

GET/api/v1/notification-channels

List.

POST/api/v1/notification-channels

Create. Types: telegram, slack, email, webhook.

PATCH/api/v1/notification-channels/{id}

Update or enable/disable.

DELETE/api/v1/notification-channels/{id}

Delete.

POST/api/v1/notification-channels/{id}/test

Send a test message. Do this when you create one.

Maintenance windows

GET/api/v1/maintenance-windows

List.

POST/api/v1/maintenance-windows

Schedule one. Alerts are suppressed; probing continues.

PATCH/api/v1/maintenance-windows/{id}

Update.

DELETE/api/v1/maintenance-windows/{id}

Cancel.

Prefer a maintenance window to pausing a monitor during a deploy. Alerts stay quiet, but the probes keep running — so you still have the history of what happened while you were working.

Status page

GET/api/v1/status-page

Your settings.

PATCH/api/v1/status-page

Update title, custom slug, or publish/unpublish.

GET/api/v1/public/status/{slug}no auth

The public read model. No credential — this is what your customers see.

Billing & diagnosis

GET/api/v1/billing

Plan, credit, and what remains.

POST/api/v1/monitors/{id}/diagnose

AI root-cause analysis for a failing monitor. Paid plans.

Operational

GET/api/v1/system/infono auth

Version, environment and uptime of the API you are talking to.

GET/api/v1/ping/{token}no auth

Heartbeat check-in. The URL a cron job calls on success.

Limits are per organization for authenticated calls and per address for anything anonymous. A refusal is a 429 with a Retry-After header saying how long to wait — respect it and you will not be refused twice.

Normal use does not come close. If you are hitting them, you are probably polling where you could be reacting: a webhook channel tells you the moment something breaks, without asking every few seconds.