Enori API Documentation

The Enori API lets you manage monitors, incidents, alerts, status pages, and more programmatically. All endpoints use REST conventions with JSON request and response bodies.

Base URL: https://api.enori.io

Quick Start

Get monitoring set up in three steps.

1. Get Your API Key

Navigate to the API Keys tab in your dashboard and create a new key. Choose scopes based on what you need:

There is no * / "full access" scope — the API rejects it with a 400. Grant the smallest set the integration needs; a key can hold any combination of the 19 above.

2. Make Your First Request

curl -H "X-API-Key: YOUR_API_KEY" https://api.enori.io/api/monitors

3. Set Up Alerts

Create a webhook alert channel to receive real-time notifications when monitors go down or recover:

curl -X POST https://api.enori.io/api/alert-channels \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "type": "Webhook",
    "webhookUrl": "https://your-server.com/webhook"
  }'

Authentication

All API requests require an API key passed in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://api.enori.io/api/monitors

API keys are scoped — choose the minimum permissions needed. Keys can be created and managed on the API Keys tab in Settings or via the /api/keys endpoint.

Never share your API key. Treat it like a password. If compromised, revoke it immediately from the dashboard and create a new one.

Managing API Keys

Create a new API key. The full key is returned only once in the response — store it securely.

{
  "name": "CI/CD Pipeline",
  "scopes": ["monitors:read", "monitors:write"]
}

List all API keys (key values are masked).

Revoke and delete an API key.

Rate Limits

Rate limits protect the API from abuse. Limits are applied per API key.

Corrected 2026-07-25: this table previously advertised a 200 / minute read tier and a 10 / hour create-monitor limit. Neither existed — there is no separate read tier, and creating a monitor is 30/minute.

When rate limited, the API returns HTTP 429 Too Many Requests with these headers:

About Remaining and Reset. X-RateLimit-Limit is exact — it is the real permit count of the policy governing that endpoint. The other two are good-faith estimates: limiter state is per-server-instance and is not exposed for direct reading, so Remaining can read higher than your true remaining budget, and Reset reports a window boundary rather than the instant your particular window replenishes. Use them for pacing, not for precise budgeting. If you are actually rate limited, Retry-After on the 429 is authoritative — honour that value.

Pagination

List endpoints accept limit and offset. Both are optional — omit them and you get the whole result set, exactly as before pagination existed, so no existing integration changes.

Every paged response carries the same four fields:

{
  "items": [ ... ],
  "totalCount": 137,
  "limit": 50,
  "offset": 100,
  "hasMore": false
}

totalCount is the size of the whole filtered set, not of this page — use it to size a progress bar or decide how many requests you need. Loop on hasMore rather than comparing counts yourself. When you do not page, limit is omitted and hasMore is false.

Available on GET /api/monitors and GET /api/incidents.

API Stability

• Additive changes ship without notice. New fields on a response, new optional query

parameters, and new enum values can appear at any time. Parse defensively: ignore fields you do not recognise, and do not treat an unknown enum value as an error.

• Breaking changes are announced first. Removing a field, renaming one, or changing the meaning

of an existing value is announced by email to account owners at least 30 days ahead, and the old behaviour keeps working through that window.

• Deprecations are visible in the response. A deprecated endpoint returns a

Deprecation header with the date it stops working and a Link header pointing at what to use instead.

• No version is silently retired. Nothing that works today stops working without the notice

above.

Monitors

List Monitors

Query parameters:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.enori.io/api/monitors?type=Website"

Response:

{
  "items": [
    {
      "id": "mon_abc123",
      "name": "Production API",
      "type": "Website",
      "url": "https://api.example.com",
      "status": "Up",
      "uptimePercentage": 99.95,
      "lastCheckedAt": "2026-03-24T10:30:00Z",
      "intervalSeconds": 60
    }
  ],
  "totalCount": 1
}

Get Monitor

Returns full monitor details including configuration and current state.

Create Monitor

