---
title: UpHeron API and agent guide
description: Monitor websites and APIs from scripts and AI agents. Reading status is free; extra monitors are paid per location, monthly or for life, with the Machine Payments Protocol.
---

# 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](/docs/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](/docs/payments) (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](/docs/payments#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](/docs/software).
- **MCP server.** Connect Claude, Cursor or any MCP client to `https://upheron.com/mcp`. See [MCP server](/docs/mcp).
- **Agents sign up by themselves.** With [auth.md](/docs/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`](https://upheron.com/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.**

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

3. **Add a monitor.**

   ```bash
   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](/docs/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](/docs/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](/docs/api#errors).
- **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`](/docs/payments.md).
- [`/llms.txt`](/llms.txt) lists every page; [`/llms-full.txt`](/llms-full.txt) is the whole documentation in one file.
- [`/openapi.json`](/openapi.json) describes the API, including MPP payment offers for the paid operations.

[Using UpHeron from an AI agent](/docs/agents) has a recommended workflow and instructions you can give your agent.

## Pages

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