#Using UpHeron from an AI agent

UpHeron is built to be used by agents as well as people. An agent can find out what UpHeron does, check whether a site is up, add monitors, and pay for them, without a human filling in forms.

#Discovery

curl -H "Accept: text/markdown" https://upheron.com/docs/payments

Markdown responses have Content-Type: text/markdown; charset=utf-8, an x-markdown-tokens header with an estimate of their length in tokens, and Vary: Accept.

#Getting access

• Your user gives you a token. They create one in Settings → API tokens; send it in X-API-Key.
• You get access yourself with auth.md. Register at POST https://upheron.com/agent/identity with your user's email (service_auth); they open a link and type the code you show them, and you receive access tokens for their workspace. Or register as anonymous to act alone in an agent workspace of your own that your user can claim later. Follow /auth.md step by step.
• You pay without an account. POST /monitors without a token answers 402; paying creates an agent workspace and returns its key. See Payments.

#Recommended workflow

1. Check your account. GET /api/v1/account returns free plan slots, credit and current prices. GET /api/v1/locations lists the location codes you can use.
2. Quote before creating. POST /api/v1/monitors/quote with the monitor you want returns amount_due_cents. If it is 0, creating is free (a plan slot or credit covers it).
3. Create with an idempotency key. POST /api/v1/monitors with Idempotency-Key: <uuid>. If it answers 402, let your MPP client pay; keep the same idempotency key on any retry of your own.
4. Read status. GET /api/v1/monitors returns every monitor's current_status. Poll no faster than the monitor's interval_seconds.
5. Look closer when something is wrong. GET /api/v1/monitors/{id} has uptime for 24 hours, 7 days and 30 days, recent results with errors, and incidents. GET /api/v1/monitors/{id}/results returns up to 500 results, and GET /api/v1/monitors/{id}/uptime?from=2026-01-01&to=2026-03-31 daily uptime for any range: it is kept for as long as the monitor exists.
6. Watch the website's software (Pro plans). Set "vulnerability_alerts": true on a website monitor. If you can see the server, send what it runs with POST /api/v1/monitors/{id}/software/import: a lockfile or Dockerfile, or a list with one name version per line from cat /etc/os-release, nginx -v, php -v and the like. GET /api/v1/monitors/{id}/vulnerabilities lists what affects it and the versions that fix it. Software lists has the format.

#Reading status

An incident opens after failure_threshold failed checks in a row (by default the first) and resolves after recovery_threshold successes. A monitor with "status": "paused" is not being checked; one with "billing_state": "overdue" was paused because its monthly renewal was not paid.

#Instructions for your agent

Paste this into your agent's instructions or tool description, and give it a token in UPTIME_MONITOR_API_KEY:

You can monitor websites and APIs with UpHeron (https://upheron.com).
- API base: https://upheron.com/api/v1 ; send the header X-API-Key: $UPTIME_MONITOR_API_KEY on every request.
- Docs as Markdown: https://upheron.com/llms-full.txt ; API schema: https://upheron.com/openapi.json
- Reading is free: GET /monitors (all statuses), GET /monitors/{id} (uptime, results, incidents), GET /monitors/{id}/uptime (daily uptime, ?from=&to=), GET /incidents.
- To add a monitor: POST /monitors/quote first; then POST /monitors with an Idempotency-Key header.
  Body: {"name": "...", "url": "https://...", "interval_seconds": 300, "locations": ["<code from GET /locations>"]}
- If a request returns 402 Payment Required, it costs money: tell the user the amount_due and ask before paying,
  unless they have already approved a budget. Monitors cost $0.01 per location per month, or $0.10 per location for life.
- On 429, wait Retry-After seconds. Never poll a monitor faster than its interval_seconds.
- Pro plans: with "vulnerability_alerts": true on a website monitor, POST /monitors/{id}/software/import {"content": "<lockfile, Dockerfile or one 'name version' per line>"}
  tells it what the server runs; GET /monitors/{id}/vulnerabilities lists what affects it.

Asking before paying is a good default. Approve a budget once (for example "up to $1 for monitors this week") so the agent can act alone within it.

#Example prompts

• "Is shop.example.com up right now, and has it had any incidents this week?"
• "Monitor https://api.example.com/health every minute from Frankfurt and New York, and email [email protected] when it goes down."
• "Add lifetime monitors for these five client websites; you can spend up to $0.50."
• "Turn on vulnerability alerts for shop.example.com and import this server's composer.lock and the output of nginx -v and php -v."

#No account? Pay as you go

An agent with an MPP wallet can create a monitor without any account: send POST /api/v1/monitors without X-API-Key, pay the 402, and store the api_key from the response. See Payments → Without an account.