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

3.3 KiB

Raw Blame History

title, description

title	description
Quickstart	From zero to a working monitor in under five minutes.

Quickstart

This walkthrough creates a Checkmate user, logs in, provisions an HTTP monitor, and reads its checks — all via the API.

It assumes you have a Checkmate instance running and reachable. Substitute https://your-checkmate-host with your actual host throughout.

1. Register the first user

If your instance is fresh, the first user becomes a superadmin:

curl -X POST https://your-checkmate-host/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "password": "Hunter2!Hunter2!",
    "role": ["superadmin"],
    "teamId": ""
  }'

The response includes a JWT and a freshly-created teamId. Save both.

If a superadmin already exists, skip to step 2 and use existing credentials.

2. Log in

If you already have an account:

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

TEAM_ID=$(curl -s -X POST https://your-checkmate-host/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"Hunter2!Hunter2!"}' \
  | jq -r '.data.user.teamId')

echo "Token: $TOKEN"
echo "Team:  $TEAM_ID"

3. Create a monitor

This creates an HTTP monitor that probes example.com every 60 seconds:

curl -X POST https://your-checkmate-host/api/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"example.com\",
    \"type\": \"http\",
    \"url\": \"https://example.com\",
    \"interval\": 60000,
    \"teamId\": \"$TEAM_ID\",
    \"isActive\": true
  }"

A successful response returns the new monitor including its _id.

4. List your team's monitors

curl https://your-checkmate-host/api/v1/monitors/team/$TEAM_ID \
  -H "Authorization: Bearer $TOKEN"

You should see the monitor you just created. Within a minute, the background worker will have run a few checks against it.

5. Read recent checks

Replace <MONITOR_ID> with the _id from step 3:

curl "https://your-checkmate-host/api/v1/checks/<MONITOR_ID>?limit=10" \
  -H "Authorization: Bearer $TOKEN"

You'll see an array of check results — status code, response time, timestamp, region (if applicable).

6. Pause and delete the monitor

Pause:

curl -X PATCH https://your-checkmate-host/api/v1/monitors/<MONITOR_ID> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'

Delete:

curl -X DELETE https://your-checkmate-host/api/v1/monitors/<MONITOR_ID> \
  -H "Authorization: Bearer $TOKEN"

What's next

Set up notifications — POST /notifications to wire email / Slack / Discord / webhook channels, then attach them to monitors.
Build a status page — POST /status-page to publish your monitors publicly.
Schedule maintenance — POST /maintenance-window to silence checks during planned downtime.
Browse the full API reference — see every endpoint with request/response schemas.

See the reference for the complete list of endpoints.

3.3 KiB Raw Blame History