v1.0.0 · REST · JSON · OpenAPI 3.1

MonitorAH API

Programmatic access to MonitorAH monitors, events, notifications, and status pages. All endpoints require either a session cookie (dashboard) or a Bearer API key with the relevant scope.

Base URL
https://monitorah.com
Raw spec
/api/v1/openapi.json

Authentication

Every /api/v1/* endpoint accepts two auth methods. The dashboard sends the session cookie; programmatic clients send a Bearer API key.

Bearer token
Authorization: Bearer mon_live_…

Create a key from Developer → API keys. Keys are scoped (e.g. monitors:write) and can be revoked instantly.

Session cookie
Cookie: session=…

Set automatically after magic-link sign in. Sessions have all scopes.

Errors

Every error response follows the same envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Request body must be valid JSON",
    "details": { ... }
  }
}
400
Bad request
401
Unauthorized
402
Plan limit
403
Forbidden
404
Not found
409
Conflict
422
Validation
429
Rate limited

Pagination

List endpoints use cursor pagination. Pass ?cursor=<opaque>&limit=50 (max 100). The response includes meta.nextCursor when more results are available.

GET /api/v1/monitors?limit=50

{
  "data": [ /* monitors */ ],
  "meta": { "nextCursor": "eyJpZCI6IjQyIn0", "hasMore": true }
}

Analytics

get /api/v1/analytics/{monitorId}

Monitor analytics

Requires session cookie OR Bearer API key.

Parameters

  • monitorId (path) *
  • from (query)
  • to (query)

Responses

  • 200 Analytics
Example curl 
curl https://monitorah.com/api/v1/analytics/{monitorId} \
  -X GET \
  -H "Authorization: Bearer mon_live_…"

API keys

get /api/v1/api-keys

List API keys

Requires session cookie OR Bearer API key.

Responses

  • 200 Keys
Example curl 
curl https://monitorah.com/api/v1/api-keys \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/api-keys

Create API key

Requires session cookie OR Bearer API key.

Responses

  • 201 Created (full key returned once)
Example curl 
curl https://monitorah.com/api/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
delete /api/v1/api-keys/{id}

Revoke API key

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 204 Revoked
Example curl 
curl https://monitorah.com/api/v1/api-keys/{id} \
  -X DELETE \
  -H "Authorization: Bearer mon_live_…"

Events

get /api/v1/events

List downtime events

Requires session cookie OR Bearer API key.

Responses

  • 200 Events
Example curl 
curl https://monitorah.com/api/v1/events \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
get /api/v1/events/{id}

Get event

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Event
Example curl 
curl https://monitorah.com/api/v1/events/{id} \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
patch /api/v1/events/{id}

Resolve event

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Resolved
Example curl 
curl https://monitorah.com/api/v1/events/{id} \
  -X PATCH \
  -H "Authorization: Bearer mon_live_…"

heartbeat

get /api/v1/heartbeat/{token}

Send heartbeat by public token (anonymous)

Public endpoint — no authentication required.

Parameters

  • token (path) *

Responses

  • 200 Acknowledged
Example curl 
curl https://monitorah.com/api/v1/heartbeat/{token} \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/heartbeat/{token}

Send heartbeat by public token (anonymous)

Public endpoint — no authentication required.

Parameters

  • token (path) *

Responses

  • 200 Acknowledged
Example curl 
curl https://monitorah.com/api/v1/heartbeat/{token} \
  -X POST \
  -H "Authorization: Bearer mon_live_…"

Monitors

get /api/v1/monitors

List monitors

Requires session cookie OR Bearer API key.

Parameters

  • cursor (query)
  • limit (query)
  • type (query)
  • status (query)
  • isActive (query)

Responses

  • 200 Monitors
Example curl 
curl https://monitorah.com/api/v1/monitors \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/monitors

Create monitor

Requires session cookie OR Bearer API key.

Request body

MonitorCreate

Responses

  • 201 Created
  • 402 Plan monitor limit reached
  • 422 Validation error
