API reference

DownCTL exposes a small JSON API for reporting data into your account. All endpoints are versioned under /api/v1, except cron ping endpoints which are unversioned for shorter URLs.

Authentication

Two kinds of API keys are used, depending on the endpoint:

• Server key (X-Downctl-Key: srv_...) — used by the monitoring agent for server metrics. Scoped to a single server.
• Site secret key (X-Downctl-Key) or site public key (X-Downctl-Public-Key) — used for error reporting and cron sync. The secret key works from a trusted backend; the public key is safe to ship in client-side JS but is rejected on endpoints marked secret-only below.

Cron ping endpoints

No authentication header required — the ping token in the URL is the credential. Get the token and full ping URL for a monitor from the cron monitor sync response below, or from the dashboard.

GET or POST /ping/cron/{token}
GET or POST /ping/cron/{token}/started
GET or POST /ping/cron/{token}/finished
GET or POST /ping/cron/{token}/failed

Optional query/body parameters on started and finished:

Example, wrapping a cron job:

curl -fsS https://your-downctl-url.com/ping/cron/YOUR_TOKEN/started
your-actual-job.sh && \
  curl -fsS https://your-downctl-url.com/ping/cron/YOUR_TOKEN/finished || \
  curl -fsS https://your-downctl-url.com/ping/cron/YOUR_TOKEN/failed

Treat the ping token as a credential. Because there's no auth header, anyone who has the URL can ping the monitor. Keep it out of public repos, shared logs, and client-side code — store it in .env or a secrets manager, not hardcoded in a script or scheduler definition.

Server metrics

POST /api/v1/metrics
Header: X-Downctl-Key: srv_...

This is what downctl-agent posts every interval — you generally won't call this directly.

{
  "cpu_percent": 43.2,
  "memory_percent": 67.1,
  "memory_total_mb": 8192,
  "memory_used_mb": 5497,
  "disk_percent": 28.0,
  "disk_total_gb": 200,
  "disk_used_gb": 56,
  "load_avg_1m": 0.42,
  "load_avg_5m": 0.51,
  "load_avg_15m": 0.48
}

cpu_percent, memory_percent, and the memory/disk fields are required; the three load averages are optional.

Error reporting

POST /api/v1/errors
Header: X-Downctl-Key: <secret key>       (backend / PHP SDK)
Header: X-Downctl-Public-Key: <public key> (browser / JS SDK)

{
  "level": "error",
  "message": "RuntimeException: DB connection failed",
  "stack_trace": "#0 app/Services/Db.php(42): ...",
  "url": "https://myapp.com/checkout",
  "user_agent": "Mozilla/5.0 ...",
  "context": { "user_id": "123", "order_id": "456" }
}

level must be one of error, warning, or info. message is required (max 5,000 characters). Errors are grouped on a fingerprint derived from the message and the first stack trace line, so repeated occurrences of the same error increment a counter instead of creating duplicate entries.

Most integrations shouldn't call this endpoint directly — see error tracking for the JS SDK, the Laravel package, and the plain PHP package, which all wrap this call for you.

Cron monitor sync

POST /api/v1/cron-monitors/sync
Header: X-Downctl-Key: <secret key>   (secret key only — public key is rejected)

Registers or updates up to 100 cron monitors in one call — useful for defining monitors alongside your job schedule in code instead of clicking through the dashboard.

{
  "monitors": [
    {
      "name": "nightly-export",
      "cron_expression": "0 2 * * *",
      "timezone": "UTC",
      "missed_runs_before_alert": 2
    }
  ]
}

Each monitor needs either cron_expression or frequency_in_minutes (not both). Response includes the ping token and ready-to-use ping URL for each monitor:

{
  "monitors": [
    {
      "name": "nightly-export",
      "ping_token": "abc123...",
      "ping_url": "https://your-downctl-url.com/ping/cron/abc123...",
      "grace_time_in_minutes": 30,
      "missed_runs_before_alert": 2
    }
  ]
}

Rate limits