#API reference

Base URL: https://upheron.com/api/v1. Send your token as X-API-Key (see Authentication). Requests and responses are JSON; lists come back as {"data": [...]}. The machine-readable version of this page is /openapi.json.

Operations marked Paid can answer 402 Payment Required with an MPP challenge; see Payments. Everything else is free within the rate limits.

#Account

#GET /account

Plan slots, credit and prices

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/account \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#PUT /account/billing

Set invoice details (name, address, country, VAT number)

Responses: 200, 401, 403, 422, 429.

curl -X PUT https://upheron.com/api/v1/account/billing \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"billing_country": "DE", "billing_vat_id": "DE123456789"}'

#GET /account/credit

Credit movements, newest first

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/account/credit \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /alert-channels

Notification contacts

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/alert-channels \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /alert-channels

Add a notification contact (email contacts must confirm a link first)

Responses: 201, 401, 403, 422, 429.

curl -X POST https://upheron.com/api/v1/alert-channels \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ops", "kind": "email", "destination": "[email protected]"}'

#DELETE /alert-channels/{id}

Remove a notification contact

Responses: 204, 401, 403, 404, 429.

curl -X DELETE https://upheron.com/api/v1/alert-channels/$ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /alert-channels/{id}/test

Send a test alert

Responses: 200, 401, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/alert-channels/$ID/test \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#Monitors

#GET /locations

Monitoring locations you can choose

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/locations \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /monitors

Every monitor and its current status

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/monitors \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /monitors

Create a monitor (paid when no plan slot is free, or without an account) · Paid · token optional

Free while the plan has a free monitor slot. Otherwise costs the per-location price for 30 days (billing_period: monthly) or ten times that for life (lifetime), taken from credit; if credit is short the response is 402 with an MPP challenge for the difference. Ask POST /monitors/quote first to see the price.

Without an API token the request is always paid (agent-plan limits: 60-second minimum interval, no group monitors). After payment the 201 response also contains api_key and workspace: a new pay-as-you-go workspace that owns the monitor. The key is shown once.

Responses: 200, 201, 401, 402, 403, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "url": "https://example.com"}'

#POST /monitors/quote

Price a monitor without creating it

Responses: 200, 401, 403, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/quote \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "url": "https://example.com"}'

#GET /monitors/{id}

A monitor with uptime, recent results, 90 daily bars, its whole history and incidents

Responses: 200, 401, 404, 429.

curl -X GET https://upheron.com/api/v1/monitors/$ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#PATCH /monitors/{id}

Change a monitor (adding locations to a paid monitor is paid) · Paid

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X PATCH https://upheron.com/api/v1/monitors/$ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "url": "https://example.com"}'

#DELETE /monitors/{id}

Delete a monitor (frees its plan slot; paid monitors are not refunded)

Responses: 204, 401, 403, 404, 429.

curl -X DELETE https://upheron.com/api/v1/monitors/$ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /monitors/{id}/quote

Price a monitor change without applying it

Responses: 200, 401, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/quote \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "url": "https://example.com"}'

#POST /monitors/{id}/renew

Renew a monthly paid monitor for 30 more days · Paid

Renewals happen automatically every hour from credit. Call this to renew early (the 30 days are added to the remaining time) or to resume a monitor that was paused for non-payment. Pays from credit, or answers 402 with an MPP challenge.

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/renew \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "url": "https://example.com"}'

#POST /monitors/{id}/renew/quote

Price a renewal

Responses: 200, 401, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/renew/quote \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /monitors/{id}/pause

Stop checking

Responses: 200, 401, 403, 404, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/pause \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /monitors/{id}/resume

Start checking again

Responses: 200, 401, 403, 404, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/resume \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#Vulnerabilities

#GET /monitors/{id}/vulnerabilities

Findings in the website's software (exploited and most severe first) and the software they were matched on

Responses: 200, 401, 404, 429.

curl -X GET https://upheron.com/api/v1/monitors/$ID/vulnerabilities \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /monitors/{id}/vulnerabilities/scan

Scan the website for its software and check it now instead of waiting for the weekly scan

Responses: 202, 401, 402, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/vulnerabilities/scan \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /monitors/{id}/vulnerabilities/{finding_id}/fixed

Record that a finding's software was upgraded: to version, or by default to the first version that fixes it; the monitor is checked again

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/vulnerabilities/{finding_id}/fixed \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example", "url": "https://example.com"}'

#POST /monitors/{id}/software

Add software the website runs, by name (Debian, nginx), package (npm:lodash, wp-plugin:slug) or NVD product (cpe:vendor:product)

Responses: 201, 401, 402, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/software \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Debian", "version": "12"}'

#POST /monitors/{id}/software/import

Import a manifest, lockfile, Dockerfile, Compose file or a plain list (one "name version" per line); importing a filename again replaces what it added

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X POST https://upheron.com/api/v1/monitors/$ID/software/import \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Debian 12\nnginx 1.24.0\nPHP 8.2.12\nwp-plugin:woocommerce 9.3.3"}'

#DELETE /monitors/{id}/software/import

Remove everything a file imported

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X DELETE https://upheron.com/api/v1/monitors/$ID/software/import \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#PATCH /monitors/{id}/software/{software_id}

Set an entry's version (it then counts as added by hand), or ignore or restore it

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X PATCH https://upheron.com/api/v1/monitors/$ID/software/$SOFTWARE_ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": "1.24.0"}'

