# how.is — API reference

Base URL: `https://how.is` · OpenAPI: `https://how.is/openapi.json` · MCP: `https://how.is/mcp` · Short guide: `https://how.is/llms.txt`

Domain and IP intelligence priced per call. Data comes from the live
[dns.pizza](https://dns.pizza) engine; site status and page watch are fetched live by how.is.

## How a call works

1. Call any endpoint — `POST` with a JSON body, or `GET` with the same field as a query parameter.
2. Without payment you get **HTTP 402**. The body lists every payment rail that works right now,
   and the `PAYMENT-REQUIRED` header carries x402 v2 terms.
3. Pay, repeat the same request, and get `{"result", "data", "receipt"}`.

The **free sample** for each check (listed below) returns real data with no payment, limited to
20 per hour per caller. Use it to learn the response shape.

**The first 20 calls per caller each day are free — no key, no wallet, no payment header, on any check priced at $0.010 or less. The counter is per API key if you send one, otherwise per IP, and it resets at 00:00 UTC.** Call it like any other request, with no payment at all.

## Paying

- **x402, per call, no account** — network `eip155:8453` (mainnet). Call any endpoint; the 402 carries a `PAYMENT-REQUIRED` header (base64 JSON, x402 v2, also copied into the body as `x402`). Sign it with any x402 client and retry with `PAYMENT-SIGNATURE: <base64 payload>`.
- **Prepaid key, paid by your user** (Stripe live mode) — no wallet needed. `POST https://how.is/v1/key` (free, no body) → `api_key` + `pay_url`. Keep the key; show your user the `pay_url` (a how.is/buy page: they pay by card from $5, and it never reveals the key). Send `Authorization: Bearer <api_key>`; calls work as soon as payment confirms. Over MCP, the free `add_credit` tool does the same. A 402 on a key with too little balance carries that key's `pay_url`. Each key has a daily spend cap (default $10.00); past it you get a 402 until 00:00 UTC.
- **Prepaid key, bought by a person directly** — `POST https://how.is/topup/checkout {"amount": 10}` → `checkout_url`; after payment the key is shown on how.is.

## Status codes

| code | meaning | charged? |
|---|---|---|
| 200 | result delivered | yes (free for samples) |
| 400 | bad input; body has `schema` and `example_body` | no |
| 402 | payment required, or daily cap reached | no |
| 404 | unknown path; body lists every endpoint | no |
| 429 | rate limited; see `retry_after_s` | no |
| 502 | upstream failed; `refunded: true` | refunded |
| 503 | upstream warming a cold cache; retry after `Retry-After` seconds | refunded |

## Checks

### URL pre-flight <a id="url_preflight"></a>

`POST /v1/url/preflight` · **$0.005** · MCP tool `url_preflight`

Check whether a URL is safe to fetch, read, sign in to, or pay — before you do. One verdict with plain reasons: domain age and newborn flag, lookalike of a top site, spam/abuse blocklists, HTTPS, robots.txt for your user agent, how our bot observatory sees your user agent, and the site's own x402 price if it answers 402. Fails closed: 'unknown' means do not proceed.

- Input: `{"url": {"type": "string", "format": "uri", "maxLength": 2000, "description": "The http(s) URL you are about to fetch"}, "ua": {"type": "string", "maxLength": 512, "description": "The user agent you will fetch with; robots.txt and our bot policy are judged for it. Defaults to the User-Agent of this request."}}`
- Returns: data: verdict (likely_safe/caution/high_risk/inconclusive), risk_score, safe_to{fetch,read,sign_in,pay} each yes/caution/no/unknown, actions{...: {answer, why}}, reasons[{risk, why}], domain_age_days, newborn, lookalike, https_valid, robots{allowed, token, status}, http{status, content_type, redirects}, x402{offers[{price_usd, network, pay_to}]}, bot_policy, not_checked[].
- Free sample: `{"url": "https://example.com"}` — or `GET https://how.is/v1/url/preflight?url=https%3A%2F%2Fsiteproxy.ruqli.workers.dev%3A443%2Fhttps%2Fexample.com`

```
curl -X POST https://how.is/v1/url/preflight -H "Authorization: Bearer $KEY" -d '{"url": "https://example.com"}'
```

### Read a page (with verdict) <a id="read_url"></a>

`POST /v1/read` · **$0.005** · MCP tool `read_url`

Read a web page as clean markdown, with the URL pre-flight verdict attached (and a viewport screenshot on request). Honors robots.txt for your user agent; flags text from risky sites as untrusted. Refunded if nothing can be read.

- Input: `{"url": {"type": "string", "format": "uri", "maxLength": 2000, "description": "The http(s) page to read"}, "ua": {"type": "string", "maxLength": 512, "description": "The user agent you will fetch with; robots.txt and our bot policy are judged for it. Defaults to the User-Agent of this request."}, "screenshot": {"type": "boolean", "description": "Also return a 1280x800 JPEG of the page"}}`
- Returns: data: markdown, title, description, lang, canonical, final_url, http_status, content_type, words, truncated, untrusted_content, preflight{verdict, safe_to, reasons, ...}, screenshot{image_base64, ...} when asked.
- Free sample: `{"url": "https://example.com"}` — or `GET https://how.is/v1/read?url=https%3A%2F%2Fsiteproxy.ruqli.workers.dev%3A443%2Fhttps%2Fexample.com`

```
curl -X POST https://how.is/v1/read -H "Authorization: Bearer $KEY" -d '{"url": "https://example.com"}'
```

### Domain profile (bundle) <a id="domain_profile"></a>

`POST /v1/domain/profile` · **$0.025** · MCP tool `domain_profile`

Everything about a domain in one call: DNS, WHOIS, TLS, DNSSEC, email auth, security score, blacklist status, plus IP intelligence for its A record.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.sections.{dns,whois,tls,dnssec,email-auth,security-score,blacklist,ip}; data.errors names any section that failed; data.billing says what was delivered.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/profile?domain=example.com`

```
curl -X POST https://how.is/v1/domain/profile -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Trust check <a id="domain_trust"></a>

`POST /v1/domain/trust` · **$0.020** · MCP tool `domain_trust`

Should an agent click, sign in to, or pay this domain? A risk score and verdict (likely_safe / caution / high_risk, or inconclusive when a check could not run) with plain-English reasons, from domain age, spam/abuse blocklists and the HTTPS certificate.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data: verdict, risk_score (0-100), reasons[{risk, why}], age_days, blocklist_listings, blocklists_unanswered[], https_valid, not_checked[].
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/trust?domain=example.com`

```
curl -X POST https://how.is/v1/domain/trust -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Company card <a id="company_lookup"></a>

`POST /v1/company` · **$0.010** · MCP tool `company_lookup`

Who runs this site? Company name and legal name, what they do, category, location and social links when known, mail/DNS/hosting providers, registration facts, and whether it is the same outfit as before, with a source and a confidence for every field. Unknown domains answer 404 and are not charged.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data: name, legal_name, description, categories, kind, audience, business_model, location{locality,region,country}, social{x,linkedin,...}, providers{dns,mail,hosting}, registration{registrar,created,expires,age_years,registrant_org}, ownership, confidence{overall,fields}, sources, not_checked[].
- Free sample: `{"domain": "stripe.com"}` — or `GET https://how.is/v1/company?domain=stripe.com`

```
curl -X POST https://how.is/v1/company -H "Authorization: Bearer $KEY" -d '{"domain": "stripe.com"}'
```

### DNS records <a id="domain_dns"></a>

`POST /v1/domain/dns` · **$0.005** · MCP tool `domain_dns`

A, AAAA, MX, NS, TXT and other records for a domain, with resolve timing.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data.records keyed by record type (A, AAAA, MX, NS, TXT, ...); data.data.responseTime.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/dns?domain=example.com`

```
curl -X POST https://how.is/v1/domain/dns -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### WHOIS / RDAP <a id="domain_whois"></a>

`POST /v1/domain/whois` · **$0.005** · MCP tool `domain_whois`

Registrar, creation and expiry dates, nameservers and status codes for a domain.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data.data: the parsed WHOIS/RDAP record (registrar, dates, nameservers, status).
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/whois?domain=example.com`

```
curl -X POST https://how.is/v1/domain/whois -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Domain age <a id="domain_age"></a>

`POST /v1/domain/age` · **$0.005** · MCP tool `domain_age`

How old a domain is: registration date, age in days and years, and whether it was registered in the last 30 days (a common phishing signal).

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data: created, age_days, age_years, newly_registered, expires, registrar, source.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/age?domain=example.com`

```
curl -X POST https://how.is/v1/domain/age -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Domain availability <a id="domain_available"></a>

`POST /v1/domain/available` · **$0.005** · MCP tool `domain_available`

Is this domain name registered? Asked of the registry over RDAP, with the standard first-year and renewal price when it is free to register.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data: available (true/false; null when only DNS could be checked, then likely_available), registered_on, suffix, source (rdap/dns), confidence, price{registration_usd, renewal_usd, registrar, note}, caveat.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/available?domain=example.com`

```
curl -X POST https://how.is/v1/domain/available -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Domain change history <a id="domain_changes"></a>

`POST /v1/domain/changes` · **$0.010** · MCP tool `domain_changes`

When did this domain appear in the registry zone file, leave it, come back, or change nameservers? From the daily gTLD + .com/.net zone files we capture (daily since 2026-08-05; monthly 2013-2018). A sudden nameserver move is a hijack or sale signal; a brand-new name is a phishing signal.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A registered name directly under a TLD, e.g. example.com (zone files list no subdomains; ccTLDs publish none)"}}`
- Returns: data: in_zone_now, first_seen, first_seen_is_coverage_start, last_seen, current_ns, events[{type: appeared|disappeared|reappeared|ns_changed, dates, from, to, message}], changed_last_30_days, coverage{daily_since, first_zone_file, runs}, ns_runs, note.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/changes?domain=example.com`

```
curl -X POST https://how.is/v1/domain/changes -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Brand look-alike domains <a id="brand_lookalikes"></a>

`POST /v1/brand/lookalikes` · **$0.020** · MCP tool `brand_lookalikes`

Newly registered look-alikes of a brand: names that entered the gTLD and .com/.net zones in the last 14 days and are a typo, a look-alike-character spelling (paypa1), the same name on another TLD, or the brand beside a lure word (paypal-login). Each with a risk tier and the reasons. Derived matches only, at most 50 — never a raw list of new domains.

- Input: `{"brand": {"type": "string", "maxLength": 253, "description": "A brand name or one of its domains, e.g. paypal or paypal.com (4-30 characters)"}, "days": {"type": "integer", "minimum": 1, "maximum": 14, "description": "Only names new in the last N zone days (default 14)"}, "min_tier": {"type": "string", "enum": ["critical", "high", "medium", "low"], "description": "Only matches at or above this tier"}}`
- Returns: data: brand, window{from,to,days}, matches[{domain, day, kind, matched, lures, tier, score, signals, ns{provider,hint}, census{state,registrar}, risk{tier,verdict,target}}], window_totals{total, by_tier, by_kind, listed_cap}, variants_searched, saturated, note.
- Free sample: `{"brand": "example"}` — or `GET https://how.is/v1/brand/lookalikes?brand=example`

```
curl -X POST https://how.is/v1/brand/lookalikes -H "Authorization: Bearer $KEY" -d '{"brand": "example"}'
```

### TLS certificate <a id="domain_tls"></a>

`POST /v1/domain/tls` · **$0.005** · MCP tool `domain_tls`

Certificate validity, issuer, protocol and days until expiry for a domain.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data: valid, issuer, subject, subjectAltNames, validFrom, validTo, daysUntilExpiry, protocol, cipher, selfSigned.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/tls?domain=example.com`

```
curl -X POST https://how.is/v1/domain/tls -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### DNSSEC <a id="domain_dnssec"></a>

`POST /v1/domain/dnssec` · **$0.005** · MCP tool `domain_dnssec`

Whether DNSSEC is signed and validates for a domain.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data: isSigned, isValid, validationStatus, chainOfTrust, dsRecords, dnskeyRecords, errors, warnings, recommendations.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/dnssec?domain=example.com`

```
curl -X POST https://how.is/v1/domain/dnssec -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Email authentication <a id="domain_email_auth"></a>

`POST /v1/domain/email-auth` · **$0.005** · MCP tool `domain_email_auth`

SPF, DKIM and DMARC records and posture for a domain.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data: spf, dkim, dmarc, mx, overallScore, overallStatus, recommendations.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/email-auth?domain=example.com`

```
curl -X POST https://how.is/v1/domain/email-auth -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Security score <a id="domain_security_score"></a>

`POST /v1/domain/security-score` · **$0.005** · MCP tool `domain_security_score`

A letter grade and point score for a domain security posture, with the scored items behind it.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data: grade, overallScore, maxPossibleScore, categories[] of scored items.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/security-score?domain=example.com`

```
curl -X POST https://how.is/v1/domain/security-score -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### Blacklist status <a id="domain_blacklist"></a>

`POST /v1/domain/blacklist` · **$0.005** · MCP tool `domain_blacklist`

Whether the addresses behind a domain appear on spam and abuse blocklists.

- Input: `{"domain": {"type": "string", "maxLength": 253, "description": "A bare domain name, e.g. example.com"}}`
- Returns: data.data.ipResults[]: target, isListed, listingCount, totalChecked.
- Free sample: `{"domain": "example.com"}` — or `GET https://how.is/v1/domain/blacklist?domain=example.com`

```
curl -X POST https://how.is/v1/domain/blacklist -H "Authorization: Bearer $KEY" -d '{"domain": "example.com"}'
```

### IP intelligence <a id="ip_lookup"></a>

`POST /v1/ip` · **$0.005** · MCP tool `ip_lookup`

Network owner (ASN), company, geolocation, privacy flags and abuse contact for an IP address.

- Input: `{"ip": {"type": "string", "description": "An IPv4 or IPv6 address"}}`
- Returns: data.data: ip, hostname, city, region, country, asn, company, privacy, carrier, abuse.
- Free sample: `{"ip": "1.1.1.1"}` — or `GET https://how.is/v1/ip?ip=1.1.1.1`

```
curl -X POST https://how.is/v1/ip -H "Authorization: Bearer $KEY" -d '{"ip": "1.1.1.1"}'
```

### Site status <a id="site_status"></a>

`POST /v1/check/site` · **$0.005** · MCP tool `site_status`

Live check of one or more URLs: HTTP status, latency, DNS resolve time, resolved IP, TTL, nameservers, TLS days remaining.

- Input: `{"sites": {"type": "array", "maxItems": 10, "items": {"type": "string", "format": "uri"}, "description": "Up to 10 http(s):// URLs"}}`
- Returns: data keyed by URL; each entry has ok, code, ms, dns_ms, ip, ttl, ns, cert_days, server, ts.
- Free sample: `{"sites": ["https://example.com"]}` — or `GET https://how.is/v1/check/site?sites=https://example.com`

```
curl -X POST https://how.is/v1/check/site -H "Authorization: Bearer $KEY" -d '{"sites": ["https://example.com"]}'
```

### Website screenshot <a id="site_screenshot"></a>

`POST /v1/site/screenshot` · **$0.020** · MCP tool `site_screenshot`

See a web page: a 1280-wide JPEG of any public URL, viewport or full page (capped at 6000 px), with its final URL, HTTP status and title.

- Input: `{"url": {"type": "string", "format": "uri", "maxLength": 2000, "description": "A public http(s) URL"}, "full_page": {"type": "boolean", "description": "Capture the whole page, not just the first screen"}}`
- Returns: data: image_base64 (JPEG), mime, width, height, final_url, http_status, title, note.
- Free sample: `{"url": "https://example.com"}` — or `GET https://how.is/v1/site/screenshot?url=https://example.com`

```
curl -X POST https://how.is/v1/site/screenshot -H "Authorization: Bearer $KEY" -d '{"url": "https://example.com"}'
```

### Page-change watch <a id="page_watch"></a>

`POST /v1/watch/page` · **$0.005** · MCP tool `page_watch`

Has this page changed since your last call, and how much? The first call stores a baseline; later calls return a text diff (2% threshold).

- Input: `{"url": {"type": "string", "format": "uri", "description": "An http(s):// URL on the public internet"}}`
- Returns: data with baseline, changed, change_pct, added, removed, last_change_ts.
- Free sample: `{"url": "https://example.com"}` — or `GET https://how.is/v1/watch/page?url=https://example.com`

```
curl -X POST https://how.is/v1/watch/page -H "Authorization: Bearer $KEY" -d '{"url": "https://example.com"}'
```

### Bot observatory feed <a id="bot_observatory"></a>

`POST /v1/bots` · **$0.050** · MCP tool `bot_observatory`

Partner tier of the dns.pizza bot observatory: every network (ASN), named crawler, TLS (JA4) fingerprint and firewall rule seen in the last 7 days, refreshed hourly. The public tier is free at https://dns.pizza/bots; unlimited pulls come with a monthly plan at https://how.is/bots.

- Input: `{}`
- Returns: data.data: generated_at, networks, bots, fingerprints (the free tier at dns.pizza/bots shows the same shape without fingerprints).
- No free sample.

```
curl -X POST https://how.is/v1/bots -H "Authorization: Bearer $KEY" -d '{}'
```

### Crawler identity check <a id="bot_verify"></a>

`POST /v1/bot/verify` · **$0.005** · MCP tool `bot_verify`

Verify a crawler's identity: is this visitor (IP + user-agent) really Googlebot, Bingbot, GPTBot, ClaudeBot, Applebot, PerplexityBot..., an impostor using the name, another bot, or likely a person? Checked against each operator's published IP lists and forward-confirmed reverse DNS, plus 7 days of bot-observatory firewall data on the network and TLS (JA4) fingerprint.

- Input: `{"ip": {"type": "string", "description": "The visitor's public IPv4 or IPv6 address"}, "ua": {"type": "string", "maxLength": 1000, "description": "The User-Agent header it sent (omit or empty if none)"}, "ja4": {"type": "string", "maxLength": 80, "description": "Optional TLS JA4 fingerprint, e.g. t13d1516h2_8daaf6152771_02713d6af862"}}`
- Returns: data: verdict (verified / impostor / unknown_bot / likely_human_or_unclassified), confidence, automation_likely, claimed, identified_as{operator, method, evidence}, reasons[], how_to_act, checks{published_ranges, reverse_dns, asn}, observatory{network, fingerprint, claimed_family, impostors_seen}.
- Free sample: `{"ip": "66.249.66.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"}` — or `GET https://how.is/v1/bot/verify?ip=66.249.66.1&ua=Mozilla%2F5.0+%28compatible%3B+Googlebot%2F2.1%3B+%2Bhttps%3A%2F%2Fsiteproxy.ruqli.workers.dev%3A443%2Fhttp%2Fwww.google.com%2Fbot.html%29`

```
curl -X POST https://how.is/v1/bot/verify -H "Authorization: Bearer $KEY" -d '{"ip": "66.249.66.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"}'
```

### Crawler identity check (batch) <a id="bot_verify_batch"></a>

`POST /v1/bot/verify/batch` · **$0.005** · MCP tool `bot_verify_batch`

Verify up to 100 visitors (IP + user-agent, optional JA4) in one call and one payment, billed per item: the same verdicts as bot_verify, for a log excerpt or a firewall review.

- Input: `{"items": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "object", "required": ["ip"], "additionalProperties": false, "properties": {"ip": {"type": "string", "description": "The visitor's public IPv4 or IPv6 address"}, "ua": {"type": "string", "maxLength": 1000, "description": "The User-Agent header it sent (omit or empty if none)"}, "ja4": {"type": "string", "maxLength": 80, "description": "Optional TLS JA4 fingerprint, e.g. t13d1516h2_8daaf6152771_02713d6af862"}}}, "description": "1-100 visitors; price is per item"}}`
- Returns: data: results[] (one bot_verify verdict per item, or {ip, error}), counts by verdict, billing{items, unit_price_usd}.
- Free sample: `{"items": [{"ip": "66.249.66.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"}]}` — or `POST https://how.is/v1/bot/verify/batch with a JSON body (no GET form)`

```
curl -X POST https://how.is/v1/bot/verify/batch -H "Authorization: Bearer $KEY" -d '{"items": [{"ip": "66.249.66.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"}]}'
```

## Bundle pricing

`profile` runs 8 checks for $0.025, versus
$0.040 bought separately. It is billed in full if at least one section comes back
(`data.errors` names the missing ones, `data.billing` restates it), and refunded only if every
section fails. Each profile also stores a free page-watch baseline for `https://<domain>`.

## Monitors <a id="monitors"></a>

Scheduled checks funded by a prepaid key; each run is charged at the check's price.

```
curl -X POST https://how.is/v1/monitors -H "Authorization: Bearer $KEY" \
  -d '{"type":"site","target":"https://example.com","interval_min":5}'
```

- `type`: `site` or `page`; `interval_min` ≥ 1
- `GET /v1/monitors` lists yours; `PATCH /v1/monitors/<id>` `{"enabled": false}` or `{"interval_min": 30}`;
  `DELETE /v1/monitors/<id>`
- Poll `GET /v1/monitors` for each monitor's state, last run and last summary. Alerts are not
  sent to customers yet. A cap or balance failure pauses the monitor.

## Account

- `GET /ledger` with your Bearer key: balance, today's spend, recent receipts.
- The daily spend cap (default $10.00) is raised by the operator on request.
