From developers, to developers
Everything you click, you can script.
Plain HTTP, small JSON bodies and curl-friendly tokens. Wire stativa into cron jobs, CI pipelines and your alerting without an SDK.
Authentication
API keys with scopes
Create keys under Settings → API keys and send them as Authorization: Bearer stv_…. Give each job the scope it needs, and bind a key to one status page when it only ever touches that page.
- read
- Page status and uptime: GET /pages, /pages/:page/status
- maintenance
- Open, read and end maintenance windows; record deploys
- incidents
- Alertmanager and Grafana webhooks open and resolve incidents
- services
- Groups and services as code: create, update, reorder, delete, rotate tokens
- admin
- Everything above plus pages, branding and custom domains
Heartbeats
Know when a cron job didn't run
Each heartbeat service has its own token in the URL — no API key. Ping when the job finishes; stativa marks the service down when a ping is late past its grace window. Expect pings on a fixed period or on a cron expression in your timezone, and set a maximum run time to catch jobs that hang.
# at the end of the job (GET or POST)
curl -fsS https://app.stativa.io/api/v1/heartbeat/$TOKEN
# report the start; on failure send the reason (first 1000 bytes kept)
curl -fsS https://app.stativa.io/api/v1/heartbeat/$TOKEN/start
tail -c 1000 job.log | curl -fsS --data-binary @- https://app.stativa.io/api/v1/heartbeat/$TOKEN/fail
Metrics
Push a number, set the thresholds
Queue depth, error rate, free disk — anything you can count. Set a degraded and an outage threshold (above or below), and how long silence may last before the service counts as down.
curl -fsS -X POST "https://app.stativa.io/api/v1/metric/$TOKEN?value=42"
# or as JSON
curl -fsS -X POST https://app.stativa.io/api/v1/metric/$TOKEN \
-H "Content-Type: application/json" -d '{"value": 0.7}'
CI/CD
Maintenance and deploys from your pipeline
Open a window before a migration, end it when the deploy is done — checks that fail inside it are planned work, not outages. With announceit shows on the page and subscribers hear about it. Ending a window twice is not an error, so a retried CI step stays green. Deploy markers show up on the Deploys screen and on the service’s response-time chart.
# maintenance key; services by slug, empty = whole page
ID=$(curl -fsS -X POST https://app.stativa.io/api/v1/maintenance \
-H "Authorization: Bearer $STATIVA_KEY" \
-d '{"services":["api"],"minutes":20,"title":"Database upgrade","announce":true}' \
| jq -r .id)
./deploy.sh
curl -fsS -X POST https://app.stativa.io/api/v1/maintenance/$ID/end -H "Authorization: Bearer $STATIVA_KEY"
curl -fsS -X POST https://app.stativa.io/api/v1/deploys -H "Authorization: Bearer $STATIVA_KEY" \
-d '{"services":["api"],"version":"'$GIT_SHA'","environment":"production"}'
Alerts
Your alerts open the incidents
Point Prometheus Alertmanager or Grafana Alerting at stativa with an incidents key. A firing alert opens an incident on the services you list; when it resolves, the incident closes. Settings → API keys has copy-paste configs for both.
# alertmanager.yml
receivers:
- name: stativa
webhook_configs:
- url: "https://app.stativa.io/api/v1/alerts/alertmanager?services=api"
http_config:
authorization:
credentials: stv_…
# Grafana → Alerting → Contact points → Webhook
# URL: https://app.stativa.io/api/v1/alerts/grafana?services=api
Infrastructure as code
Services and pages from a script
Keep the page in sync with what you run: create groups and services, change their checks, reorder or remove them, and rotate heartbeat and metric tokens. Admin keys also manage pages, branding and custom domains.
- ✓GET /pages · GET /pages/:page · GET /pages/:page/status
- ✓GET|POST /pages/:page/groups · PUT|DELETE /groups/:id
- ✓POST /groups/:id/services · GET /services
- ✓GET|PUT|DELETE /services/:id
- ✓POST /services/:id/heartbeat/token · /metric/token
- ✓POST /pages · PUT /pages/:page · /branding · /domain
Public data
Read any page without a key, and verify it
Every public page has a JSON status, uptime history, incident permalinks, an RSS feed and an SVG badge. Responses carry a Stativa-Signature header — an Ed25519 signature over <t>.<body>— and the workspace publishes its public key, so you can check a status really came from stativa and wasn’t changed on the way.
curl https://api.stativa.io/api/public/t/acme/p/status/status
curl https://api.stativa.io/api/public/t/acme/p/status/feed.xml

// Node: verify a response
import { createPublicKey, verify } from "node:crypto";
const key = await (await fetch("https://api.stativa.io/api/public/t/acme/signing-key")).json();
const res = await fetch("https://api.stativa.io/api/public/t/acme/p/status/status");
const body = await res.text();
const sig = Object.fromEntries(res.headers.get("stativa-signature")
.split(",").map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]));
const ok = verify(null, Buffer.from(`${sig.t}.${body}`),
createPublicKey(key.public_key_pem), Buffer.from(sig.ed25519, "base64"));
Get a key and try it.
Create a workspace, add a service and copy its heartbeat URL. It takes a couple of minutes.