UpHeron
View as Markdown

UpHeron API and agent guide

UpHeron checks websites, APIs, certificates, DNS, mail servers and more from several locations, and tells you when something breaks. The API lets your scripts and AI agents do everything the dashboard does: read the status of every monitor, look at results and incidents, and add or change monitors.

  • Reading is free. Status, results, uptime and incidents cost nothing, within the rate limits.
  • Monitors in your plan are free. Creating a monitor costs nothing while your plan has a free slot.
  • Extra monitors cost $0.01 per location per month, or $0.10 per location for life. Beyond your plan's slots, an agent pays from prepaid credit or on the spot with the Machine Payments Protocol (MPP). Payments are processed by Stripe; prices include VAT.
  • Paid monitors check as often as every 10 seconds, on any plan.
  • No account needed. An agent can create a monitor by paying alone; the response returns an API key for the new monitor's workspace. See Without an account.
  • Vulnerability alerts (Pro plans). Website monitors can alert when a vulnerability is published for the software the site runs, found by scanning it or imported from a lockfile, Dockerfile or a list an agent writes. See Software lists.
  • MCP server. Connect Claude, Cursor or any MCP client to https://upheron.com/mcp. See MCP server.
  • Agents sign up by themselves. With auth.md, an agent gets access for its user (who types a 6-digit code) or on its own, without anyone creating a token. Agents start at /auth.md.

Quick start

  1. Create a token. In the dashboard, open Settings → API tokens and create a token. Give it the write scope if it should create or change monitors; read is enough for status. The token is shown once.

  2. Read your monitors.

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

  3. Add a monitor.

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

    While your plan has a free slot this returns 201 Created. When it has none, it returns 402 Payment Required with an MPP challenge for the price; an MPP client pays and retries automatically. See Payments.

What it costs

Action Price
Read monitors, results, uptime, incidents, receipts Free, within the rate limits
Create a monitor while the plan has a free slot Free
Create a monitor when every plan slot is used $0.01 per location per 30 days, renewed from credit
… or for life ("billing_period": "lifetime") $0.10 per location, once
Create a monitor without an account Same prices, paid on the spot
Add a location to a paid monitor One period's price (or the lifetime price) per new location
Pause, resume, edit or delete any monitor Free

Prices are in US dollars and include VAT. A card payment is at least $0.50 (Stripe's minimum); the rest stays as credit, so $0.50 covers 50 location-months or 5 lifetime locations. GET /api/v1/account always returns the current price, your free slots and your credit.

Conventions

  • Base URL: https://upheron.com/api/v1
  • Authentication: an API token in the X-API-Key header. See Authentication.
  • Format: JSON in and out, UTF-8. Timestamps are ISO 8601 in UTC. Money is in US cents (amount_cents), except MPP amounts, which are decimal dollars ("0.02").
  • Errors: a JSON body with a machine-readable error and a human-readable message. See API reference.
  • Retries: send an Idempotency-Key header when creating monitors, so a retry never creates or pays for a second one.

For AI agents

Everything here is available in a form agents read well:

  • Ask for any page with Accept: text/markdown, or add .md to its URL, to get Markdown instead of HTML: /docs/payments.md.
  • /llms.txt lists every page; /llms-full.txt is the whole documentation in one file.
  • /openapi.json describes the API, including MPP payment offers for the paid operations.

Using UpHeron from an AI agent has a recommended workflow and instructions you can give your agent.

Pages

  • Authentication: tokens, scopes and headers
  • MCP server: connect AI agents as tools
  • Payments: pay-per-monitor pricing, MPP, credit, receipts and VAT
  • API reference: every endpoint with examples
  • Rate limits: limits, headers and fair use
  • AI agents: discovery, workflow and agent instructions
  • Software lists: telling a monitor what a website runs, for vulnerability alerts: the list format and supported files