Public API

1. 1

   Create a key

   Open Dashboard → API & webhooks. Give the key a clear name, choose read-only or full access, and set an expiry.

2. 2

   Copy it once

   The key starts with moon_ and is shown only once. Store it in a secrets manager, never in browser code or source control.

3. 3

   Make a request

   curl https://www.moonitor.dev/api/v1/monitors \
     -H "X-API-Key: moon_YOUR_KEY"

The complete OpenAPI 3.1 contract, request builder, schemas, examples and responses live in the Scalar API reference. The raw document is available at /openapi.json.

• Read-only keys can list and fetch every resource, but cannot mutate anything.
• Full-access keys can read and write all documented resources. Revoke or replace a key at any time from the dashboard.
• Keys are scoped to one organization. A key can never select another tenant through a query or request body.
• Each key allows 120 requests per 60 seconds. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, plus the structured RateLimit and RateLimit-Policy fields, so a client can pace itself rather than discovering the limit by hitting it. A 429 adds Retry-After.

List endpoints accept limit (1–100, default 25) and offset (default 0). Every list response includes the exact values and total count:

{
  "data": [],
  "pagination": { "limit": 25, "offset": 0, "total": 0 }
}

Add an Idempotency-Key header to POST, PATCH and DELETE requests that your client may retry. Moonitor binds the key to the method, path and validated body, then replays the same successful response for 24 hours instead of running the mutation twice.

curl -X POST https://www.moonitor.dev/api/v1/monitors \
  -H "X-API-Key: moon_YOUR_KEY" \
  -H "Idempotency-Key: deploy-2026-07-15-monitor-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Website","type":"HTTP","url":"https://example.com"}'

A replay includes Idempotency-Replayed: true. Reusing the key for different input returns 409 idempotency_conflict.

Errors always use one envelope. Keep the requestId when contacting support; it is also returned in the X-Request-ID header.

{
  "error": {
    "code": "validation_error",
    "message": "The request is invalid",
    "requestId": "…",
    "details": [{ "path": "url", "message": "url is required for HTTP monitors" }]
  }
}

Branch on error.code, never on error.message: the codes below are a fixed set, published as an enum in the Error schema of the OpenAPI document, while the messages are written for humans and may be reworded.

The version is in the path. Everything documented here is /api/v1, and we treat that prefix as a promise.

• Additive changes happen within a version. New endpoints, new optional request fields and new response fields can appear at any time — so your client must ignore response fields it does not recognise rather than failing on them.
• Breaking changes ship as a new version. Removing a field, renaming one, tightening validation or changing a status code means /api/v2. /api/v1 keeps working.
• Removal is announced in the responses themselves. A deprecated operation returns a Deprecation header (RFC 9745) saying when it was deprecated, a Sunset header (RFC 8594) with the earliest date it may stop working, and a Link with rel="deprecation" pointing at what to use instead. It is also marked deprecated in the OpenAPI document.
• You get at least 180 days. That is the minimum between the first Deprecation header and the shutdown date, and we email account holders with active API keys as well.

Nothing is currently deprecated.