Example curl 
curl https://monitorah.com/api/v1/monitors \
  -X POST \
  -H "Authorization: Bearer mon_live_…" \
  -H "Content-Type: application/json" \
  -d '{"...":"..."}'
get /api/v1/monitors/{id}

Get monitor

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Monitor
Example curl 
curl https://monitorah.com/api/v1/monitors/{id} \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
patch /api/v1/monitors/{id}

Update monitor

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Updated
Example curl 
curl https://monitorah.com/api/v1/monitors/{id} \
  -X PATCH \
  -H "Authorization: Bearer mon_live_…"
delete /api/v1/monitors/{id}

Delete monitor

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 204 Deleted
Example curl 
curl https://monitorah.com/api/v1/monitors/{id} \
  -X DELETE \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/monitors/{id}/check

Run on-demand check

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Check result
Example curl 
curl https://monitorah.com/api/v1/monitors/{id}/check \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/monitors/{id}/heartbeat

Send heartbeat (dead-man switch)

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Acknowledged
Example curl 
curl https://monitorah.com/api/v1/monitors/{id}/heartbeat \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
get /api/v1/monitors/{id}/logs

List check logs

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Logs
Example curl 
curl https://monitorah.com/api/v1/monitors/{id}/logs \
  -X GET \
  -H "Authorization: Bearer mon_live_…"

Notification channels

get /api/v1/notification-channels

List channels

Requires session cookie OR Bearer API key.

Responses

  • 200 Channels
Example curl 
curl https://monitorah.com/api/v1/notification-channels \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/notification-channels

Create channel

Requires session cookie OR Bearer API key.

Responses

  • 201 Created
Example curl 
curl https://monitorah.com/api/v1/notification-channels \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
patch /api/v1/notification-channels/{id}

Update channel

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Updated
Example curl 
curl https://monitorah.com/api/v1/notification-channels/{id} \
  -X PATCH \
  -H "Authorization: Bearer mon_live_…"
delete /api/v1/notification-channels/{id}

Delete channel

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 204 Deleted
Example curl 
curl https://monitorah.com/api/v1/notification-channels/{id} \
  -X DELETE \
  -H "Authorization: Bearer mon_live_…"

Notification rules

get /api/v1/notification-rules

List rules

Requires session cookie OR Bearer API key.

Responses

  • 200 Rules
Example curl 
curl https://monitorah.com/api/v1/notification-rules \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/notification-rules

Create rule

Requires session cookie OR Bearer API key.

Responses

  • 201 Created
Example curl 
curl https://monitorah.com/api/v1/notification-rules \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
delete /api/v1/notification-rules/{id}

Delete rule

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 204 Deleted
Example curl 
curl https://monitorah.com/api/v1/notification-rules/{id} \
  -X DELETE \
  -H "Authorization: Bearer mon_live_…"

Status pages

get /api/v1/status-pages

List status pages

Requires session cookie OR Bearer API key.

Responses

  • 200 Status pages
Example curl 
curl https://monitorah.com/api/v1/status-pages \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/status-pages

Create status page

Requires session cookie OR Bearer API key.

Responses

  • 201 Created
Example curl 
curl https://monitorah.com/api/v1/status-pages \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
get /api/v1/status-pages/{id}

Get status page

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Status page
Example curl 
curl https://monitorah.com/api/v1/status-pages/{id} \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
patch /api/v1/status-pages/{id}

Update status page

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 200 Updated
Example curl 
curl https://monitorah.com/api/v1/status-pages/{id} \
  -X PATCH \
  -H "Authorization: Bearer mon_live_…"
delete /api/v1/status-pages/{id}

Delete status page

Requires session cookie OR Bearer API key.

Parameters

  • id (path) *

Responses

  • 204 Deleted
Example curl 
curl https://monitorah.com/api/v1/status-pages/{id} \
  -X DELETE \
  -H "Authorization: Bearer mon_live_…"
get /api/v1/status-pages/{slug}/public

Public status page data (no auth)

Public endpoint — no authentication required.

