PingQL — Documentation

Overview

PingQL is a developer-friendly uptime monitoring API. Monitors are defined with a URL, an interval, and an optional query that determines what "up" means for your service.

Base URL: https://api.pingql.com

Authentication

All API requests require an account key passed as a Bearer token:

http

Authorization: Bearer <your-64-char-hex-key>

Create an account at /dashboard or via the API. Keys are 64-character hex strings (256-bit). Shown once at registration — store them securely.

Account

Register

POST/account/register

Create a new account. Email is optional — used only for account recovery.

json — request body

{ "email": "you@example.com" }  // optional

json — response

{ "key": "5bf5311b56d09254c8a1f0e3...", "email_registered": true }

Update Email

POST/account/email

Set or update the recovery email for an existing account.

json — request body

{ "email": "you@example.com" }

Monitors

List

GET/monitors/

Returns all monitors for the authenticated account.

Create

POST/monitors/

json — request body

{
  "name":       "My API",
  "url":        "https://api.example.com/health",
  "interval_s": 60,        // check every 60 seconds (min: 10)
  "query":      { ... }   // optional — see Query Language below
}

Get

GET/monitors/:id

Returns a monitor including its most recent ping results.

Update

PATCH/monitors/:id

Update any field. All fields are optional.

Delete

DELETE/monitors/:id

Toggle

POST/monitors/:id/toggle

Enable or disable a monitor without deleting it.

Ping History

GET/monitors/:id/pings?limit=100

Returns recent ping results for a monitor. Max 1000.

Query Language — Fields

A PingQL query is a JSON object evaluated against each ping. If it returns true, the monitor is up. Default (no query): up when status < 400.

Field	Type	Description
status	number	HTTP status code
body	string	Full response body as text
headers.name	string	Response header, e.g. `headers.content-type`
$responseTime	number	Request latency in milliseconds
$certExpiry	number	Days until SSL certificate expires
$json	object	JSONPath expression against response body
$select	object	CSS selector against response HTML

Query Language — Operators

Operator	Description	Types
$eq	Equal to	any
$ne	Not equal to	any
$gt / $gte	Greater than / or equal	number
$lt / $lte	Less than / or equal	number
$contains	String contains substring	string
$startsWith	String starts with	string
$endsWith	String ends with	string
$regex	Matches regular expression	string
$exists	Field is present and non-null	any
$in	Value is in array	any

json

// simple equality shorthand
{ "status": 200 }

// operator form
{ "status": { "$lt": 400 } }
{ "body": { "$contains": "healthy" } }
{ "headers.content-type": { "$contains": "application/json" } }

$json — JSONPath

Extract and compare a value from a JSON response body. The key is a dot-notation path starting with $.

json

// response body: { "status": "ok", "db": { "connections": 12 } }

{ "$json": { "$.status": { "$eq": "ok" } } }
{ "$json": { "$.db.connections": { "$lt": 100 } } }

$select — CSS Selector

Extract text content from an HTML response using a CSS selector. Useful for monitoring public pages without an API.

json

// matches if <h1> text is exactly "Example Domain"
{ "$select": { "h1": { "$eq": "Example Domain" } } }

// matches if status badge contains "operational"
{ "$select": { ".status-badge": { "$contains": "operational" } } }

Logical Operators

json

// $and — all conditions must match
{ "$and": [{ "status": 200 }, { "body": { "$contains": "ok" } }] }

// $or — any condition must match
{ "$or": [{ "status": 200 }, { "status": 204 }] }

// $not — invert a condition
{ "$not": { "status": 500 } }

$consider

By default, matching conditions mean the monitor is up. Set "$consider": "down" to flip this — if the conditions match, the monitor is down.

json

// down if response time exceeds 2 seconds
{ "$consider": "down", "$responseTime": { "$gt": 2000 } }

// down if cert expires in less than 7 days
{ "$consider": "down", "$certExpiry": { "$lt": 7 } }

// down if any of these match
{
  "$consider": "down",
  "$or": [
    { "status": { "$gte": 500 } },
    { "$responseTime": { "$gt": 5000 } }
  ]
}

Examples

Basic health endpoint

json

{ "status": 200, "body": { "$contains": "healthy" } }

JSON API response shape

json

{
  "$and": [
    { "status": 200 },
    { "$json": { "$.ok": { "$eq": true } } }
  ]
}

Performance monitor (mark down if slow)

json

{ "$consider": "down", "$responseTime": { "$gt": 1000 } }

Cert expiry alert

json

{ "$consider": "down", "$certExpiry": { "$lt": 14 } }

Status page (HTML)

json

{ "$select": { ".status-indicator": { "$eq": "All systems operational" } } }