TRX/Checkmate

0 Fork 0

Files

T

gorkem-bwl 9aa2594df7 docs(api): add public API documentation site (Astro Starlight)

## Changes
- Add narrative API documentation in docs/api-content/ (introduction,
  quickstart, authentication, conventions, errors, rate limiting)
- Scaffold Astro Starlight site at docs/api/ that consumes prose from
  the sibling api-content folder and auto-generates the endpoint
  reference from server/openapi.json via starlight-openapi
- Wire Checkmate brand color (#13715B) into Starlight via custom CSS
- Add vercel.json so the docs site deploys cleanly as an Astro project
  with root directory docs/api/

## Benefits
- Public API docs ready to publish at checkmate.so/docs
- Endpoint reference stays in sync with the OpenAPI spec automatically
- Zero third-party SaaS dependency: site is fully self-hosted on Vercel
- Contributors edit plain markdown; no Astro knowledge needed for prose

2026-05-22 10:21:10 -04:00

2.8 KiB

Raw Blame History

title, description

title	description
Introduction	Use the Checkmate REST API to manage monitors, incidents, status pages, notifications, and users programmatically.

Checkmate API

Checkmate exposes a REST API that mirrors everything the web UI can do. Use it to provision monitors from infrastructure-as-code, build internal dashboards, automate incident workflows, or integrate Checkmate into your existing alerting stack.

The web UI you log in to is itself just a client of this same API.

Base URL

https://<your-checkmate-host>/api/v1

Replace <your-checkmate-host> with the domain where you deployed Checkmate. For local development:

http://localhost:52345/api/v1

All endpoints are relative to this base. Every path on this page is shown without the /api/v1 prefix — prepend it when making requests.

API stability

The API is at version v1 and is considered stable. Breaking changes will only ship under a new major version (/api/v2).

What you can do

Resource	What it covers
`monitors`	Create, update, pause, and delete monitors of any type (HTTP, Ping, Port, DNS, Docker, PageSpeed, gRPC, WebSocket, Game, Hardware)
`checks`	Read individual check results and aggregated stats
`incidents`	List, filter, and resolve downtime incidents
`notifications`	Manage notification channels (email, Slack, Discord, webhooks)
`status-page`	Configure public status pages
`maintenance-window`	Schedule maintenance windows so checks don't fire incidents
`geo-checks`	Multi-region check results
`auth`	Register, log in, manage users
`invite`	Invite teammates
`logs`	Audit and operational logs
`settings`	Tune global Checkmate settings
`queue`	Inspect the background-job queue (operational)
`diagnostic`	Health and system info

What you'll need

A running Checkmate instance you administer.
A user account on that instance.
A JWT obtained by calling POST /auth/login — see Authentication.

There is no separate "API key" concept in Checkmate. The same JWT that authenticates the web UI authenticates every API call.

Response shape

Every endpoint returns the same envelope:

{
  "success": true,
  "msg": "OK",
  "data": { /* endpoint-specific payload */ }
}

See Conventions for the full contract and Errors for failure shapes.

Quick example

# 1. Log in to get a token
TOKEN=$(curl -s -X POST https://your-checkmate-host/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"YourPass1!"}' \
  | jq -r '.data.token')

# 2. List your team's monitors
curl https://your-checkmate-host/api/v1/monitors/team/<teamId> \
  -H "Authorization: Bearer $TOKEN"

Next: Authentication.

2.8 KiB Raw Blame History