gorkem-bwl
9aa2594df7
## 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
85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
---
|
|
title: Introduction
|
|
description: 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
|
|
|
|
1. A running Checkmate instance you administer.
|
|
2. A user account on that instance.
|
|
3. A JWT obtained by calling `POST /auth/login` — see [Authentication](/api/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:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"msg": "OK",
|
|
"data": { /* endpoint-specific payload */ }
|
|
}
|
|
```
|
|
|
|
See [Conventions](/api/conventions) for the full contract and [Errors](/api/errors) for failure shapes.
|
|
|
|
## Quick example
|
|
|
|
```bash
|
|
# 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](/api/authentication).
|