API reference

Base URL and conventions

The control-plane API is rooted at {API_ORIGIN}/api/v1. The API serves /healthz, /readyz, and /metrics on HTTP_PORT (8080 in the bundled deployments); its declared METRICS_PORT does not have a separate listener. Public rendered status pages are served by the separate status-page service.

export PROBARA_API_ORIGIN='https://monitoring.example.com'

curl "$PROBARA_API_ORIGIN/healthz"
curl "$PROBARA_API_ORIGIN/readyz"

Authentication

Administrator session

Login establishes an HTTP-only access cookie and a rotating refresh session. It is the credential used by the web application and can switch among allowed tenants.

API key

Send Authorization: Bearer pk_<secret>. The key has read or write scope and is bound to its creation tenant.

Push token

Used only in /api/v1/push/{token}. No cookie or bearer key is required because possession of the URL token authorizes a heartbeat.

curl \
  -H 'Authorization: Bearer pk_<secret>' \
  -H 'Accept: application/json' \
  "$PROBARA_API_ORIGIN/api/v1/monitors?page=1&page_size=20"

Tenant selection and permissions

For an administrator cookie, send X-Tenant-ID: <tenant-id> to select an allowed membership. A supported tenant_id query fallback can select context where middleware permits it. API keys ignore caller-selected tenant values and remain pinned to one tenant.

curl \
  --cookie cookie-jar.txt \
  -H 'X-Tenant-ID: <tenant-id>' \
  "$PROBARA_API_ORIGIN/api/v1/auth-context"

Compute-only POST exceptions include /monitors/test, /monitors/import/preview, /monitors/dependency-suggestions, /mesh/probe, and /ai-settings/test. They do not persist monitor/result/graph state. Channel test sends a real outbound notification and therefore is not read-only.

Pagination and common filters

Collection APIs generally accept 1-based page and page_size. The common maximum is 100; locations allow up to 200, and dashboard recent-item limits are capped at 50. Use returned total/page metadata where provided rather than inferring completion from a short page.

Monitor endpoints

{
  "name": "Public API",
  "type": "http",
  "config": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "expected_status_classes": ["2xx"],
    "json_assertions": [
      {"path": "status", "op": "equals", "value": "ok"}
    ],
    "max_latency_ms": 1500
  },
  "interval_seconds": 60,
  "timeout_seconds": 15,
  "enabled": true,
  "tags": ["api", "production"],
  "consecutive_failures_threshold": 2,
  "notification_mode": "default",
  "location_ids": [],
  "location_quorum": 1
}

Monitor relationships, bulk, and portability

Dependency creation rejects self-reference and transitive cycles with HTTP 409. Export/import is not a universal secret-preserving round trip: masked fields and newer monitor types require explicit preview and remediation. Import preview reports a schema for recognized sources (portable_monitor_export, uptime_kuma_export), per-row warnings, and skipped_rows naming source records it declined to translate.

Locations, mesh, and maintenance

{
  "title": "Database upgrade",
  "description": "Planned primary database maintenance",
  "starts_at": "2026-08-01T22:00:00Z",
  "ends_at": "2026-08-01T23:30:00Z",
  "monitor_ids": ["<monitor-id>"]
}

Dashboard endpoints

Overview ranges are 1h, 24h, 7d, 30d, 90d, and 365d, defaulting to 24h. Dashboard group rows are tag-derived presentation, not group-monitor resources.

Alert and notification endpoints

Incident endpoints

Status page endpoints

The separate status-page service exposes unauthenticated GET /public/status/{slug}, /data, and /stream, plus draft preview. Do not use those public routes to mutate configuration.

Agent and push endpoints

Administration endpoints

Server-sent events

GET /api/v1/alerts/stream is an authenticated tenant alert stream. The public status-page service exposes a different slug-scoped stream at /public/status/{slug}/stream. Use a native EventSource-compatible client where cookie authentication is required, or a streaming HTTP client that can attach the bearer key.

curl -N \
  -H 'Authorization: Bearer pk_<secret>' \
  "$PROBARA_API_ORIGIN/api/v1/alerts/stream"

• Reconnect with backoff after network or proxy interruption.
• Treat events as refresh/invalidation signals and refetch durable resource state.
• Keep proxy buffering disabled for the streaming route.
• Do not assume the stream is a replayable audit log.

Build a safe client

• Set explicit HTTP timeouts and retry only operations whose idempotency you understand.
• Retry GET requests with bounded exponential backoff; do not blindly retry create, run-now, import execution, notification tests, or incident timeline writes.
• Use import preview before import execution and monitor test before saving complex check configuration.
• Respect 401, 403, 404, 409, 410, 422, and rate/transport failures as distinct conditions.
• Send ***, or leave the field out, to keep a masked designated secret field; send an empty string when you deliberately want to clear it.
• Page collections and retain returned coverage metadata for analytics.
• Store full API keys only in a secret manager; the API returns them once.
• Log resource IDs and status codes without logging bearer keys, push tokens, installer output, WebSocket headers, connection strings, or webhook secrets.