---
title: "Create Ping Watch"
method: POST
path: "/watch/ping"
tags: ["watch"]
---

# Create Ping Watch

`POST /watch/ping`

## Request

- Base URL: `https://dnsdoctor.dev/api/v1`
- URL: `https://dnsdoctor.dev/api/v1/watch/ping`
- Auth: none declared

Buy an HTTP ping watch: one URL, five regions on four continents, up to 24 hours.

Same gate order as the propagation create, with one gate more: the URL is put
through the SSRF seam (structural rules, then resolve-and-pin) BEFORE the lane
opens, so a target we would never dispatch five hosts at is a free 422. The
per-check re-resolve in `watch/ping.py` is what closes the rebinding window
afterwards — this pre-flight only keeps an unbuyable target from being sold.

## Request body

- WatchPingIn: The ping watch's terms. The URL itself is validated in `watch/targets.py`. `cadence_seconds` is bounded to the two cadences we sell at the MODEL, so an unsold cadence is refused during parse rather than silently priced as the cheap one. The HTTP method is deliberately NOT a buyer knob: the probe fleet issues a `HEAD`, which is the smallest request that answers "does this URL still respond" and the least useful thing to aim at a third party.
  - `url` string, required: The URL to check. It is fetched over the shared probe fleet and stored for the life of the watch, so it must not carry a secret — no token, key or signature in the path or query.
  - `cadence_seconds` integer
  - `window_hours` number

## Response `200`

Successful Response

- WatchCreated: The minted handle plus the terms it was sold on. Deterministic throughout: an echo of what the buyer asked for, the price that was settled, and where to poll. No prose, no record, no prescription — the D94 invariant carries onto every watch surface.
  - `watch_id` string, required
  - `kind` string, required
  - `target` string, required
  - `record_type` string, nullable, required
  - `expected_value` string, nullable, required
  - `state` string, required
  - `cadence_seconds` integer, required
  - `window_hours` number, required
  - `price_usd` string, required
  - `created_at` string, required
  - `expires_at` string, required
  - `results_expire_at` string, required
  - `poll_url` string, required

## Other responses

- `402`: Payment required — retry with an x402 payment header.
- `422`: Validation Error

---

[API](https://skmtc.dev/dnsdoctor/apis/dns-doctor-api.md) · [All operations](https://skmtc.dev/dnsdoctor/apis/dns-doctor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dnsdoctor/apis/dns-doctor-api/revisions/1d0114806e76?raw)