Health checks API: create and query checks via API v2

With the health checks API (part of the IPv64.net API v2) you create, change, pause and delete checks from scripts, query measurements, events and incidents, and manage notification channels, maintenance windows and nodes. The field names are the same as in the Node64 API, so scripts look alike against both.

Overview: base URL, format and errors

All paths on this page start with /hc2 and are appended to the API v2 base URL:

https://ipv64.net/api/v2

• Methods: GET, POST, PATCH and DELETE. If you can only send GET and POST, send POST with the header X-HTTP-Method-Override: PATCH (or DELETE).
• Requests as JSON (Content-Type: application/json), at most 1 MB. PATCH only changes the fields you send.
• Responses as JSON in the envelope {"data": …, "meta": {…}}; meta only appears for lists with paging details. DELETE answers 204 without content.
• Times in ISO 8601 with time zone, in responses always UTC (e.g. 2026-10-26T08:15:00.000Z).
• The complete description as OpenAPI 3.1 (section “Healthchecks 2.0”) is available at ipv64.net/api_v2_docs.

Errors

Errors follow RFC 9457 as application/problem+json with a fixed error code in code:

{
  "type": "https://ipv64.net/api/v2/errors#limit_reached",
  "title": "Forbidden",
  "status": 403,
  "detail": "Online-Limit erreicht: 10 von 10 Messstellen belegt, benötigt werden 2 weitere. …",
  "code": "limit_reached",
  "errors": ["Online-Limit erreicht: …"]
}

Validation messages of checks and channels (detail, errors) are in German.

Authentication and limits

The API uses your API keys from Account > API (see Account: API keys). Send the key only in a header – never in the URL:

curl "https://ipv64.net/api/v2/hc2/account" -H "Authorization: Bearer YOUR_API_KEY"
curl "https://ipv64.net/api/v2/hc2/account" -H "X-API-Key: YOUR_API_KEY"

Limits

• General: per account up to 300 requests at once, then 10 per second; per IP address 600 at once, then 20 per second. Failed logins: 20, then 12 per minute per IP. The headers RateLimit-Limit and RateLimit-Remaining show the current state; on 429, Retry-After gives the waiting time in seconds.
• Test messages: one per 30 seconds per channel.
• Confirmation codes: 5 codes per hour, 10 attempts per hour – shared with the portal.
• Sending through an IPv64 channel (/send): 30 at once, then 30 per hour, at most 200 per day; SMS additionally according to the daily limit of your account class.
• The health check limits of your account class (online measuring points, online measurements per day, locations per check) also apply via API, see Limits.

Account and settings

GET /hc2/account

Account class, limits and usage:

{"data": {
  "plan": "Supporter",
  "online_measuring_points": {"used": 6, "limit": 10},
  "locations_per_check": 2,
  "checks_per_day": {"used": 2817, "limit": 8192},
  "sms_per_day": 50,
  "locations": [{"code": "fsn", "name": "Falkenstein"}, {"code": "nbg", "name": "Nürnberg"}],
  "nodes": {"total": 1, "online": 1},
  "checks": 12
}}

limit: null means unlimited; for sms_per_day that is 0.

GET and PATCH /hc2/settings

Quiet hours and grouped alerts of the account (see Notifications). Allowed keys:

curl -X PATCH "https://ipv64.net/api/v2/hc2/settings" -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notify.quiet_enabled": true, "notify.quiet_from": "23:00", "notify.quiet_to": "06:30"}'

Manage checks

Fields of a check

The response additionally contains token, node_id, node_name, nodes (with names), revision, created_at, updated_at and state with state, since, last_check_at, last_status, last_latency_ms, last_reason, last_message, down_since and last_push_at. Push checks also have a push object (see Push URL). The state is one of up, down, degraded, flapping, stabilizing, dependent, pending and paused; “not monitored” and “quota used up” show as pending with last_reason unchecked or quota_exhausted.

Parameters per type (params)

json_rules is a list of objects {"path": "status", "op": "eq", "value": "ok"} with the operators eq, ne, lt, le, gt, ge, contains, not_contains, regex, exists, not_exists – or the text form as in the form. Limits and meaning of all values are listed under Check types.

Examples

Create an HTTPS check from both locations:

curl -X POST "https://ipv64.net/api/v2/hc2/checks" -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "http", "name": "Website", "target": "https://example.com/",
       "interval_seconds": 60, "locations": ["nbg", "fsn"],
       "params": {"accept_status": "200-299", "cert_min_days": 14}}'

Push check for a nightly backup:

curl -X POST "https://ipv64.net/api/v2/hc2/checks" -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "push", "name": "Backup NAS", "params": {"period_seconds": 86400, "grace_seconds": 3600}}'

