API Reference

Complete REST API documentation for integrating with SysTeam HealthChecks.

Authentication

All API requests (except public endpoints) require authentication. Two methods are supported:

Method 1: JWT Cookie (Web Sessions)

The web interface uses JWT tokens stored in cookies. This is handled automatically when you log in.

Method 2: Personal Access Token (Scripts/API)

For scripts, CI/CD, and API integrations, use a Personal Access Token:

Authorization: Bearer pat_your_token_here

Getting a JWT Token

POST/api/auth/tokenLogin and get JWT token

Request (form-urlencoded)

username=user@example.com
password=your-password

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Checks API

GET/api/checks/List all checks

POST/api/checks/Create a new check

GET/api/checks/{id}Get check details

PUT/api/checks/{id}Update a check

DELETE/api/checks/{id}Delete a check

GET/api/checks/{id}/logsGet check logs

GET/api/checks/{id}/statsGet check statistics

GET/api/checks/{id}/incidentsGet incidents

GET/api/checks/{id}/slaGet SLA metrics

GET/api/checks/{id}/sloGet SLO config/status

POST/api/checks/{id}/sloCreate/update SLO

DELETE/api/checks/{id}/sloDelete SLO

Create Check Example

POST /api/checks/

{
  "name": "My Website",
  "type": "uptime",
  "url": "https://example.com",
  "interval": 60,
  "grace_period": 60,
  "expected_status_codes": [200],
  "content_match_enabled": true,
  "content_match_text": "Welcome",
  "content_match_type": "contains",
  "geo_monitoring_enabled": false,
  "assigned_agent_ids": [1, 2],
  "check_source_critical": {"agent:1": true, "geo:EU-PL": false}
}

Execution Source Fields

Checks support a flexible execution model. Private agents and geo monitoring can be used simultaneously on the same check.

Field	Type	Description
`assigned_agent_ids`	array of int	IDs of private agents assigned to execute this check. Multiple agents can be assigned — the check runs on all of them simultaneously. If empty and geo monitoring is disabled, the check runs from the central server.
`geo_monitoring_enabled`	bool	When `true`, the check is distributed across all active geo agents. Can be combined with `assigned_agent_ids` to run from both private agents and geo locations at the same time.
`check_source_critical`	dict	Maps source keys to their critical flag. A critical source failing immediately sets the check to DOWN, regardless of other sources. Keys use the format `agent:<id>` for private agents and `geo:<location_id>` for geo locations. Example: `{"agent:5": true, "geo:EU-PL": true}`
`agent_location_statuses`	dict (read-only)	Per-source status breakdown returned in GET responses. Keys are the same `agent:<id>` / `geo:<location_id>` format. Values are `UP`, `DOWN`, `DEGRADED`, or `UNKNOWN`. This field is populated by the server and ignored on create/update.

Tip

The old single-value field assigned_agent_id is deprecated. Use assigned_agent_ids (array) instead. The API still accepts the singular form for backward compatibility and converts it automatically.

Notification Channels API

GET/api/notification-channels/List channels

POST/api/notification-channels/Create channel

PUT/api/notification-channels/{id}Update channel

DELETE/api/notification-channels/{id}Delete channel

POST/api/notification-channels/{id}/testTest channel

Create Slack Channel Example

{
  "name": "Ops Alerts",
  "channel_type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/..."
  }
}

Maintenance Windows API

GET/api/maintenance/List maintenance windows

POST/api/maintenance/Create window

GET/api/maintenance/{id}Get window

PUT/api/maintenance/{id}Update window

DELETE/api/maintenance/{id}Delete window

GET/api/maintenance/check/{id}/statusCheck maintenance status

Status Pages API

GET/api/status-pages/List status pages

POST/api/status-pages/Create status page

GET/api/status-pages/{id}Get status page

PUT/api/status-pages/{id}Update status page

DELETE/api/status-pages/{id}Delete status page

GET/api/status-pages/public/{slug}Public status (no auth)

GET/api/status-pages/public/{slug}/uptimePublic uptime data

GET/api/status-pages/public/{slug}/feed.atomAtom feed

