Log in Get started
Documentation · API

For agents: start without a person

An AI agent or any program can open a PingWise account on its own, monitor the domains it proves it controls, and hand the account to a person with a claim link. Limits, endpoints and the rules.

A program can open an account at PingWise without a person in the loop: one call returns an API key and a claim link. The account is unclaimed until a person opens that link; while unclaimed it is small, it can only monitor domains it has proved it controls, and it is deleted after 72 hours. Once claimed it is an ordinary account.

This page is for the agent. If you are the person who received a claim link, open it, type your email address, accept the Terms, and the account is yours.

Copy this into your agent

Paste the text below into an agent that can run commands or make HTTP requests (Claude Code, Cursor, Codex, ChatGPT in agent mode). A chat assistant without tools will only explain the steps.

Set up uptime monitoring for my website with PingWise (https://pingwise.com).
1. Register an account for me: POST https://app.pingwise.com/api/v1/agent/register, body {"name": "<my site name>"}. Save the api_key from the answer (it is shown only once) and use it as "Authorization: Bearer <api_key>" on every later request. Show me the claim_url and the expires_at time from the answer.
2. Prove I control my domain: POST https://app.pingwise.com/api/v1/domains {"name": "<my domain>"}. Tell me the TXT record (name and value) to add in my DNS, or the file to put on my site, and wait for me to say it's done. Then call POST https://app.pingwise.com/api/v1/domains/<my domain>/verify until "verified" is true (DNS can take a few minutes).
3. Add up to 5 monitors on that domain, every 60 seconds or slower: POST https://app.pingwise.com/api/v1/monitors {"type": "http", "url": "https://<my domain>/", "interval": 60}. Ask me which pages or services matter if you're not sure.
4. If I give you a webhook URL on the same domain, add it for alerts: POST https://app.pingwise.com/api/v1/channels {"kind": "webhook", "url": "<my webhook URL>"}.
Rules: only act on confirmed outages (incidents), never on a single failed check. Full API: https://app.pingwise.com/api/v1/openapi.json
When you're done, remind me to open the claim_url within 72 hours, or the account and its monitors are deleted.

In one go

# 1. Register (no key needed). Keep api_key: it is shown once.
curl -X POST https://app.pingwise.com/api/v1/agent/register \
  -H "Content-Type: application/json" -d '{"name": "shop.example.com"}'

# 2. Add the domain and read back the TXT record (or file) that proves it
curl -X POST https://app.pingwise.com/api/v1/domains \
  -H "Authorization: Bearer pw_..." -H "Content-Type: application/json" -d '{"name": "example.com"}'

# 3. Put the record or the file in place, then ask us to check
curl -X POST https://app.pingwise.com/api/v1/domains/example.com/verify -H "Authorization: Bearer pw_..."

# 4. Add a monitor and a webhook on that domain
curl -X POST https://app.pingwise.com/api/v1/monitors -H "Authorization: Bearer pw_..." \
  -H "Content-Type: application/json" -d '{"type": "http", "url": "https://shop.example.com/", "interval": 60}'
curl -X POST https://app.pingwise.com/api/v1/channels -H "Authorization: Bearer pw_..." \
  -H "Content-Type: application/json" -d '{"kind": "webhook", "url": "https://shop.example.com/hooks/pingwise"}'

# 5. Give claim_url to the person responsible.

Registering

POST /api/v1/agent/register takes an optional name and needs no key. The answer carries:

  • api_key, shown once; it has write scope within the limits below;
  • claim_url, the link a person opens to take the account over;
  • expires_at, 72 hours after registration;
  • limits: 5 monitors, 60 seconds as the fastest interval, 21,600 starter credits, 72 hours;
  • terms: the sentence «By using this key, whoever operates this client accepts the Terms of Service, the Acceptable Use Policy and the Privacy Policy.» and links to the three documents;
  • next_steps, in words.

Every later answer carries the header PingWise-Account-Expires, and GET /api/v1/account has an unclaimed block with the expiry and the limits.

Registration is limited to 5 an hour per address and 20 a day per /24 or /48, and to 500 unclaimed accounts alive at once. Over a limit the answer is 429 with Retry-After and the reason. Opening accounts repeatedly to extend the 72 hours or to dodge the limits is against the Acceptable Use Policy.

Proving a domain

An unclaimed account can monitor only hosts on a domain it has verified. POST /api/v1/domains with the registrable domain returns the proof you need, both ways:

  • txt: a DNS record named _pingwise.<domain> with the value pingwise-verify=<token>;
  • file: https://<domain>/.well-known/pingwise-verify.txt containing the token.

Put either in place, then POST /api/v1/domains/<domain>/verify. The answer says whether it worked, and if not, what was missing. A monitor on a host whose domain is not verified is refused with 422. The older names, _uptimebox.<domain> and uptimebox-verify.txt, still verify. Details: Domain verification.

What an unclaimed account can do

  • Monitors: up to 5, at 60 seconds or slower, on verified domains only: HTTP(S), keyword, TLS, ping, TCP, SMTP, DNS and the other probe-side checks.
  • Credits: 21,600 once, enough for 5 monitors every minute for 72 hours. No monthly free credits and no purchases until a person claims it.
  • Alerts: webhooks only, and only to a URL on a verified domain of the account, or a status page of the account. POST /api/v1/channels returns the signing_secret once; every delivery is signed, see Webhooks. No email, SMS or chat channels.
  • Status pages: allowed, without email subscribers and without a custom domain until claimed.
  • Expiry: 72 hours after registration the account and everything in it are deleted, with no warning email, since there is nobody to email. The expiry is in every answer; act on it.

Claiming

The person opens claim_url, types an email address, ticks the Terms box and gets a sign-in link. On the first sign-in they become the owner of the same account, which turns into a normal account: the free credits of that month, every channel type, purchases, the panel. Nothing the agent set up is lost. The claim link is as secret as the key: give it only to the person responsible.

Only act on confirmed outages

PingWise marks a site down only when two thirds of the probes that checked it, on at least three continents and three networks, agree twice in a row. An agent that reacts to alerts, by rolling back a deploy or posting an incident, should react to monitor.down and nothing earlier. Every incident in the API and every webhook carries a quorum block: how many probes agreed out of how many checked, the continents and networks among them, and the rule in force at the time. A monitor.partial event means one region could not reach the site while the rest could; it is information, not an outage.

Reading the rest of the API: reference, OpenAPI document, and every docs page as Markdown by adding .md to its path.

Last change: 6 November 2026.