#DELETE /monitors/{id}/software/{software_id}

Remove an entry; software the scan found is ignored instead, so it is not added back

Responses: 200, 401, 402, 403, 404, 422, 429.

curl -X DELETE https://upheron.com/api/v1/monitors/$ID/software/$SOFTWARE_ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /software-catalog

Software known by name; any package (npm:, composer:, pypi:, gem:, go:, maven:, nuget:, cargo:), wp-plugin:/wp-theme: slug or cpe:vendor:product works too

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/software-catalog \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#Results

#GET /monitors/{id}/results

Recent check results, newest first

Responses: 200, 401, 404, 429.

curl -X GET https://upheron.com/api/v1/monitors/$ID/results \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /monitors/{id}/uptime

Daily uptime for any range, kept for as long as the monitor

One entry per UTC day, oldest first. Without from and to, every day from the first check (since) to today. At most 3660 days per request.

Responses: 200, 401, 404, 422, 429.

curl -X GET https://upheron.com/api/v1/monitors/$ID/uptime \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /incidents

Incidents, newest first

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/incidents \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /incidents/{id}

One incident with its events

Responses: 200, 401, 404, 429.

curl -X GET https://upheron.com/api/v1/incidents/$ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#POST /incidents/{id}/acknowledge

Acknowledge an incident

Responses: 200, 401, 403, 404, 429.

curl -X POST https://upheron.com/api/v1/incidents/$ID/acknowledge \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#Payments

#POST /credits

Buy prepaid credit with MPP · Paid

Always answered with 402 and an MPP challenge for amount_cents until paid. Cards (Stripe shared payment tokens) need at least $0.50.

Responses: 200, 401, 402, 403, 422, 429, 503.

curl -X POST https://upheron.com/api/v1/credits \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 500}'

#GET /payments

Payments, newest first

Responses: 200, 401, 429.

curl -X GET https://upheron.com/api/v1/payments \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /payments/{id}

One payment

Responses: 200, 401, 404, 429.

curl -X GET https://upheron.com/api/v1/payments/$ID \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#GET /payments/{id}/receipt

Receipt with seller and VAT details (JSON, or Markdown with Accept: text/markdown)

Responses: 200, 401, 404, 429.

curl -X GET https://upheron.com/api/v1/payments/$ID/receipt \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY"

#Check options

check_options carries the settings specific to a monitor kind. The most common:

Network checks (tcp, ssh, mail, ftps, ntp, udp, minecraft, ssl) take host or host:port in url; tcp and udp need the port.

http and api monitors alert 30, 14, 7, 3 and 1 days before their domain registration expires and, for HTTPS, before their TLS certificate expires without having been renewed: certificate alerts start at a sixth of the certificate's lifetime, at most 14 days ahead, after automatic renewal (Let's Encrypt, Cloudflare) should have happened. Send "expiry_alerts": false to turn both off. The monitor reports domain_name, domain_expires_at, cert_issuer and cert_expires_at after the daily checks.

On paid plans, http and api monitors can also alert on vulnerabilities in the software their website runs: send "vulnerability_alerts": true, and optionally "vulnerability_severity" (low, the default, medium, high or critical) for the lowest severity that alerts. Actively exploited vulnerabilities and releases reaching end of support always alert. Free plans get 422 with plan_required.

The software is found by a weekly scan of the website (POST /monitors/{id}/vulnerabilities/scan runs one now) and can be told directly: POST /monitors/{id}/software/import takes a file's text and optional filename (package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, composer.json/.lock, requirements.txt, Pipfile.lock, poetry.lock, Gemfile.lock, go.mod, Cargo.lock, pom.xml, .csproj, Dockerfile, docker-compose.yml, .nvmrc, .tool-versions) or a plain list with one name version per line, such as Debian 12, nginx 1.24.0 or npm:lodash 4.17.21 (format and supported files). POST /monitors/{id}/software adds one entry. GET /monitors/{id}/vulnerabilities returns the software and the findings: exploited and most severe first, each with severity, fixed_in, fix_version (the first version that fixes it), exploited_on (CISA's exploited list) and version_known (false when the advisory only may apply). After upgrading, POST /monitors/{id}/vulnerabilities/{finding_id}/fixed records the new version (by default fix_version, or {"version": "…"}) and checks again. These endpoints answer 402 with plan_required on plans without vulnerability alerts.

A heartbeat monitor's heartbeat_url takes a GET or POST after each successful run. Add /fail to the URL to report a failed run: the incident opens at once instead of after the failure threshold.

Invalid options are reported as 422 with the offending fields.

#Notification contacts

A workspace alerts its notification contacts when a monitor goes down and recovers. Add them with POST /api/v1/alert-channels:

curl https://upheron.com/api/v1/alert-channels \
  -H "X-API-Key: $UPTIME_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ops", "kind": "email", "destination": "[email protected]"}'

An email contact receives a confirmation link and is alerted only after it is opened. New monitors alert every contact unless you pass alert_channel_ids. Pay-as-you-go workspaces can use email and webhook contacts.

#Errors

Errors have a JSON body with a machine-readable error and a human-readable message; validation errors add fields.

{ "error": "validation_failed", "message": "Some fields are invalid.", "fields": { "url": ["can't be blank"] } }