Docs / HTTP API

HTTP API

Manage checks and read results. Base URL https://api.pingform.org/v2. Bearer tokens, JSON in and out.

Authentication

curl https://api.pingform.org/v2/checks \
  -H "Authorization: Bearer pft_live_7Qm2x..."

Tokens are workspace-scoped and carry one of three roles: read, write, admin. Rate limit is 600 requests per minute per token; the X-RateLimit-Remaining header is authoritative.

Endpoints

Method	Path	Description
GET	/checks	List checks, paginated by cursor
POST	/checks	Create a check
PATCH	/checks/{id}	Update interval, expectations, vantage points
DELETE	/checks/{id}	Delete a check and its schedule
GET	/checks/{id}/results	Raw samples for a time range
GET	/checks/{id}/uptime	Rolled-up availability
GET	/agents	Agents, last seen, transport in use
GET	/vantage-points	Managed and private vantage points
POST	/exports	Request a bulk export job

Create a check

POST /v2/checks
{
  "id": "api-edge",
  "type": "http",
  "target": "https://api.example.com/healthz",
  "interval": "30s",
  "timeout": "5s",
  "from": ["eu-central", "us-east"],
  "expect": { "status": 200, "body_contains": "ok", "tls_min_days": 14 },
  "alerts": { "after": 2, "notify": ["pd:primary"] }
}

Read results

GET /v2/checks/api-edge/results?from=2026-10-11T00:00:00Z&to=2026-10-12T00:00:00Z&vantage=eu-central

{
  "cursor": null,
  "samples": [
    { "t": "2026-10-11T00:00:03Z", "vantage": "eu-central", "result": "ok",
      "duration_ms": 84, "dns_ms": 7, "connect_ms": 21, "tls_ms": 33, "ttfb_ms": 71 },
    { "t": "2026-10-11T00:00:33Z", "vantage": "eu-central", "result": "ok",
      "duration_ms": 79, "dns_ms": 1, "connect_ms": 19, "tls_ms": 31, "ttfb_ms": 68 }
  ]
}

Errors

Code	Error	Meaning
400	invalid_expectation	Expectation not valid for this check type
402	quota_exceeded	Plan check limit reached
404	unknown_vantage	Vantage point not available on this plan
409	duplicate_id	Check ID already used in this workspace
429	rate_limited	Retry after `Retry-After` seconds