{
  "name": "Production API",
  "type": "Website",
  "url": "https://api.example.com",
  "intervalSeconds": 60,
  "timeoutSeconds": 30,
  "httpMethod": "GET",
  "expectedStatusCode": 200,
  "failureThreshold": 2,
  "alertOnDown": true,
  "alertOnRecovered": true,
  "alertChannelIds": ["ch_abc123"],
  "regions": ["UsEast", "EuWest"],
  "tags": ["production", "api"]
}

Monitor types:

Update Monitor

Send the full monitor configuration. Fields not included will be reset to defaults.

Upsert by Name

Idempotent — creates if not exists, updates if exists. Always returns 200. Ideal for infrastructure-as-code and Terraform workflows. The URL name takes precedence over the body name.

Delete Monitor

Permanently deletes the monitor and all associated data (check results, incidents, alerts).

Pause and Resume

Pausing stops checks and alerts. Resuming triggers an immediate check.

Trigger Immediate Check

Triggers an on-demand check outside the regular interval. Rate limited to 5 per minute.

Three limits apply, and they return different 429 bodies — branch on the body, not the status:

Call GET /api/monitors/check-limits for the current usedToday / remainingToday. The same daily cap applies to the check_now MCP tool.

usedToday counts check results already RECORDED, and a triggered check records its row when the executor runs it — so remainingToday is a lower bound on what you have left, not an exact figure while checks are still in flight (the limits block returned by the trigger call itself does not include the check it just queued).

Check Results

Returns recent check results with response time, status code, and error details.

Statistics

Incidents

List Incidents

Returns { items: [...], totalCount: N }.

This endpoint does not accept date filters. An earlier version of this page listed from and to; they were never implemented, so a request carrying them silently returned unfiltered data. To narrow by date, filter startedAt client-side. (GET /api/incidents/recent takes a count, not a date range, so it is not a substitute.)

Recent and Active Incidents

Get Incident

Create Manual Incident

Acknowledge

Stops escalation timers for this incident.

Resolve

Add Update

Post a status update to the incident timeline.

Incident Statistics

Incidents by Monitor

Alerts

List Alert Records

Alert Channels

Manage where alerts are delivered.

Supported channel types: Email, Slack, Discord, Teams, Webhook

Alert Rules

Configure which monitors trigger which channels.

Job Monitoring

Enori's Job monitor type tracks cron jobs and scheduled tasks using heartbeat pings.

How It Works

1. Create a Job monitor with a cron expression defining your expected schedule
2. Get the unique ping token from the monitor details
3. Add ping calls to your job script — Enori alerts you if pings stop arriving

Ping Endpoints

These endpoints require no authentication — just the unique token.

Report job success (heartbeat).

Report job failure.

Report job start (enables runtime tracking).

All three endpoints accept GET, HEAD, and POST methods.

Example: Shell Cron Job

#!/bin/bash
# Notify Enori the job has started
curl -fsS -m 10 https://api.enori.io/ping/YOUR_TOKEN/start

# Run the actual job
/usr/bin/backup-database.sh

# Report success or failure based on exit code
if [ $? -eq 0 ]; then
  curl -fsS -m 10 https://api.enori.io/ping/YOUR_TOKEN
else
  curl -fsS -m 10 https://api.enori.io/ping/YOUR_TOKEN/fail
fi

Example: GitHub Actions

name: Nightly Build
on:
  schedule:
    - cron: '0 2 * * *'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsS https://api.enori.io/ping/${{ secrets.ENORI_TOKEN }}/start
      - run: npm ci && npm run build
      - run: curl -fsS https://api.enori.io/ping/${{ secrets.ENORI_TOKEN }}
        if: success()
      - run: curl -fsS https://api.enori.io/ping/${{ secrets.ENORI_TOKEN }}/fail
        if: failure()

Example: Python Script

import requests
import sys

TOKEN = "YOUR_TOKEN"
BASE = "https://api.enori.io/ping"

# Signal start
requests.get(f"{BASE}/{TOKEN}/start", timeout=10)

try:
    # Your job logic here
    run_etl_pipeline()
    requests.get(f"{BASE}/{TOKEN}", timeout=10)
except Exception:
    requests.get(f"{BASE}/{TOKEN}/fail", timeout=10)
    sys.exit(1)

Ping History

