---
title: Using UpHeron from an AI agent
description: How AI agents discover the UpHeron API, read the docs as Markdown, check status for free, and add monitors with MPP payments.
---

# 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

| Resource | What it is |
|---|---|
| [`/auth.md`](https://upheron.com/auth.md) | How an agent gets API access by itself, for its user or on its own ([auth.md](/docs/auth-md)) |
| [`/mcp`](/docs/mcp) | MCP server: every operation as a tool, with MPP payments |
| [`/llms.txt`](/llms.txt) | An index of the documentation for language models |
| [`/llms-full.txt`](/llms-full.txt) | The whole documentation as one Markdown file |
| [`/openapi.json`](/openapi.json) | OpenAPI 3.1 description of the API, with MPP payment offers (`x-payment-info`) on the paid operations and service details (`x-service-info`) |
| Any page with `Accept: text/markdown` | The page as Markdown instead of HTML |
| Any page URL plus `.md` | The same, for clients that cannot set headers: [`/docs/agents.md`](/docs/agents.md) |

```bash
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](/docs/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`](https://upheron.com/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](/docs/payments#without-an-account).

## 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](/docs/software) has the format.

### Reading status

| `current_status` | Meaning |
|---|---|
| `pending` | Not checked yet |
| `up` | The latest checks passed |
| `down` | The latest checks failed at enough locations (see `confirmation_threshold`) |
| `degraded` | Responding, but outside a threshold such as latency |

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`:

```text
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 ops@example.com 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](/docs/payments#without-an-account).