API for agents

Machine-readable: /openapi.json · /llms.txt. All endpoints accept and return UTF-8 JSON.

1. Create a monitor

curl -i -X POST https://pagechange.online/api/v1/monitors \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <random 24-128 chars; keep secret>' \
  -d '{"url":"https://shop.example.com/item","what_to_watch":"price",
       "change_type":"PRICE_BELOW","threshold":450,
       "frequency":"12h","max_checks":28,"preferred_output_language":"de"}'
# → 402 with x402 v2 requirements (PAYMENT-REQUIRED header)
# Resend the same request with PAYMENT-SIGNATURE: <base64 x402 payload>
# → 201 with monitor_id, baseline, checks, next_check_at

The baseline is taken before the payment settles. If the page cannot be fetched, the target is not found, or the page only renders with JavaScript, you get 422 and the payment is never settled. Reusing the Idempotency-Key returns the same monitor.

2. Read status and events

curl https://pagechange.online/api/v1/monitors/<id> -H 'Authorization: Bearer <Idempotency-Key>'
curl 'https://pagechange.online/api/v1/monitors/<id>/events?after=0&limit=50' -H 'Authorization: Bearer <Idempotency-Key>'

An event includes previous_state, current_state, normalized_diff, evidence_before/after (original text), condition_met, source_language, a summary in the output language, confidence and remaining_checks. The baseline is never an event.

3. Control

POST /api/v1/monitors/<id>/cancel   # stop; remaining checks kept
POST /api/v1/monitors/<id>/resume   # restart with remaining checks (free)
POST /api/v1/monitors/<id>/fund     # {"checks":10} + x402 payment

change_type

ANY_MEANINGFUL_CHANGE · TEXT_CHANGE · TEXT_APPEARS · TEXT_DISAPPEARS · SECTION_CHANGE · PRICE_CHANGE · PRICE_BELOW · PRICE_ABOVE · AVAILABILITY_CHANGE · BECOMES_AVAILABLE · BECOMES_UNAVAILABLE · STRUCTURED_FIELD_CHANGE · ITEM_ADDED · ITEM_REMOVED

Pin ambiguous targets with selector (CSS), currency (ISO 4217) or field (JSON-LD path such as offers.price). Events of type TARGET_MISSING / TARGET_RESTORED report when the watched element disappears or returns.

Webhooks (optional)

Pass webhook_url (public HTTPS). The creation response includes webhook_secret. Each POST carries PageChange-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + raw body). Up to 3 attempts (immediately, +1 min, +10 min); delivery status is recorded on the event. Polling the events endpoint always works.

Health

GET /api/v1/health checks configuration only and never wakes the database. ?ready=1 adds a cached database check.