List checks that are down, pause a check:

curl "https://ipv64.net/api/v2/hc2/checks?state=down" -H "Authorization: Bearer YOUR_API_KEY"
curl -X POST "https://ipv64.net/api/v2/hc2/checks/YOUR_CHECK_TOKEN/pause" -H "Authorization: Bearer YOUR_API_KEY"

Errors on create: 422 invalid_healthcheck (invalid input), 422 private_target (private target online), 403 limit_reached (measuring point limit).

Change the execution (moving)

If a PATCH changes execution, the nodes or the locations, the API saves all other fields but leaves the execution unchanged and answers 409 move_requires_test. You switch with a test run – or you send "force_move": true, then the switch happens without a test.

curl -X POST "https://ipv64.net/api/v2/hc2/checks/YOUR_CHECK_TOKEN/move" -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"execution": "both", "nodes": ["YOUR_NODE_ID"], "locations": ["nbg", "fsn"]}'

{"data": {"id": 4711, "status": "ok", "target": "both", "applied": true,
  "results": [{"source": "ipv64 Nürnberg", "ok": true, "message": "ipv4 up 23.4 ms"}, …]}}

Poll the test run every 2 seconds for at most 60 seconds. status is pending, ok (switch applied, applied: true), failed (stays as before) or expired (no answer within 60 seconds, then with error). Errors on start: 409 unchanged (already runs this way), 422 move_rejected (e.g. node offline, remote management off, private target, limit, Docker check).

Measurements, events, incidents and statistics

• Measuring points (source): loc:nbg or loc:fsn for the IPv64 locations, node:NODE_ID for a node, push for pushes.
• Single measurements are only kept for a short time; for longer periods use /stats.
• Paging of events: meta contains limit, has_more and next_before (or next_after when you page forward with after). Pass the value as before or after in the next request.
• silent: true means no message was sent for this event.

curl "https://ipv64.net/api/v2/hc2/checks/YOUR_CHECK_TOKEN/stats?range=30d" -H "Authorization: Bearer YOUR_API_KEY"
curl "https://ipv64.net/api/v2/hc2/incidents?open=true" -H "Authorization: Bearer YOUR_API_KEY"

Push URL for cron jobs

Pushes do not go through API v2 and need no API key. Every push check has a push object in the response:

# Report OK
curl -fsS -m 10 "https://ipv64.net/health.php?token=YOUR_PUSH_TOKEN"
# Report an outage
curl -fsS -m 10 "https://ipv64.net/health.php?token=YOUR_PUSH_TOKEN&status=down&msg=backup+failed"

Parameters: status=down or fail for an outage, msg or message for a message (up to 500 characters). The response is OK. At most 60 pushes per minute per token; pushes count against the daily quota. More under Push checks.

Notification channels

Channel types and their config keys: ipv64_mail (email), ipv64_sms (number), app (device_key, critical), telegram (bot_token, chat_id, silent), discord (webhook_url, username), slack and teams (webhook_url), matrix (server, token, room), ntfy (server, topic, token, user, password, priority_down, priority_up), gotify (server, app_token, priority), pushover (user_key, app_token, device, priority_down, priority_up), webhook (url, method, headers, body, insecure_tls), smtp (host, port, security, user, password, from, to). Meaning and defaults: Channel types. URLs and the SMTP host must be public, SMTP only on port 25, 465, 587 or 2525; otherwise 422 invalid_channel with the messages in errors. Internal targets only work through a channel on the node.

curl -X POST "https://ipv64.net/api/v2/hc2/channels" -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "ntfy", "name": "ntfy phone", "default": true, "config": {"server": "https://ntfy.sh", "topic": "my-secret-topic"}}'

With /send, an event_id that was already sent successfully in the last 24 hours is not sent again (response duplicate: true). For SMS, sms_left in the response tells how many SMS are left today (null = unlimited).

Maintenance windows

Fields: name, start_at and end_at (ISO 8601, required, end after start), repeat (none, daily, weekly, monthly), repeat_until, tokens (list of check tokens, empty = all checks) and active (default true).

curl -X POST "https://ipv64.net/api/v2/hc2/maintenance" -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Proxmox updates", "start_at": "2026-11-01T03:00:00+01:00", "end_at": "2026-11-01T04:00:00+01:00", "repeat": "weekly"}'

Nodes

The node only accepts commands if its remote management allows it (see Remote management). Nodes register themselves with POST /node64/hello; you do not need that in your own scripts.

Found a mistake or missing something? Tell us in the v64.tech forum. · Updated: 2026-11-04