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.

MCP access token

Bearer pbm_at_…, issued to an AI agent by the MCP sign-in. Valid only on /api/v1/mcp: every tool call there runs as one of the routes below with the same checks. A direct REST call with it returns 401.

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. The AI label routes persist operator verdicts, so they are writes: viewers and read keys get HTTP 403.

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
}

GET /monitors/results/batch answers {"limit", "results": {monitor_id: [...]}, "members": {group_id: [member_id, ...]}}. Each results list is what GET /monitors/{id}/results?limit=N returns for that monitor: a group's list merges its nested members' newest results under a derived group-status row, and members lists a group's direct members (by name). Ids that are not live monitors of the workspace are left out rather than failing the request; more than 100 ids, a malformed id, or a limit outside 1-100 is a 400. Raw results are kept 30 days, so a monitor that has not run for longer than that comes back with an empty list (here and on the per-monitor endpoint alike). Viewers and read-scope keys may call it.

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>"]
}

SLA endpoints

{
  "name": "Checkout platform",
  "target_pct": 99.9,
  "aggregation": "serial",
  "period": "monthly",
  "timezone": "Europe/Paris",
  "degraded_counts_as_down": false,
  "tags": ["checkout"],
  "monitor_ids": ["<monitor-id>"]
}

Report semantics, composite rules and limits are covered in SLA reporting.

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. Problem monitors are ordered by current state (down, degraded, unknown, up), then failed checks, before the limit applies, so a monitor that is down now is never cut. A group's attention_count counts members down or degraded now; failures earlier in the range show only in its uptime.

Alert and notification endpoints

Alert reads (list, detail, recent alerts, and the acknowledge and resolve responses) and the alerts[] of GET /incidents/{id} include a read-only triage object when the alert has a triage row. The object is omitted when there is no row, and stream events never carry it. Fields that do not apply are null: id, status (pending, ready, failed, skipped), hypothesis (catalogue key) and title, confidence (low, medium, high) and summary when ready, skip_reason (resolved, cooldown, not_modeled, disabled) when skipped, error_message (a fixed string) when failed, created_at (claim time), completed_at, labelled, and labelable (ready and at least one decision was sent to the model). Only GET /alerts/{id} adds label_context, in the same shape as an incident analysis's, when the triage is labelable.

Incident endpoints

A ready analysis that can be labelled also carries label_context on the analysis GET and on GET /incidents/{id}: catalogue_version, the incident-level predicted key, the selectable choices (key, title), one entry per monitor decision (id, monitor_id, monitor_name, which is null once the monitor is purged, and predicted), and the current label or null. It is omitted for pending, failed and legacy analyses, analyses that sent no decisions, and analyses completed before labels existed. The analysis GET and GET /incidents/{id} also add monitor_names, a map from each monitor ID cited in metadata (evidence references and incomplete-evidence notes) to the monitor's current name; purged monitors are absent, and the map is omitted when nothing resolves.

AI label endpoints

Bodies are strict JSON up to 64 KiB, and unknown fields are rejected with validation_error, so evidence can never be supplied: the server copies it from the stored decision snapshot or recomputes it. Labelling never calls the model and works with local AI disabled. A label is one row per analysis, triage or unordered monitor pair; sending again replaces the verdict and answers (latest wins). Every label route returns the label: subject_type, subject_id (analyses and triages only), verdict, incident_label (for a triage, its alert-level cause), answers keyed by opaque decision ID (label, plus source: operator, confirmed or propagated), catalogue_version, model_version, labeled_by (null for API keys) and labeled_at.

{
  "analysis_id": "<optional; defaults to the newest ready analysis>",
  "verdict": "corrected",
  "incident_label": "dns_failure",
  "answers": { "<decision id>": "insufficient_evidence" }
}

verdict is confirmed or corrected. Confirming keeps every decision's shown answer and accepts incident_label only when it equals the prediction; correcting requires an incident_label from the analysis's choices. Optional answers override single decisions. Errors: 400 validation_error (bad verdict, a cause or override that is not a choice of that decision, unknown decision ID), 404 not_found (incident or analysis_id not in this tenant), 409 analysis_not_ready (pending, failed, or no ready analysis), 409 analysis_not_labelable (legacy, no-decision, or pre-label analysis).

{
  "verdict": "corrected",
  "label": "dns_failure",
  "answers": { "<decision id>": "insufficient_evidence" }
}

The triage label works like the incident analysis label, with label in place of incident_label. Confirming accepts label only when it equals the triage's hypothesis, and correcting requires one of its choices. The label is stored with subject type alert_triage, and its evidence comes from the triage's stored decision snapshot. Errors: 400 validation_error (bad verdict, a cause or override that is not a choice, unknown decision ID, unknown fields), 404 not_found (alert not in this tenant), 409 triage_not_ready (no triage, or one that is pending, failed or skipped), 409 triage_not_labelable (the triage sent no decisions).

{
  "monitor_id": "<dependent monitor>",
  "depends_on_id": "<suggested upstream>",
  "verdict": "rejected",
  "corrected": "reversed"
}

verdict is confirmed or rejected; corrected is allowed only with rejected and is reversed, shared_upstream, insufficient_evidence or no_dependency (the default). Either orientation addresses the same pair. Errors: 400 validation_error (identical or malformed IDs, bad verdict), 404 not_found (a monitor is not a live monitor of this tenant), 409 pair_evidence_unavailable (the pair is no longer a candidate: disabled, a group, outside the 250-monitor set, or no shared signal left).

Export takes an optional body with since and until (RFC 3339, a half-open window on the label's last update) and subject_types (incident_analysis, alert_triage, dependency_pair); an empty body exports everything, and an inverted window or unknown type is a validation_error. It returns application/x-ndjson as probara-ai-labels-YYYYMMDD.jsonl with X-Probara-Export-Rows and X-Probara-Export-Skipped headers: one training row per decision, and rows whose stored evidence fails validation are skipped and counted. Triage rows share a split group with the earliest incident that links the alert, or form their own group when none does. More than 5,000 labels or 20,000 rows returns 400 export_too_large; narrow the window. Rows contain no identifiers (see security).

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

Discovery endpoints

POST /api/v1/discovery-collectors/{id}/snapshot returns 204 when the snapshot is applied, 401 for a missing or malformed bearer, 404 for an unknown integration or wrong token, 400 for an invalid body (unknown JSON fields are ignored, so a newer collector still syncs; known fields are fully validated), 409 for a stale or replayed revision (no Retry-After), 409 with Retry-After: 10 when it scanned a namespace that was removed meanwhile (not counted against the rate limit), 429 rate_limited with Retry-After (whole seconds) when a snapshot was applied, or refused with 422, less than 60 seconds earlier, and 422 inventory_limit when the integration would store more than 10,000 resources after reconciling its active namespaces (pending namespaces that would exceed it are left pending as inventory_limit and the snapshot is applied without them). A refused snapshot leaves the inventory, revision and last-seen time unchanged; a 422 still counts against the rate limit, since it did the reconciliation work. The token and the rate limit are checked before the body of up to 4 MiB is read.

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 on a monitor; send an empty string when you deliberately want to clear it. Notification channel configs differ: an empty string also keeps the stored secret, and null clears an optional one (a required one is then rejected by validation).
• 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.