Returns the heartbeat history for a Job monitor including execution times, status, and messages.

Status Pages

Authenticated Endpoints

Public Endpoints (No Auth)

View a public status page — returns component statuses, uptime data, and incident history.

Subscribe to status page updates via email.

Webhooks

When you create a Webhook alert channel, Enori will POST JSON payloads to your URL whenever monitor events occur.

Payload Format

{
  "event": "monitor.down",
  "timestamp": "2026-03-24T14:30:00Z",
  "monitor": { "id": "mon_abc123", "name": "Production API" },
  "alert": {
    "type": "Down",
    "title": "Production API is down",
    "message": "HTTP 503 Service Unavailable"
  },
  "episode": {
    "id": "ep_def456",
    "cause": "availability",
    "kind": "opened",
    "severity": "critical",
    "openedAt": "2026-03-24T14:30:00Z",
    "lastFiredAt": "2026-03-24T14:30:00Z",
    "resolvedAt": null,
    "actions": {
      "acknowledge": "https://api.enori.io/api/alert-actions/ack?...",
      "resolve": "https://api.enori.io/api/alert-actions/resolve?..."
    }
  }
}

timestamp is top-level, not inside alert. episode is present only for alerts that belong to an episode and is null otherwise; its actions are pre-signed URLs your system can call to acknowledge or resolve without a login.

Event Types

event is either monitor.{type} — the alert type lowercased — or monitor.episode.{kind} for episode-driven alerts.

Treat unknown event names as forward-compatible: new alert types add new values, so match on the prefix rather than on an exhaustive list.

Security

Verify webhook authenticity by checking:

• The User-Agent header contains Enori-Webhook/1.0
• The request arrives within seconds of the event timestamp
• Your endpoint URL uses HTTPS

Retry Policy

Failed webhook deliveries (non-2xx response or timeout) are retried:

• 30 seconds after the first failure, then every 120 seconds
• Up to 3 attempts per delivery
• After the final attempt the delivery is marked failed and visible in your alert history

Badges

Embed a live uptime, status or response-time badge for one monitor in your README, documentation, or dashboard. Three endpoints, all anonymous, all returning SVG.

For the product-side walkthrough — where the switch lives, what the snippet builder does, troubleshooting — see the Status Badges guide.

Turn badges on first

Badges are off by default and must be enabled per monitor. Until you do, all three endpoints return a gray unknown badge — that is the most common reason a badge looks stuck.

The fastest way is the product: open the monitor, expand Status badges, flip the switch, and copy the ready-made Markdown or HTML from the same panel. It fills in the monitor id for you and previews the exact badge your readers will see.

Through the API:

curl -X PUT https://api.enori.io/api/monitors/mon_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgesEnabled": true}'

badgesEnabled is also accepted on POST /api/monitors and is returned on every monitor response, so you can check the current state with GET /api/monitors/{monitorId}. Omitting it on PUT leaves it unchanged.

This publishes the monitor. While it is on, anyone who has a badge URL can read that monitor's uptime percentage, current status and average response time without signing in — that is what makes the badge work in a public README. Nothing else is exposed: not the monitored URL, not the monitor's name, not the check history, not your other monitors. Turning it back off takes effect on our side immediately — the publication check is never cached, so the very next request gets the gray badge. But every badge response carries Cache-Control: public, max-age=300, so an image already delivered can keep rendering for up to about five minutes in a reader's browser, a docs CDN, or an image proxy. Plan for that tail.

Uptime Badge

Renders the uptime percentage over the window, to two decimals (99.87%). Settled results only, maintenance excluded from both sides of the ratio — the same number GET /api/monitors/{id}/range-stats returns for the same range. Colour bands: >= 99.9 green, >= 99 olive, >= 95 amber, >= 90 orange, below that red.

Status Badge

Renders the monitor's current status as one word. The full value domain:

A paused monitor still serves its badges if badgesEnabled is true — the status badge reads paused and the uptime badge keeps reporting the window it can measure. Pausing is not unpublishing; badgesEnabled: false is.

Response Time Badge

Renders the average response time over the window, in whole milliseconds (183 ms). Same population as the uptime badge and as range-stats' avgResponseMs: successful checks with a measured response time, outside maintenance.