Parameters

  • slug (path) *

Responses

  • 200 Public status page
Example curl 
curl https://monitorah.com/api/v1/status-pages/{slug}/public \
  -X GET \
  -H "Authorization: Bearer mon_live_…"

Subscription

get /api/v1/subscription

Get current subscription

Requires session cookie OR Bearer API key.

Responses

  • 200 OK
Example curl 
curl https://monitorah.com/api/v1/subscription \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/subscription

Cancel subscription at period end

Requires session cookie OR Bearer API key.

Responses

  • 200 Scheduled cancellation
Example curl 
curl https://monitorah.com/api/v1/subscription \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/subscription/checkout

Create Stripe checkout session

Requires session cookie OR Bearer API key.

Responses

  • 200 Checkout URL
Example curl 
curl https://monitorah.com/api/v1/subscription/checkout \
  -X POST \
  -H "Authorization: Bearer mon_live_…"
post /api/v1/subscription/portal

Create Stripe billing portal session

Requires session cookie OR Bearer API key.

Responses

  • 200 Portal URL
Example curl 
curl https://monitorah.com/api/v1/subscription/portal \
  -X POST \
  -H "Authorization: Bearer mon_live_…"

Health

get /api/v1/health

Health check (anonymous, minimal)

Public endpoint — no authentication required.

Responses

  • 200 Status only — { status: "ok" | "degraded" }
Example curl 
curl https://monitorah.com/api/v1/health \
  -X GET \
  -H "Authorization: Bearer mon_live_…"
get /api/v1/health/details

Detailed health (admin only)

Requires session cookie OR Bearer API key.

Responses

  • 200 Full health info: dbConnected, cronRunning, version, serverTime
  • 403 Not an admin
Example curl 
curl https://monitorah.com/api/v1/health/details \
  -X GET \
  -H "Authorization: Bearer mon_live_…"

Schemas

Error 
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "details": {}
      }
    }
  }
}
PageMeta 
{
  "type": "object",
  "properties": {
    "nextCursor": {
      "type": "string",
      "nullable": true
    },
    "hasMore": {
      "type": "boolean"
    }
  }
}
MonitorType 
{
  "type": "string",
  "enum": [
    "PING",
    "HTTP",
    "SSL",
    "DNS",
    "PORT",
    "WHOIS",
    "BLACKLIST",
    "HEARTBEAT"
  ]
}
MonitorStatus 
{
  "type": "string",
  "enum": [
    "UP",
    "DOWN",
    "UNKNOWN"
  ]
}
Monitor 
{
  "type": "object",
  "required": [
    "id",
    "name",
    "type",
    "target",
    "checkInterval",
    "isActive",
    "lastStatus"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "type": {
      "$ref": "#/components/schemas/MonitorType"
    },
    "target": {
      "type": "string"
    },
    "config": {
      "type": "object",
      "additionalProperties": true
    },
    "checkInterval": {
      "type": "integer",
      "minimum": 15
    },
    "isActive": {
      "type": "boolean"
    },
    "lastCheckAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "lastStatus": {
      "$ref": "#/components/schemas/MonitorStatus"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
MonitorCreate 
{
  "type": "object",
  "required": [
    "name",
    "type",
    "target"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 120
    },
    "type": {
      "$ref": "#/components/schemas/MonitorType"
    },
    "target": {
      "type": "string"
    },
    "config": {
      "type": "object",
      "additionalProperties": true
    },
    "checkInterval": {
      "type": "integer",
      "minimum": 15,
      "maximum": 86400
    },
    "isActive": {
      "type": "boolean"
    }
  }
}
DowntimeEvent 
{
  "type": "object",
  "required": [
    "id",
    "monitorId",
    "startedAt",
    "resolved"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "monitorId": {
      "type": "string"
    },
    "startedAt": {
      "type": "string",
      "format": "date-time"
    },
    "endedAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "durationSeconds": {
      "type": "integer",
      "nullable": true
    },
    "resolved": {
      "type": "boolean"
    }
  }
}