Status pages via the API

What the API can do

Everything you do with your status page in the dashboard also works through the CitexNode API under https://api.citexnode.com/api/v1/me/status-pages/…. Every endpoint with all its fields is in the API documentation under statuspages; general notes on the API are in API and embedding the status page.

For scripts, use a personal API token instead of your login.

Creating a token

Dashboard → Account → API tokens, New token, enter a name and choose under Permissions:

A token may never order, renew, change the plan, delete the page, or change settings, domains or webhooks. That only works logged in to the dashboard; a token gets 403 token_not_allowed there.

Your page's ID

The endpoints need the page's ID, not its address. To list your pages with their IDs:

curl -s https://api.citexnode.com/api/v1/me/status-pages \
  -H "Authorization: Bearer $CITEXNODE_TOKEN"

Example: opening an incident

With a write token in the Authorization: Bearer header:

curl -s -X POST https://api.citexnode.com/api/v1/me/status-pages/PAGE_ID/incidents \
  -H "Authorization: Bearer $CITEXNODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title":  { "de": "Langsame Antworten der API", "en": "Slow API responses" },
    "impact": "degraded",
    "status": "investigating",
    "body":   { "de": "Wir sehen erhöhte Antwortzeiten und schauen nach.", "en": "We are seeing increased response times and are looking into it." }
  }'

This opens the incident and notifies subscribers and webhooks, just like the dashboard.

The values:

• impact: notice, degraded, partial_outage, major_outage.
• status: investigating, identified, monitoring, resolved.
• title and body with de and optionally en. German is required; if en is missing, English visitors see the German text.
• Optional components: the IDs of the affected components.

Further steps are posted as updates to POST …/incidents/INCIDENT_ID/updates with status and body. An update with "status": "resolved" closes the incident.

Components and check types

You create components with POST …/status-pages/PAGE_ID/components and change them with PATCH …/components/COMPONENT_ID. The check type goes in check_type: manual, http, tcp, dns, ping, ssl, heartbeat or citexnode. What belongs in target is described in Components and checks.

Settings that only one check type knows go in check_options:

Fields of other check types are ignored. interval_seconds runs from your plan's shortest interval to 3600, for a heartbeat to 86400.

A heartbeat component has no target. Instead, the response contains heartbeat_url, the secret URL for your job. A PATCH with "rotate_heartbeat": true issues a new one; the old one stops working immediately.

Example: a heartbeat for a backup

A nightly backup that may run up to 30 minutes late:

curl -s -X POST https://api.citexnode.com/api/v1/me/status-pages/PAGE_ID/components \
  -H "Authorization: Bearer $CITEXNODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":             { "de": "Nächtliches Backup", "en": "Nightly backup" },
    "check_type":       "heartbeat",
    "interval_seconds": 86400,
    "check_options":    { "grace_seconds": 1800 }
  }'

Take heartbeat_url from the response and call it at the end of the backup, for example with curl -fsS -m 10 "$HEARTBEAT_URL". Like the token, the URL belongs in your secrets, not in a repository.

Typical uses

• Your deploy script creates a maintenance before an update.
• Your own monitoring opens an incident when it sees something our checks can't.
• A script adds a component for every new server.