371 lines
20 KiB
HTML
371 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>PingQL — Documentation</title>
|
|
<script src="https://cdn.tailwindcss.com"></script>
|
|
<style>
|
|
body { font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', ui-monospace, monospace; background: #0a0a0a; }
|
|
pre, code { font-family: inherit; }
|
|
|
|
/* Sidebar nav */
|
|
.nav-link { display: block; padding: 0.3rem 0.75rem; font-size: 0.8rem; color: #6b7280; border-left: 2px solid transparent; transition: all 0.1s; }
|
|
.nav-link:hover { color: #d1d5db; border-left-color: #374151; }
|
|
.nav-link.active { color: #93c5fd; border-left-color: #3b82f6; }
|
|
.nav-section { font-size: 0.7rem; font-weight: 600; color: #374151; text-transform: uppercase; letter-spacing: 0.08em; padding: 0.75rem 0.75rem 0.25rem; margin-top: 0.5rem; }
|
|
|
|
/* Content */
|
|
.section { padding-top: 3rem; padding-bottom: 1rem; border-top: 1px solid #111827; margin-top: 2rem; }
|
|
.section:first-child { border-top: none; margin-top: 0; padding-top: 0; }
|
|
h2 { font-size: 1.2rem; font-weight: 700; color: #f9fafb; margin-bottom: 0.5rem; }
|
|
h3 { font-size: 0.85rem; font-weight: 600; color: #9ca3af; text-transform: uppercase; letter-spacing: 0.06em; margin: 1.5rem 0 0.5rem; }
|
|
p { font-size: 0.875rem; color: #6b7280; line-height: 1.7; margin-bottom: 0.75rem; }
|
|
p a { color: #93c5fd; }
|
|
p a:hover { color: #bfdbfe; }
|
|
|
|
/* Code blocks */
|
|
.cb { background: #0f172a; border: 1px solid #1e293b; border-radius: 0.5rem; overflow: hidden; margin: 0.75rem 0 1.25rem; }
|
|
.cb-header { background: #0a1628; border-bottom: 1px solid #1e293b; padding: 0.4rem 0.85rem; display: flex; align-items: center; justify-content: space-between; }
|
|
.cb-lang { font-size: 0.7rem; color: #475569; }
|
|
.cb-copy { font-size: 0.7rem; color: #3b82f6; cursor: pointer; }
|
|
.cb-copy:hover { color: #93c5fd; }
|
|
.cb pre { padding: 0.85rem; font-size: 0.78rem; line-height: 1.65; color: #e2e8f0; overflow-x: auto; margin: 0; }
|
|
|
|
/* Syntax */
|
|
.k { color: #c084fc; } /* key */
|
|
.s { color: #34d399; } /* string */
|
|
.n { color: #f59e0b; } /* number */
|
|
.o { color: #60a5fa; } /* operator */
|
|
.c { color: #334155; } /* comment */
|
|
|
|
/* Tables */
|
|
table { width: 100%; border-collapse: collapse; font-size: 0.8rem; margin: 0.5rem 0 1.25rem; }
|
|
th { text-align: left; color: #4b5563; font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.05em; padding: 0.4rem 0.75rem; border-bottom: 1px solid #111827; }
|
|
td { color: #6b7280; padding: 0.45rem 0.75rem; border-bottom: 1px solid #0d1117; vertical-align: top; }
|
|
td:first-child { color: #93c5fd; white-space: nowrap; font-size: 0.78rem; }
|
|
td code { background: #1e293b; color: #94a3b8; padding: 0.1em 0.35em; border-radius: 0.2rem; font-size: 0.75rem; }
|
|
|
|
/* Endpoint blocks */
|
|
.endpoint { display: flex; align-items: baseline; gap: 0.75rem; margin-bottom: 0.5rem; }
|
|
.method { font-size: 0.7rem; font-weight: 700; padding: 0.15rem 0.45rem; border-radius: 0.2rem; }
|
|
.method.get { background: #052e16; color: #4ade80; }
|
|
.method.post { background: #172554; color: #93c5fd; }
|
|
.method.patch { background: #1c1917; color: #fb923c; }
|
|
.method.delete { background: #3f1215; color: #f87171; }
|
|
.path { color: #e2e8f0; font-size: 0.875rem; }
|
|
.endpoint-desc { font-size: 0.8rem; color: #4b5563; margin-bottom: 1rem; }
|
|
</style>
|
|
</head>
|
|
<body class="bg-[#0a0a0a] text-gray-100 min-h-screen">
|
|
|
|
<!-- Top bar -->
|
|
<div class="border-b border-gray-900 px-6 py-3 flex items-center justify-between">
|
|
<a href="/" class="text-lg font-bold">Ping<span class="text-blue-400">QL</span> <span class="text-gray-600 font-normal text-sm">docs</span></a>
|
|
<a href="/dashboard" class="text-sm text-gray-600 hover:text-gray-400 transition-colors">Dashboard →</a>
|
|
</div>
|
|
|
|
<div class="flex max-w-6xl mx-auto">
|
|
|
|
<!-- Sidebar -->
|
|
<aside class="w-52 shrink-0 sticky top-0 h-screen overflow-y-auto py-6 hidden md:block">
|
|
<div class="nav-section">Getting Started</div>
|
|
<a href="#overview" class="nav-link">Overview</a>
|
|
<a href="#auth" class="nav-link">Authentication</a>
|
|
|
|
<div class="nav-section">API Reference</div>
|
|
<a href="#account" class="nav-link">Account</a>
|
|
<a href="#monitors" class="nav-link">Monitors</a>
|
|
|
|
<div class="nav-section">Query Language</div>
|
|
<a href="#ql-fields" class="nav-link">Fields</a>
|
|
<a href="#ql-operators" class="nav-link">Operators</a>
|
|
<a href="#ql-json" class="nav-link">$json</a>
|
|
<a href="#ql-select" class="nav-link">$select</a>
|
|
<a href="#ql-logical" class="nav-link">Logical</a>
|
|
<a href="#ql-consider" class="nav-link">$consider</a>
|
|
<a href="#ql-examples" class="nav-link">Examples</a>
|
|
</aside>
|
|
|
|
<!-- Main content -->
|
|
<main class="flex-1 px-10 py-8 max-w-3xl">
|
|
|
|
<!-- Overview -->
|
|
<div id="overview" class="section">
|
|
<h2>Overview</h2>
|
|
<p>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.</p>
|
|
<p>Base URL: <code style="color:#93c5fd;background:#0f172a;padding:0.15em 0.4em;border-radius:0.25rem;font-size:0.8rem">https://api.pingql.com</code></p>
|
|
</div>
|
|
|
|
<!-- Auth -->
|
|
<div id="auth" class="section">
|
|
<h2>Authentication</h2>
|
|
<p>All API requests require an account key passed as a Bearer token:</p>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">http</span></div>
|
|
<pre>Authorization: Bearer <your-64-char-hex-key></pre>
|
|
</div>
|
|
<p>Create an account at <a href="/dashboard">/dashboard</a> or via the API. Keys are 64-character hex strings (256-bit). Shown once at registration — store them securely.</p>
|
|
</div>
|
|
|
|
<!-- Account -->
|
|
<div id="account" class="section">
|
|
<h2>Account</h2>
|
|
|
|
<h3>Register</h3>
|
|
<div class="endpoint"><span class="method post">POST</span><span class="path">/account/register</span></div>
|
|
<p class="endpoint-desc">Create a new account. Email is optional — used only for account recovery.</p>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json — request body</span></div>
|
|
<pre>{ <span class="k">"email"</span>: <span class="s">"you@example.com"</span> } <span class="c">// optional</span></pre>
|
|
</div>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json — response</span></div>
|
|
<pre>{ <span class="k">"key"</span>: <span class="s">"5bf5311b56d09254c8a1f0e3..."</span>, <span class="k">"email_registered"</span>: <span class="n">true</span> }</pre>
|
|
</div>
|
|
|
|
<h3>Update Email</h3>
|
|
<div class="endpoint"><span class="method post">POST</span><span class="path">/account/email</span></div>
|
|
<p class="endpoint-desc">Set or update the recovery email for an existing account.</p>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json — request body</span></div>
|
|
<pre>{ <span class="k">"email"</span>: <span class="s">"you@example.com"</span> }</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Monitors -->
|
|
<div id="monitors" class="section">
|
|
<h2>Monitors</h2>
|
|
|
|
<h3>List</h3>
|
|
<div class="endpoint"><span class="method get">GET</span><span class="path">/monitors/</span></div>
|
|
<p class="endpoint-desc">Returns all monitors for the authenticated account.</p>
|
|
|
|
<h3>Create</h3>
|
|
<div class="endpoint"><span class="method post">POST</span><span class="path">/monitors/</span></div>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json — request body</span></div>
|
|
<pre>{
|
|
<span class="k">"name"</span>: <span class="s">"My API"</span>,
|
|
<span class="k">"url"</span>: <span class="s">"https://api.example.com/health"</span>,
|
|
<span class="k">"interval_s"</span>: <span class="n">60</span>, <span class="c">// check every 60 seconds (min: 10)</span>
|
|
<span class="k">"query"</span>: { ... } <span class="c">// optional — see Query Language below</span>
|
|
}</pre>
|
|
</div>
|
|
|
|
<h3>Get</h3>
|
|
<div class="endpoint"><span class="method get">GET</span><span class="path">/monitors/:id</span></div>
|
|
<p class="endpoint-desc">Returns a monitor including its most recent ping results.</p>
|
|
|
|
<h3>Update</h3>
|
|
<div class="endpoint"><span class="method patch">PATCH</span><span class="path">/monitors/:id</span></div>
|
|
<p class="endpoint-desc">Update any field. All fields are optional.</p>
|
|
|
|
<h3>Delete</h3>
|
|
<div class="endpoint"><span class="method delete">DELETE</span><span class="path">/monitors/:id</span></div>
|
|
|
|
<h3>Toggle</h3>
|
|
<div class="endpoint"><span class="method post">POST</span><span class="path">/monitors/:id/toggle</span></div>
|
|
<p class="endpoint-desc">Enable or disable a monitor without deleting it.</p>
|
|
|
|
<h3>Ping History</h3>
|
|
<div class="endpoint"><span class="method get">GET</span><span class="path">/monitors/:id/pings?limit=100</span></div>
|
|
<p class="endpoint-desc">Returns recent ping results for a monitor. Max 1000.</p>
|
|
</div>
|
|
|
|
<!-- QL Fields -->
|
|
<div id="ql-fields" class="section">
|
|
<h2>Query Language — Fields</h2>
|
|
<p>A PingQL query is a JSON object evaluated against each ping. If it returns <code style="color:#4ade80;background:#052e16;padding:0.1em 0.35em;border-radius:0.2rem;font-size:0.78rem">true</code>, the monitor is <strong style="color:#4ade80">up</strong>. Default (no query): up when status < 400.</p>
|
|
<table>
|
|
<thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>status</td><td>number</td><td>HTTP status code</td></tr>
|
|
<tr><td>body</td><td>string</td><td>Full response body as text</td></tr>
|
|
<tr><td>headers.<em>name</em></td><td>string</td><td>Response header, e.g. <code>headers.content-type</code></td></tr>
|
|
<tr><td>$responseTime</td><td>number</td><td>Request latency in milliseconds</td></tr>
|
|
<tr><td>$certExpiry</td><td>number</td><td>Days until SSL certificate expires</td></tr>
|
|
<tr><td>$json</td><td>object</td><td>JSONPath expression against response body</td></tr>
|
|
<tr><td>$select</td><td>object</td><td>CSS selector against response HTML</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<!-- QL Operators -->
|
|
<div id="ql-operators" class="section">
|
|
<h2>Query Language — Operators</h2>
|
|
<table>
|
|
<thead><tr><th>Operator</th><th>Description</th><th>Types</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>$eq</td><td>Equal to</td><td>any</td></tr>
|
|
<tr><td>$ne</td><td>Not equal to</td><td>any</td></tr>
|
|
<tr><td>$gt / $gte</td><td>Greater than / or equal</td><td>number</td></tr>
|
|
<tr><td>$lt / $lte</td><td>Less than / or equal</td><td>number</td></tr>
|
|
<tr><td>$contains</td><td>String contains substring</td><td>string</td></tr>
|
|
<tr><td>$startsWith</td><td>String starts with</td><td>string</td></tr>
|
|
<tr><td>$endsWith</td><td>String ends with</td><td>string</td></tr>
|
|
<tr><td>$regex</td><td>Matches regular expression</td><td>string</td></tr>
|
|
<tr><td>$exists</td><td>Field is present and non-null</td><td>any</td></tr>
|
|
<tr><td>$in</td><td>Value is in array</td><td>any</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre><span class="c">// simple equality shorthand</span>
|
|
{ <span class="k">"status"</span>: <span class="n">200</span> }
|
|
|
|
<span class="c">// operator form</span>
|
|
{ <span class="k">"status"</span>: { <span class="o">"$lt"</span>: <span class="n">400</span> } }
|
|
{ <span class="k">"body"</span>: { <span class="o">"$contains"</span>: <span class="s">"healthy"</span> } }
|
|
{ <span class="k">"headers.content-type"</span>: { <span class="o">"$contains"</span>: <span class="s">"application/json"</span> } }</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- $json -->
|
|
<div id="ql-json" class="section">
|
|
<h2>$json — JSONPath</h2>
|
|
<p>Extract and compare a value from a JSON response body. The key is a dot-notation path starting with <code style="color:#93c5fd;background:#0f172a;padding:0.1em 0.35em;border-radius:0.2rem;font-size:0.78rem">$.</code></p>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre><span class="c">// response body: { "status": "ok", "db": { "connections": 12 } }</span>
|
|
|
|
{ <span class="o">"$json"</span>: { <span class="s">"$.status"</span>: { <span class="o">"$eq"</span>: <span class="s">"ok"</span> } } }
|
|
{ <span class="o">"$json"</span>: { <span class="s">"$.db.connections"</span>: { <span class="o">"$lt"</span>: <span class="n">100</span> } } }</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- $select -->
|
|
<div id="ql-select" class="section">
|
|
<h2>$select — CSS Selector</h2>
|
|
<p>Extract text content from an HTML response using a CSS selector. Useful for monitoring public pages without an API.</p>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre><span class="c">// matches if <h1> text is exactly "Example Domain"</span>
|
|
{ <span class="o">"$select"</span>: { <span class="s">"h1"</span>: { <span class="o">"$eq"</span>: <span class="s">"Example Domain"</span> } } }
|
|
|
|
<span class="c">// matches if status badge contains "operational"</span>
|
|
{ <span class="o">"$select"</span>: { <span class="s">".status-badge"</span>: { <span class="o">"$contains"</span>: <span class="s">"operational"</span> } } }</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Logical -->
|
|
<div id="ql-logical" class="section">
|
|
<h2>Logical Operators</h2>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre><span class="c">// $and — all conditions must match</span>
|
|
{ <span class="o">"$and"</span>: [{ <span class="k">"status"</span>: <span class="n">200</span> }, { <span class="k">"body"</span>: { <span class="o">"$contains"</span>: <span class="s">"ok"</span> } }] }
|
|
|
|
<span class="c">// $or — any condition must match</span>
|
|
{ <span class="o">"$or"</span>: [{ <span class="k">"status"</span>: <span class="n">200</span> }, { <span class="k">"status"</span>: <span class="n">204</span> }] }
|
|
|
|
<span class="c">// $not — invert a condition</span>
|
|
{ <span class="o">"$not"</span>: { <span class="k">"status"</span>: <span class="n">500</span> } }</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- $consider -->
|
|
<div id="ql-consider" class="section">
|
|
<h2>$consider</h2>
|
|
<p>By default, matching conditions mean the monitor is <strong style="color:#4ade80">up</strong>. Set <code style="color:#93c5fd;background:#0f172a;padding:0.1em 0.35em;border-radius:0.2rem;font-size:0.78rem">"$consider": "down"</code> to flip this — if the conditions match, the monitor is <strong style="color:#f87171">down</strong>.</p>
|
|
<div class="cb">
|
|
<div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre><span class="c">// down if response time exceeds 2 seconds</span>
|
|
{ <span class="o">"$consider"</span>: <span class="s">"down"</span>, <span class="k">"$responseTime"</span>: { <span class="o">"$gt"</span>: <span class="n">2000</span> } }
|
|
|
|
<span class="c">// down if cert expires in less than 7 days</span>
|
|
{ <span class="o">"$consider"</span>: <span class="s">"down"</span>, <span class="k">"$certExpiry"</span>: { <span class="o">"$lt"</span>: <span class="n">7</span> } }
|
|
|
|
<span class="c">// down if any of these match</span>
|
|
{
|
|
<span class="o">"$consider"</span>: <span class="s">"down"</span>,
|
|
<span class="o">"$or"</span>: [
|
|
{ <span class="k">"status"</span>: { <span class="o">"$gte"</span>: <span class="n">500</span> } },
|
|
{ <span class="k">"$responseTime"</span>: { <span class="o">"$gt"</span>: <span class="n">5000</span> } }
|
|
]
|
|
}</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Examples -->
|
|
<div id="ql-examples" class="section">
|
|
<h2>Examples</h2>
|
|
|
|
<h3>Basic health endpoint</h3>
|
|
<div class="cb"><div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre>{ <span class="k">"status"</span>: <span class="n">200</span>, <span class="k">"body"</span>: { <span class="o">"$contains"</span>: <span class="s">"healthy"</span> } }</pre></div>
|
|
|
|
<h3>JSON API response shape</h3>
|
|
<div class="cb"><div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre>{
|
|
<span class="o">"$and"</span>: [
|
|
{ <span class="k">"status"</span>: <span class="n">200</span> },
|
|
{ <span class="o">"$json"</span>: { <span class="s">"$.ok"</span>: { <span class="o">"$eq"</span>: <span class="n">true</span> } } }
|
|
]
|
|
}</pre></div>
|
|
|
|
<h3>Performance monitor (mark down if slow)</h3>
|
|
<div class="cb"><div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre>{ <span class="o">"$consider"</span>: <span class="s">"down"</span>, <span class="k">"$responseTime"</span>: { <span class="o">"$gt"</span>: <span class="n">1000</span> } }</pre></div>
|
|
|
|
<h3>Cert expiry alert</h3>
|
|
<div class="cb"><div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre>{ <span class="o">"$consider"</span>: <span class="s">"down"</span>, <span class="k">"$certExpiry"</span>: { <span class="o">"$lt"</span>: <span class="n">14</span> } }</pre></div>
|
|
|
|
<h3>Status page (HTML)</h3>
|
|
<div class="cb"><div class="cb-header"><span class="cb-lang">json</span></div>
|
|
<pre>{ <span class="o">"$select"</span>: { <span class="s">".status-indicator"</span>: { <span class="o">"$eq"</span>: <span class="s">"All systems operational"</span> } } }</pre></div>
|
|
</div>
|
|
|
|
<div class="mt-12 pt-6 border-t border-gray-900 text-sm text-gray-600">
|
|
PingQL · <a href="/dashboard" class="hover:text-gray-400 transition-colors">Dashboard</a>
|
|
</div>
|
|
|
|
</main>
|
|
</div>
|
|
|
|
<script>
|
|
// Highlight active nav link on scroll
|
|
const sections = document.querySelectorAll('[id]');
|
|
const navLinks = document.querySelectorAll('.nav-link');
|
|
const observer = new IntersectionObserver((entries) => {
|
|
entries.forEach(entry => {
|
|
if (entry.isIntersecting) {
|
|
navLinks.forEach(l => l.classList.remove('active'));
|
|
const link = document.querySelector(`.nav-link[href="#${entry.target.id}"]`);
|
|
if (link) link.classList.add('active');
|
|
}
|
|
});
|
|
}, { rootMargin: '-20% 0px -70% 0px' });
|
|
sections.forEach(s => observer.observe(s));
|
|
|
|
// Copy buttons
|
|
document.querySelectorAll('.cb').forEach(cb => {
|
|
const btn = cb.querySelector('.cb-copy');
|
|
if (!btn) return;
|
|
btn.addEventListener('click', () => {
|
|
const text = cb.querySelector('pre').innerText;
|
|
navigator.clipboard.writeText(text);
|
|
btn.textContent = 'Copied!';
|
|
setTimeout(() => btn.textContent = 'Copy', 1500);
|
|
});
|
|
});
|
|
// Add copy buttons to all codeblocks
|
|
document.querySelectorAll('.cb-header').forEach(h => {
|
|
if (!h.querySelector('.cb-copy')) {
|
|
const btn = document.createElement('button');
|
|
btn.className = 'cb-copy';
|
|
btn.textContent = 'Copy';
|
|
h.appendChild(btn);
|
|
btn.addEventListener('click', () => {
|
|
const text = h.nextElementSibling.innerText;
|
|
navigator.clipboard.writeText(text);
|
|
btn.textContent = 'Copied!';
|
|
setTimeout(() => btn.textContent = 'Copy', 1500);
|
|
});
|
|
}
|
|
});
|
|
</script>
|
|
</body>
|
|
</html>
|