REST API

Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key from your Account settings.

Free plan accounts will receive a 403 Forbidden response. Upgrade to Pro or Agency for API access.

Base URL

Endpoints

Everything you can configure in the dashboard is available through the API. All endpoints are scoped to the account that owns the API key.

Returns all domains on your account, including their current SSL certificate status and domain registration details.

Example request

Example response

{
  "domains": [
    {
      "id": "abc-123",
      "domain": "example.com",
      "verified": true,
      "verification_status": "verified",
      "paused": false,
      "last_checked_at": "2026-04-04T12:00:00Z",
      "created_at": "2026-03-01T08:30:00Z",
      "ssl": {
        "status": "ok",
        "issuer": "/O=Let's Encrypt/CN=R3",
        "expires_at": "2026-07-01T00:00:00Z",
        "days_until_expiry": 88,
        "chain_valid": true
      },
      "domain_registration": {
        "registrar": "Namecheap, Inc.",
        "expires_at": "2027-03-01T00:00:00Z",
        "days_until_expiry": 331
      }
    }
  ]
}

Add one or more domains to your account. Returns TXT record values you'll need to set on each domain for ownership verification.

Request body

Example — single domain

Example — multiple domains

Example response

{
  "created": [
    {
      "id": "abc-123",
      "domain": "example.com",
      "verified": false,
      "verification_status": "pending",
      "verification": {
        "txt_record_host": "_xpiry.example.com",
        "txt_record_value": "xpiry-verify=a1b2c3d4e5f6..."
      }
    }
  ],
  "errors": []
}

Permanently delete a domain and all its associated data (SSL certificates, check history, alerts).

Example request

Example response

{
  "message": "Domain 'example.com' deleted."
}

Configure the public status page, including serving it on your own hostname. Setting custom_domain starts verification; the response includes the CNAME record to add at your DNS provider.

Example request

Example response

{
  "status_page": {
    "enabled": true,
    "slug": "example-com-1a2b3c4d",
    "url": "https://xpiry.com/status/example-com-1a2b3c4d",
    "theme": "dark",
    "custom_domain": {
      "hostname": "status.example.com",
      "status": "pending",
      "live": false,
      "cname": {
        "host": "status.example.com",
        "target": "status.xpiry.dev"
      }
    }
  },
  "message": "Verification started. Add the CNAME record from custom_domain.cname to activate status.example.com."
}

The high-volume ingest path. Two credentials are required: the path token identifies the monitor, and an Authorization: Bearer <API key> header authorizes the account that owns it (the same keys this REST API uses). Each monitor has its own token; find the full URL in the dashboard or in the ping_url field of the monitor API responses below. Both GET and POST work. Ingest is subject to a per-plan daily event budget; over it the endpoint returns 429.

Examples

Parameters

Responses

Example response

The ping URL returns plain text, not JSON.

# 200 — success
OK

# 422 — a metric ping with no value
value is required for metric monitors

Create a heartbeat or metric monitor. The response includes the monitor's ping_url. Heartbeats require expected_interval_seconds; metrics require at least one of warn_threshold / critical_threshold.

Request body

Wrap the fields in a monitor object.

Example — heartbeat

Example — metric

Example response

{
  "monitor": {
    "id": "mon-789",
    "name": "Nightly backup",
    "kind": "heartbeat",
    "status": "unknown",
    "enabled": true,
    "component_group": "Jobs",
    "show_on_status_page": true,
    "ping_url": "https://xpiry.com/ping/xpm_aB3dE4fG...",
    "last_event_at": null,
    "down_since": null,
    "acknowledged_until": null,
    "availability": { "last_24h": null, "last_7d": null, "last_30d": null },
    "heartbeat": {
      "expected_interval_seconds": 86400,
      "grace_period_seconds": 3600,
      "max_duration_seconds": null,
      "last_duration_ms": null,
      "start_url": "https://xpiry.com/ping/xpm_aB3dE4fG.../start"
    },
    "recent_events": []
  }
}

Lists a domain's monitors. Each carries a heartbeat or metric block depending on its kind, plus 24h/7d/30d availability. GET /monitors/:id returns the same shape with a recent_events array (the last 20 pings).

Example response

{
  "domain_id": "abc-123",
  "monitors": [
    {
      "id": "mon-456",
      "name": "Queue depth",
      "kind": "metric",
      "status": "up",
      "enabled": true,
      "component_group": "Workers",
      "show_on_status_page": true,
      "ping_url": "https://xpiry.com/ping/xpm_aB3dE4fG...",
      "last_event_at": "2026-06-16T11:59:00Z",
      "down_since": null,
      "acknowledged_until": null,
      "availability": { "last_24h": 100.0, "last_7d": 99.8, "last_30d": 99.9 },
      "metric": {
        "unit": "jobs",
        "value_direction": "up_bad",
        "warn_threshold": 100.0,
        "critical_threshold": 500.0,
        "stale_after_seconds": null,
        "last_value": 42.0,
        "show_value_on_status_page": true
      }
    }
  ]
}

Record an event over the authenticated API instead of the public ping URL: useful for clients already holding a Bearer token. Accepts the same fields as the ping URL: state (ok/fail), value, duration_ms, error. Returns the updated monitor.

Example — push a metric value

Request body

Example response

Returns the monitor with its new status and value (no recent_events block).

{
  "monitor": {
    "id": "mon-456",
    "name": "Queue depth",
    "kind": "metric",
    "status": "up",
    "enabled": true,
    "component_group": "Workers",
    "show_on_status_page": true,
    "ping_url": "https://xpiry.com/ping/xpm_aB3dE4fG...",
    "last_event_at": "2026-06-16T12:00:00Z",
    "down_since": null,
    "acknowledged_until": null,
    "availability": { "last_24h": 100.0, "last_7d": 99.8, "last_30d": 99.9 },
    "metric": {
      "unit": "jobs",
      "value_direction": "up_bad",
      "warn_threshold": 100.0,
      "critical_threshold": 500.0,
      "stale_after_seconds": null,
      "last_value": 87.0,
      "show_value_on_status_page": true
    }
  }
}

Error responses

All errors return a JSON object with an error key.

Example error

{
  "error": "Invalid API key."
}