Always rendered in one colour — a "good" response time is workload-dependent, so Enori does not publish a performance verdict you never configured.

Domain and Cron Job monitors have no response time, so this badge always reads no data for them. Neither type makes a timed request of its own: a Domain check reads stored registry data, and a Cron Job monitor receives a heartbeat rather than calling out. (This is the same reason a latency SLO is refused on those two types.)

Parameters

period is refused, style is coerced — deliberately. A wrong style costs you the wrong corners; a wrong period would publish a different number under your own label. So an unrecognised period renders a red invalid period badge (still HTTP 200 — a 4xx would show up in a README as a broken-image glyph) rather than quietly falling back to 30 days. ?period=24H is fine; ?period=30 and ?period=1y are not. Sending period= empty is the same as omitting it.

What label accepts. Characters outside the set above are silently removed, not rejected — the badge still renders, just without them. Letters and digits from any alphabet are kept, so café, приложение and 日本 come through intact. Punctuation and symbols do not:

The removal happens first and the 30-character limit is applied afterwards. If nothing survives, the label falls back to that endpoint's own default — uptime, status or response respectively. The Status badges panel in the app previews this for you as you type.

Embed in Markdown

[![Uptime](https://api.enori.io/api/badges/mon_abc123/uptime.svg)](https://app.enori.io/dashboard/monitors/mon_abc123)
[![Status](https://api.enori.io/api/badges/mon_abc123/status.svg?style=flat-square)](https://app.enori.io/dashboard/monitors/mon_abc123)
[![Response](https://api.enori.io/api/badges/mon_abc123/response-time.svg?style=for-the-badge)](https://app.enori.io/dashboard/monitors/mon_abc123)

Linking the badge costs nothing extra and lets a reader who sees a red badge click through instead of guessing. A bare !Uptime works too.

Embed in HTML

<a href="https://app.enori.io/dashboard/monitors/mon_abc123">
  <img src="https://api.enori.io/api/badges/mon_abc123/uptime.svg" alt="Uptime" />
</a>

Response contract

Every outcome the badge endpoint itself decides returns HTTP 200 with an SVG — monitor not found, not opted in, bad period, empty window. Failure is expressed in the badge's TEXT, because the response is consumed as an and a 4xx renders as a broken-image glyph. The exceptions come from outside the endpoint: exceeding the rate limit returns 429, and an API-side fault returns a 5xx.

Headers on every response:

Content-Type: image/svg+xml; charset=utf-8
Cache-Control: public, max-age=300
X-Content-Type-Options: nosniff
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox

Badges are cached for 5 minutes on both sides: the uptime and response-time figures are computed at most once per 5 minutes per monitor and window, and the response tells caches the same. The publication check itself is not cached.

Badge requests are rate-limited to 60 requests per minute per IP address.

Why is my badge gray?

A gray badge carries one of two words, and they mean different things.

A gray unknown badge means one of these, in the order worth checking:

1. Badges are not enabled for that monitor — see "Turn badges on first" above. This is by far the

most common cause.

1. The monitor id is wrong or the monitor was deleted. Ids look like mon_ followed by 32

hexadecimal characters; copy it from the Status badges panel rather than retyping it.

1. You switched badges off within the last 5 minutes and are seeing a cached image.
2. On status.svg only: the monitor genuinely has no verdict yet — never checked, or the last

check could not be classified.

Causes 1 and 2 are deliberately indistinguishable on the wire: an opted-out monitor and a nonexistent monitor id return byte-identical responses, so a badge URL cannot be used to discover which monitor ids exist. That also means the badge itself cannot tell you which one applies — check the panel.

A gray no data badge is different and is not an error: the monitor is enabled and running, but the window you asked for contains nothing to measure — a brand-new monitor, or one whose every check in that window fell inside a maintenance window. Widen period or wait for the next check. On response-time.svg it is also permanent for Domain and Cron Job monitors, as described above.

Badges from other services (Shields.io)

If you already use Shields.io and want a badge in its exact house style, point its dynamic/json badge at a public status page's uptime history, which is plain JSON and needs no API key:

https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.enori.io%2Fapi%2Fstatus-pages%2Fpublic%2FYOUR-SLUG%2Fuptime-history&query=%24.overallUptimePct&label=uptime

Colour, style and any prefix/suffix are Shields' own options — consult their documentation for those. On our side, GET /api/status-pages/public/{slug}/uptime-history returns overallUptimePct (uptime across every monitor on the page, weighted by check count) plus a days array. Use overallUptimePct: entries in days carry a placeholder of 100 for days with no recorded checks, flagged by hasData: false, so a badge built on a single day can show a perfect score for a day nobody watched. overallUptimePct is null when the whole window has no checks.

The page must be public and not password-protected. There is no equivalent per-monitor JSON endpoint — a monitor is published through its own badge opt-in or through a status page, and both are choices you make deliberately.

Error Responses

The API uses standard HTTP status codes and returns JSON error bodies.

Status Codes

Error Format

{
  "error": "Monitor limit exceeded",
  "message": "Your Base plan allows 10 monitors. Upgrade to Pro for up to 50.",
  "code": "PLAN_LIMIT_EXCEEDED"
}

Common Errors

Plan Limits

Add-ons (available on any plan):

All plans include a 14-day free trial.

Code Examples

cURL

# List all monitors
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.enori.io/api/monitors

# Create a website monitor
curl -X POST https://api.enori.io/api/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "Website",
    "url": "https://api.example.com/health",
    "intervalSeconds": 60,
    "expectedStatusCode": 200,
    "alertOnDown": true,
    "alertOnRecovered": true
  }'

# Pause a monitor
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  https://api.enori.io/api/monitors/mon_abc123/pause

# Trigger an immediate check
curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  https://api.enori.io/api/monitors/mon_abc123/check

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.enori.io"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Create a monitor
monitor = requests.post(f"{BASE}/api/monitors", headers=HEADERS, json={
    "name": "Staging API",
    "type": "Website",
    "url": "https://staging.example.com",
    "intervalSeconds": 300,
    "expectedStatusCode": 200,
}).json()
print(f"Created monitor: {monitor['id']}")

# List all monitors
data = requests.get(f"{BASE}/api/monitors", headers=HEADERS).json()
for m in data["items"]:
    print(f"  {m['name']}: {m['status']} ({m['uptimePercentage']:.2f}%)")

# Get recent incidents
incidents = requests.get(
    f"{BASE}/api/incidents/recent", headers=HEADERS
).json()
for inc in incidents:
    print(f"  [{inc['status']}] {inc['title']}")

Node.js

const API_KEY = "YOUR_API_KEY";
const BASE = "https://api.enori.io";

async function enori(path, options = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...options,
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  return res.json();
}

// Create a monitor
const monitor = await enori("/api/monitors", {
  method: "POST",
  body: JSON.stringify({
    name: "Checkout Service",
    type: "Website",
    url: "https://checkout.example.com/health",
    intervalSeconds: 60,
  }),
});
console.log(`Created: ${monitor.id}`);

// List all monitors
const { items } = await enori("/api/monitors");
items.forEach((m) => console.log(`${m.name}: ${m.status}`));

GitHub Actions

name: Deploy and Verify Uptime
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build && npm run deploy

      - name: Verify monitors after deploy
        env:
          ENORI_KEY: ${{ secrets.ENORI_API_KEY }}
        run: |
          sleep 30
          RESPONSE=$(curl -s -H "X-API-Key: $ENORI_KEY" \
            "https://api.enori.io/api/monitors?tag=production")
          echo "$RESPONSE" | jq '.items[] | "\(.name): \(.status)"'

          DOWN=$(echo "$RESPONSE" | jq '[.items[] | select(.status == "Down")] | length')
          if [ "$DOWN" -gt 0 ]; then
            echo "::error::$DOWN production monitors are down!"
            exit 1
          fi

Interactive API Explorer

For a complete interactive reference with all endpoints, request/response schemas, and the ability to try requests directly, visit the Scalar API documentation:

Open API Explorer

The OpenAPI 3.0 specification is also available programmatically:

curl https://api.enori.io/openapi/v1.json