stativa

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
![status](https://api.stativa.io/api/public/t/acme/p/status/badge.svg)

// 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.