POST/api/status-pages/public/{slug}/subscribeEmail subscribe

Agents API

GET/api/agents/List agents

POST/api/agents/registerRegister new agent

POST/api/agents/heartbeatAgent heartbeat

GET/api/agents/checksGet assigned checks (agent)

POST/api/agents/resultsSubmit check results (agent)

GET/api/agents/checks/{id}/geo-summaryGeo status summary

GET/api/agents/checks/{id}/geo-timeseriesGeo timeseries data

GET/api/agents/geo-locationsList geo locations

Reports API

POST/api/reports/generateGenerate a report

GET/api/reports/{id}Get report status/download

GET/api/reports/List generated reports

GET/api/checks/{id}/export/incidents.csvQuick export: incidents

GET/api/checks/{id}/export/logs.csvQuick export: logs

Badges API (Public)

GET/api/badges/{uuid}Status badge SVG

GET/api/badges/{uuid}/uptimeUptime badge SVG

Metrics API

GET/api/metrics/{key}Prometheus metrics

GET/api/metrics/{key}?format=otlpOTLP format metrics

Metrics keys are managed in the Integrations page. See the integrations documentation for Grafana and OTel Collector setup.

Inbound Events API

Receive alerts from external monitoring systems (Prometheus, Grafana, Zabbix, CloudWatch, custom scripts). See the Inbound Events documentation for full setup instructions.

Public Ingest Endpoint (No Auth)

POST/api/events/ingestTrigger/acknowledge/resolve inbound incident

Trigger Event

{
  "routing_key": "ik_abc123...",
  "event_action": "trigger",
  "dedup_key": "disk-full-srv01",
  "payload": {
    "summary": "Disk full on srv01",
    "severity": "critical",
    "source": "prometheus",
    "component": "disk",
    "group": "infrastructure",
    "custom_details": { "usage_pct": 95 }
  }
}

Response (202 Accepted)

{
  "status": "success",
  "dedup_key": "disk-full-srv01",
  "incident_id": 42
}

Deduplication

Sending another trigger with the same dedup_key updates the existing incident instead of creating a new one. Use event_action: "acknowledge" to stop escalation, and "resolve" to close the incident.

Integration Keys (Org-Scoped, ADMIN+)

GET/api/organizations/{id}/integration-keysList integration keys

POST/api/organizations/{id}/integration-keysCreate key (raw key shown once)

DELETE/api/organizations/{id}/integration-keys/{kid}Revoke key

Inbound Incidents (Org-Scoped, MEMBER+)

GET/api/organizations/{id}/inbound-incidentsList incidents (filterable)

GET/api/organizations/{id}/inbound-incidents/{iid}Incident detail + events

POST/api/organizations/{id}/inbound-incidents/{iid}/ackAcknowledge from UI

Heartbeat (Ping) API

No authentication required. Use your check's UUID to send pings.

Endpoints

GET/api/ping/{uuid}Success ping

POST/api/ping/{uuid}Success ping with body

GET/api/ping/{uuid}/startJob started

GET/api/ping/{uuid}/failExplicit failure

GET/api/ping/{uuid}/logLog only

GET/api/ping/{uuid}/{exit_code}With exit code

Query Parameters

Parameter	Description
`rid`	Run ID to correlate /start with success/fail ping

POST endpoints accept up to 100KB of text in the request body (stdout/stderr from jobs). See Heartbeat Check for full usage examples.

Organizations API

GET/api/organizations/List organizations

POST/api/organizations/Create organization

GET/api/organizations/{id}Get organization

PUT/api/organizations/{id}Update organization

GET/api/organizations/{id}/membersList members

GET/api/organizations/{id}/usageUsage & limits

GET/api/organizations/{id}/settingsGet settings

PUT/api/organizations/{id}/settingsUpdate settings

On-Call & Escalation API

On-Call Schedules

GET/api/organizations/{id}/oncall-schedulesList schedules

POST/api/organizations/{id}/oncall-schedulesCreate schedule

GET/api/organizations/{id}/oncall-schedules/{sid}Get schedule

