API Documentation
The PingBase API is a REST API that lets you manage monitors, retrieve check results, and configure your status page programmatically.
Base URL
https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev
All endpoints accept and return application/json. All authenticated requests require a Bearer token in the Authorization header.
Authentication
PingBase uses JWT Bearer tokens. Get a token by calling POST /api/auth/login. Tokens expire after 7 days.
Authorization: Bearer <your-token>
Requests without a valid token to authenticated endpoints return 401 Unauthorized.
Errors
All errors return a JSON body with an error field.
{ "error": "Invalid email or password (min 8 chars)" }
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — missing or invalid token |
| 403 | Forbidden — plan limit reached |
| 404 | Resource not found |
| 409 | Conflict — e.g. email already registered |
| 500 | Internal server error |
Auth
/api/auth/register
Create a new account. Returns a JWT token and creates a default status page.
{
"email": "you@example.com",
"password": "minlength8"
}
{
"token": "eyJ...",
"plan": "free",
"statusPageSlug": "you-a1b2c3"
}
curl -X POST https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"mypassword"}'
/api/auth/login
Log in to an existing account. Returns a fresh JWT token valid for 7 days.
{
"email": "you@example.com",
"password": "mypassword"
}
{
"token": "eyJ...",
"plan": "free"
}
curl -X POST https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"mypassword"}'
User
/api/me
Requires auth
Returns your account details including current plan.
{
"id": "uuid",
"email": "you@example.com",
"plan": "free",
"created_at": 1712345678
}
curl https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/me \ -H "Authorization: Bearer $TOKEN"
Plan values: free · pro · business · past_due
Monitors
/api/monitors
Requires auth
Returns all monitors for your account, ordered by creation date.
[
{
"id": "uuid",
"user_id": "uuid",
"name": "My API",
"url": "https://api.example.com/health",
"interval_minutes": 5,
"is_active": 1,
"status": "up",
"last_checked_at": 1712345678,
"created_at": 1712345000
}
]
curl https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/monitors \ -H "Authorization: Bearer $TOKEN"
/api/monitors
Requires auth
Create a new monitor. The check interval is set automatically based on your plan (5 min on Free, 1 min on Pro/Business). Returns 403 if your plan limit is reached.
{
"name": "My API",
"url": "https://api.example.com/health"
}
{
"id": "uuid",
"user_id": "uuid",
"name": "My API",
"url": "https://api.example.com/health",
"interval_minutes": 5,
"is_active": 1,
"status": "pending",
"last_checked_at": null,
"created_at": 1712345678
}
curl -X POST https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/monitors \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My API","url":"https://api.example.com/health"}'
Plan limits
| Free | 1 monitor · 5-min checks |
| Pro | 10 monitors · 1-min checks |
| Business | 50 monitors · 1-min checks |
/api/monitors/:id
Requires auth
Delete a monitor. Returns 404 if the monitor doesn't exist or belongs to another user.
{ "success": true }
curl -X DELETE \ https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/monitors/MONITOR_ID \ -H "Authorization: Bearer $TOKEN"
Check Results
/api/monitors/:id
Requires auth
Returns the last 100 check results for a monitor, newest first.
[
{
"id": "uuid",
"monitor_id": "uuid",
"status": "up",
"response_time_ms": 142,
"status_code": 200,
"error": null,
"checked_at": 1712345678
},
{
"id": "uuid",
"monitor_id": "uuid",
"status": "down",
"response_time_ms": null,
"status_code": null,
"error": "Connection timeout",
"checked_at": 1712345378
}
]
curl https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/monitors/MONITOR_ID \ -H "Authorization: Bearer $TOKEN"
status — "up" or "down"
response_time_ms — null when the check failed to connect
status_code — the HTTP status code returned, or null on connection failure
checked_at — Unix timestamp (seconds)
Status Page
/api/status-page
Requires auth
Returns your status page configuration including its public slug.
{
"id": "uuid",
"user_id": "uuid",
"slug": "you-a1b2c3",
"title": "My Status Page",
"description": null,
"created_at": 1712345000
}
curl https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/status-page \ -H "Authorization: Bearer $TOKEN"
The public URL for this status page is https://pingba.se/status/{slug}
/api/status-page/monitors
Requires auth
Add a monitor to your public status page. Monitors are shown in the order they were added. Adding a monitor that's already on the page is a no-op.
{
"monitor_id": "uuid"
}
{ "success": true }
curl -X POST \
https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/status-page/monitors \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"monitor_id":"MONITOR_ID"}'
/api/status/:slug
Public
Returns the public status page data for a given slug. No authentication required. This is the endpoint that powers the public status page at pingba.se/status/:slug.
{
"title": "Acme Corp Status",
"description": null,
"overall_status": "operational",
"monitors": [
{
"id": "uuid",
"name": "Main Website",
"url": "https://acme.com",
"status": "up",
"last_checked_at": 1712345678,
"uptime_pct": "99.98",
"incidents": []
}
]
}
curl https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/status/your-slug
overall_status — "operational" (all up) · "degraded" (any down) · "unknown" (no checks yet)
uptime_pct — 90-day uptime percentage as a string, or null if no checks recorded yet
incidents — up to 5 recent incidents with started_at, resolved_at, and is_resolved
Health
/api/health
Public
Returns worker status. Use this to verify the API is reachable.
{ "ok": true, "ts": 1712345678000 }
curl https://pingbase-worker.YOUR_SUBDOMAIN.workers.dev/api/health