Build with it

API

Anything the web app can do, the API can do. JSON in and out, camelCase everywhere, versioned under /v1.

Base URL

https://app.openping.ai/v1

Auth

Send an API key as a bearer token. Make one in the app under API keys; it starts with opk_ and is shown once.

curl https://app.openping.ai/v1/monitors \
  -H "Authorization: Bearer $OPENPING_API_KEY"

A key carries scopes: read, write, incidents and status_pages. write includes read. Give each key only what it needs.

Create a monitor

curl -X POST https://app.openping.ai/v1/monitors \
  -H "Authorization: Bearer $OPENPING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0d4e-web-app" \
  -d '{
    "name": "Web app",
    "type": "http",
    "target": "https://yourapp.com/api/health",
    "intervalSeconds": 180,
    "assertions": [
      { "kind": "status", "value": 200 },
      { "kind": "latency", "value": 1500 }
    ]
  }'

The answer is 201 with { "monitors": [ … ] }. A heartbeat monitor comes back with its heartbeatToken.

Errors

Every error has the same shape, and the message is a sentence you can act on:

{
  "error": {
    "code": "plan_limit",
    "message": "The Free plan checks every 3 minutes at the fastest. Pro checks every 30 seconds.",
    "field": "intervalSeconds"
  }
}

Status	Code	Means
400	`invalid`	Something in the request is wrong; `field` says what
401	`unauthenticated`	No key, or a key we don’t know
403	`forbidden`, `plan_limit`, `not_allowed`	The key lacks the scope, or the plan’s limit is reached
404	`not_found`	No such thing in your organisation
409	`conflict`	It clashes with something that exists
429	`rate_limited`	Slow down; `Retry-After` says for how long
503	`unavailable`	That part is switched off or briefly down

Good to know

Idempotency. Send an Idempotency-Key with any POST that creates something. A repeat within 24 hours returns the first answer instead of making a second one.
Paging. ?limit= (50 by default, 200 at most) and ?before=. The answer carries nextBefore when there is more.
Rate limits come back as X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
Plan limits are enforced by the API: monitor count, fastest interval, regions, status pages and agent runs.

Monitors

Route	Scope	What it does
`GET /v1/monitors`	read	List monitors, with counts by state. Filter with ?service=, ?type= and ?q=
`POST /v1/monitors`	write	Create one monitor, or several with { monitors: [...] }. The first run is queued at once
`GET /v1/monitors/:id`	read	One monitor with its state, last run, uptime and bars
`PATCH /v1/monitors/:id`	write	Change a monitor
`DELETE /v1/monitors/:id`	write	Remove a monitor
`POST /v1/monitors/:id/pause · /resume`	write	Stop and start checking
`POST /v1/monitors/:id/run-now`	write	Run a check now. Returns job ids to poll
`GET /v1/monitors/:id/runs`	read	Past runs, newest first
`POST /v1/monitors/:id/changes/accept`	write	Accept a changed MCP tool list or DNS answer as the new normal

Everything else

Route	Scope	What it does
`POST /v1/try`	none	The no-account check: look at a URL and suggest monitors
`POST /v1/discover`	write	The same look-around, tied to your organisation
`POST /v1/deploy/plan · /apply`	read · write	Monitors as code: show the plan for an openping.yml, then apply it
`POST /v1/deploys`	write	Mark a deploy on the charts and run the service’s monitors at once
`GET /v1/incidents`	read	Incidents. ?state=open, resolved or all
`POST /v1/incidents/:id/ack · /resolve`	incidents	Acknowledge or resolve
`POST /v1/incidents/:id/updates`	incidents	Post a status update
`GET · POST /v1/channels`	read · write	Where alerts go
`POST /v1/channels/test`	write	Send a test alert and see how long it took
`GET · POST /v1/alert-rules`	read · write	Who hears about what, and after how long
`GET · POST /v1/status-pages`	read · status_pages	Status pages; /publish and /unpublish on one
`PUT /v1/secrets/:name`	write	Save a secret. Values can never be read back
`GET · POST /v1/api-keys`	read · write	API keys. The key itself is shown once
`GET /v1/me`	read	Who you are, your plan and your usage

The no-account check

POST /v1/try needs no key. It is the door our home page uses, and the one an AI agent can use to set up monitoring for its person. It is limited to 10 an hour from one address, and an unclaimed check expires after 24 hours.

curl -X POST https://app.openping.ai/v1/try \
  -H "Content-Type: application/json" \
  -d '{ "url": "yourapp.com" }'

The answer has an id, a claimToken and an eventsUrl that streams what is found. Signing in and calling POST /v1/try/:id/claim with the token turns the suggestions into monitors.

Heartbeats

Heartbeat calls need no key; the token in the URL is the credential. See heartbeats.