PUT/api/organizations/{id}/oncall-schedules/{sid}Update schedule

DELETE/api/organizations/{id}/oncall-schedules/{sid}Delete schedule

GET/api/organizations/{id}/oncall-schedules/{sid}/currentWho's on-call now

GET/api/organizations/{id}/oncall-schedules/{sid}/timelineSchedule timeline

POST/api/organizations/{id}/oncall-schedules/{sid}/overridesCreate override

Escalation Policies

GET/api/organizations/{id}/escalation-policiesList policies

POST/api/organizations/{id}/escalation-policiesCreate policy

GET/api/organizations/{id}/escalation-policies/{pid}Get policy

PUT/api/organizations/{id}/escalation-policies/{pid}Update policy

DELETE/api/organizations/{id}/escalation-policies/{pid}Delete policy

Teams API

GET/api/organizations/{id}/teamsList teams

POST/api/organizations/{id}/teamsCreate team

GET/api/organizations/{id}/teams/{tid}Get team details

PUT/api/organizations/{id}/teams/{tid}Update team

DELETE/api/organizations/{id}/teams/{tid}Delete team

POST/api/organizations/{id}/teams/{tid}/membersAdd member

PUT/api/organizations/{id}/teams/{tid}/members/{uid}Change member role

DELETE/api/organizations/{id}/teams/{tid}/members/{uid}Remove member

PUT/api/organizations/{id}/teams/{tid}/resourcesAssign resources

War Rooms API

GET/api/organizations/{id}/war-roomsList war rooms

POST/api/organizations/{id}/war-roomsCreate war room

GET/api/organizations/{id}/war-rooms/{rid}Get war room

POST/api/organizations/{id}/war-rooms/{rid}/closeClose war room

POST/api/organizations/{id}/war-rooms/{rid}/membersAdd member

DELETE/api/organizations/{id}/war-rooms/{rid}/members/{mid}Remove member

Postmortems API

GET/api/organizations/{id}/postmortemsList postmortems

POST/api/organizations/{id}/postmortemsCreate postmortem

GET/api/organizations/{id}/postmortems/{pid}Get postmortem

PUT/api/organizations/{id}/postmortems/{pid}Update postmortem

DELETE/api/organizations/{id}/postmortems/{pid}Delete postmortem

Incidents API

GET/api/incidentsList all incidents

POST/api/checks/{cid}/incidents/{lid}/ackAcknowledge check incident

POST/api/checks/{cid}/incidents/{lid}/resolveForce resolve incident

POST/api/organizations/{id}/incidents/{type}/{ref}/notesAdd note

GET/api/organizations/{id}/incidents/{type}/{ref}/timelineGet timeline

SSO API

GET/api/auth/sso/providersList SSO providers

GET/api/auth/sso/init/{slug}Start SSO login

POST/api/auth/sso/link/{slug}Link SSO identity

DELETE/api/auth/sso/unlink/{slug}Unlink SSO identity

GET/api/auth/sso/me/identitiesList linked identities

Feedback API

POST/api/feedbackSubmit feedback

GET/api/feedbackList your feedback

GET/api/feedback/{id}Get feedback details

Real-Time Events (SSE)

GET/api/eventsSSE event stream

Connect to this endpoint to receive real-time updates. Events include: status.change, log.append, incident.new, incident.resolve, incident.ack, check.update, agent.status. See Incidents → Real-Time Updates for details.

Users API

GET/api/users/meGet current user

PUT/api/users/me/notification-preferencesUpdate notification prefs

GET/api/users/List users (admin)

PUT/api/users/{id}Update user

DELETE/api/users/{id}Delete user

Error Responses

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Missing or invalid token
`403`	Forbidden — Insufficient permissions
`404`	Not Found — Resource doesn't exist
`422`	Validation Error — Invalid data format
`429`	Too Many Requests — Rate limit exceeded
`500`	Server Error

Rate Limiting

API endpoints are rate-limited to prevent abuse. See Security → Rate Limiting for details. When rate limited, you'll receive a 429 response with a Retry-After header.