REST API Documentation

The UpMonitor REST API allows you to programmatically run website audits, manage monitors, and retrieve historical data.

Base URL

https://upmonitor.io/api/v1
Copy

Authentication

All API requests require a Bearer token in the Authorization header. You can generate an API key in your Developer Settings.

Authorization: Bearer YOUR_API_KEY
Copy

Endpoints

Audits

Run a Stateless Check

POST /run-check Trigger an instant audit. Not saved to history.

• Body: { "url": string, "checkers": string[] }

Monitors

List Monitors

GET /monitors

Create Monitor

POST /monitors

• Body: { "url": string, "name": string, "interval": number, "regions": string[], "checkers": string[], "headers": object }

Get Monitor

GET /monitors/:id

• Query: history=N (0-100)

Update Monitor

PATCH /monitors/:id

• Body: { "name": string, "interval": number, "regions": string[], "checkers": string[], "headers": object, "enabled": boolean }

Delete Monitor

DELETE /monitors/:id

Trigger Check Now

POST /monitors/:id/check

Get Active Incident

GET /monitors/:id/incident

Incidents

List Incidents

GET /incidents

• Query: status=open|closed, acknowledged=true|false|any, monitorId=string, limit=number

Get Incident

GET /incidents/:id

Acknowledge Incident

POST /incidents/:id/acknowledge

Resolve Incident

POST /incidents/:id/resolve

Rate Limits

Two limits run in parallel on every authenticated API call:

Per-minute rate limit (all authenticated tiers): 20 requests / minute / user. Exceeding this returns 429 Too Many Requests.

Monthly quota (per subscription tier):

• Free: 100 requests / month
• PRO: 10,000 requests / month
• Agency: Unlimited

Exceeding the monthly quota returns 403 quota_exceeded until the next month rolls over.

Anonymous (unauthenticated) calls to public audit endpoints are capped at 5 requests / hour per IP.

Every authenticated response includes two headers you can use for client-side throttling:

• X-RateLimit-Remaining: minute-window requests remaining.
• X-Quota-Remaining: month-window requests remaining (-1 if your tier is unlimited).

Error Codes

• 400 Bad Request: Missing required parameters.
• 401 Unauthorized: Missing or invalid API key.
• 403 Forbidden with body { "error": "quota_exceeded" }: Monthly quota exhausted - upgrade or wait for reset.
• 429 Too Many Requests: Per-minute rate limit exceeded - back off and retry.