DocsAPI & apps

REST API

Automate isituprightnow with the REST API — API keys and scopes, the X-Api-Key header, base URL, rate limits, errors and problem codes, monitors, incidents, contacts, maintenance and status pages, with curl examples.

On this page

Everything you do in the dashboard is built on a JSON REST API. With an API key you can create monitors from your deployment pipeline, pause checks during a release, pull uptime into your own reports or open tickets from incidents.

Basics#

Setting	Value
Base URL	`https://api.isituprightnow.com/api/v1`
Authentication	Header `X-Api-Key: <your key>`
Format	JSON with camelCase fields; send `Content-Type: application/json`
Times	ISO 8601 in UTC (`2026-10-03T14:05:12Z`); time zones are IANA names
Money	Integer cents plus an ISO currency (`"amountCents": 900, "currency": "USD"`)
Nulls	Optional fields are always present, with `null` when empty

Try it:

bash

export IIUN_API_KEY="iiun_xxxxxxxx_…"

curl -s https://api.isituprightnow.com/api/v1/monitors \
  -H "X-Api-Key: $IIUN_API_KEY"

API keys#

Create keys in Settings → API keys (owners and admins; API access depends on your plan — see Pricing).

A key looks like iiun_<8 characters>_<40 characters>. The full key is shown once, when you create it; afterwards only its prefix (iiun_<8 characters>) is visible. We store only a hash.
Give each integration its own key with a descriptive name, so you can revoke one without breaking the others. Last used shows whether a key is still in use.
Keep keys out of source code and logs; use your CI's secret store.

Scopes#

Scope	Allows
`read`	`GET` and `HEAD` requests.
`write`	Every method (`POST`, `PUT`, `DELETE`…). Includes `read`.

A read-only key that tries to change something gets 403 with code: "api_key_read_only".

What a key can access#

A key acts on its account with the permissions of an account Admin, except for account, team and billing management: account/*, billing/*, api-keys/*, invitations/*, auth/* and push/* answer 403 with code: "api_key_not_allowed". Monitors, incidents, alert contacts, maintenance windows and status pages are all available.

Pagination#

Lists that can grow take ?page=1&pageSize=50 (pageSize up to 200). They return a plain JSON array and the total in the X-Total-Count response header.

bash

curl -s -D - "https://api.isituprightnow.com/api/v1/incidents?status=all&page=2&pageSize=100" \
  -H "X-Api-Key: $IIUN_API_KEY" -o incidents.json | grep -i x-total-count

Rate limits#

What	Limit
Sign-in, sign-up, password and 2FA endpoints	10 requests per minute per IP address
Public endpoints (status page subscribe / unlock, contact form…)	10 requests per minute per IP address
Contact form	also 5 messages per IP and 3 per sender e-mail per hour
Heartbeat URLs	60 calls per minute per monitor

Requests made with an API key have no fixed quota today, but please keep traffic reasonable (for example, don't poll more often than your check interval). When you hit a limit the API answers 429 with code: "rate_limited" and a Retry-After header (seconds): wait that long before retrying.

Errors#

Errors use the RFC 7807 application/problem+json format, with a stable machine-readable code:

json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "Interval must be between 15 and 86400 seconds.",
  "code": "validation_failed",
  "errors": {
    "intervalSeconds": ["Interval must be between 15 and 86400 seconds."]
  }
}

Use code in your code (the English title and detail may change). Validation problems list every invalid field in errors; plan-limit problems add limit.

Code	Status	Meaning
`validation_failed`	400	Invalid fields; see `errors`.
`bad_request`	400	Malformed request (e.g. invalid JSON).
`unauthorized`	401	Missing or invalid API key.
`forbidden`	403	Not allowed.
`api_key_read_only`	403	The key has no `write` scope.
`api_key_not_allowed`	403	This endpoint can't be used with API keys.
`account_suspended`	403	The account is suspended; contact support.
`not_found`	404	The resource doesn't exist (or belongs to another account).
`conflict`	409	The request conflicts with the current state.
`slug_taken`	409	A status page already uses this slug.
`domain_taken`	409	Another status page uses this custom domain.
`plan_limit`	402	Your plan doesn't allow it. `limit` is `monitors`, `interval`, `statusPages`, `seats`, `regions` or `feature`.
`rate_limited`	429	Too many requests; see `Retry-After`.
`maintenance_mode`	503	The service is in maintenance mode: changes are briefly disabled (reads, checks and alerts continue).
`not_configured`	503	A channel (SMS, voice, Telegram) isn't available yet.
`not_implemented`	501	Not supported yet.
`server_error`	500	Unexpected error on our side; retry later.

Monitors#

Method and path	Description
`GET /monitors?tag=&status=&q=`	List monitors, optionally filtered by tag, status (`up`, `down`, `paused`, `unknown`) or a search text.
`GET /monitors/{id}`	One monitor.
`POST /monitors`	Create a monitor.
`PUT /monitors/{id}`	Update a monitor (same body as create).
`DELETE /monitors/{id}`	Delete a monitor and its history.
`POST /monitors/{id}/pause`, `POST /monitors/{id}/resume`	Pause or resume checks.
`POST /monitors/bulk`	`{ "ids": [...], "action": "pause" \| "resume" \| "delete" }` → `{ "affected": 3 }`
`GET /monitors/{id}/results?hours=24`	Recent check results (up to 168 hours, at most 300 points).
`GET /monitors/{id}/stats`	Uptime for 24 h / 7 / 30 / 90 days, average response times and 90 daily values.
`GET /monitors/{id}/alert-rules`, `PUT /monitors/{id}/alert-rules`	Read or replace the monitor's alert rules.

Create a monitor#

bash

curl -s -X POST https://api.isituprightnow.com/api/v1/monitors \
  -H "X-Api-Key: $IIUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website — homepage",
    "type": "Http",
    "target": "https://www.example.com/",
    "intervalSeconds": 60,
    "timeoutMs": 10000,
    "tags": ["production"],
    "config": {
      "method": "GET",
      "expectedStatusCodes": "200-299",
      "followRedirects": true
    }
  }'

type is one of Http, Keyword, Ping, Port, Heartbeat, Ssl, Domain, Dns, Udp. Omit regions to use the default region; the available region codes are listed in GET /public/config (regions). The config fields of each type are described in Monitors. The response is the monitor:

json

{
  "id": "8b0c7d3e-3f5a-4a49-9a51-2f1f0f4c6a10",
  "name": "Website — homepage",
  "type": "Http",
  "target": "https://www.example.com/",
  "intervalSeconds": 60,
  "timeoutMs": 10000,
  "regions": ["eu-central"],
  "status": "Unknown",
  "paused": false,
  "inMaintenance": false,
  "lastCheckedAt": null,
  "lastResponseMs": null,
  "uptime24h": null,
  "tags": ["production"],
  "config": {
    "method": "GET",
    "headers": {},
    "body": null,
    "expectedStatusCodes": "200-299",
    "followRedirects": true,
    "keyword": null,
    "keywordMode": "contains",
    "caseSensitive": false,
    "slowThresholdMs": null,
    "basicAuthUser": null,
    "basicAuthPassword": { "isSet": false, "hint": null }
  },
  "lastStatusChangeAt": null,
  "expiresAt": null,
  "createdAt": "2026-10-03T14:05:12Z",
  "updatedAt": "2026-10-03T14:05:12Z"
}

Secrets such as basicAuthPassword are never returned, only { "isSet": true|false }. On update, omit a secret (or send null) to keep it and send "" to clear it. For heartbeat monitors, config.heartbeatUrl contains the URL to call.

Pause during a deployment#

bash

curl -s -X POST "https://api.isituprightnow.com/api/v1/monitors/$MONITOR_ID/pause" -H "X-Api-Key: $IIUN_API_KEY"
./deploy.sh
curl -s -X POST "https://api.isituprightnow.com/api/v1/monitors/$MONITOR_ID/resume" -H "X-Api-Key: $IIUN_API_KEY"

Prefer a maintenance window when you know the time in advance: checks continue and the status page shows maintenance.

Uptime for a report#

bash

curl -s "https://api.isituprightnow.com/api/v1/monitors/$MONITOR_ID/stats" -H "X-Api-Key: $IIUN_API_KEY"

json

{
  "uptime": { "h24": 100, "d7": 99.98, "d30": 99.95, "d90": 99.97 },
  "avgResponseMs": { "h24": 182, "d7": 190, "d30": 188 },
  "daily": [{ "date": "2026-10-02", "uptime": 100 }]
}

Uptime values are percentages (0–100); null means there were no checks in that period. daily holds 90 calendar days in the account's time zone.

Incidents#

Method and path	Description
`GET /incidents?status=open\|all&monitorId=`	List incidents (paginated), newest first.
`GET /incidents/{id}`	Details: snapshot of the failing check, timeline and comments.
`POST /incidents/{id}/acknowledge`	Acknowledge; stops reminders.
`POST /incidents/{id}/comments`	`{ "body": "Rolled back release 1.42" }` (plans with incident comments).

bash

curl -s "https://api.isituprightnow.com/api/v1/incidents?status=open" -H "X-Api-Key: $IIUN_API_KEY"

json

[
  {
    "id": "5e1f2a9b-77c4-4d3e-9a0f-6b2d8c1e4f55",
    "monitorId": "8b0c7d3e-3f5a-4a49-9a51-2f1f0f4c6a10",
    "monitorName": "Website — homepage",
    "startedAt": "2026-10-03T14:05:12Z",
    "resolvedAt": null,
    "durationSeconds": 240,
    "cause": "HTTP 503",
    "regions": ["eu-central", "us-east"],
    "acknowledged": false
  }
]

Alert contacts#

Method and path	Description
`GET /alert-contacts`, `GET /alert-contacts/{id}`	List or read contacts.
`POST /alert-contacts`, `PUT /alert-contacts/{id}`, `DELETE /alert-contacts/{id}`	Create, update, delete.
`POST /alert-contacts/{id}/test`	Send a test alert → `{ "ok": true, "message": "…" }`.
`POST /alert-contacts/{id}/verify`	`{ "code": "123456" }` verifies e-mail / SMS / voice contacts; an empty body sends a new code.

bash

curl -s -X POST https://api.isituprightnow.com/api/v1/alert-contacts \
  -H "X-Api-Key: $IIUN_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "Slack", "name": "#ops", "target": "https://hooks.slack.com/services/T000/B000/XXXX" }'

type is one of Email, Sms, Voice, Webhook, Slack, Discord, Teams, GoogleChat, Telegram, Pushover. Webhook contacts take config: { "method", "headers", "bodyTemplate" }; Pushover takes config: { "appToken", "device", "priority" }. See Alerts.

Connect contacts to a monitor with its alert rules (this replaces the whole list):

bash

curl -s -X PUT "https://api.isituprightnow.com/api/v1/monitors/$MONITOR_ID/alert-rules" \
  -H "X-Api-Key: $IIUN_API_KEY" -H "Content-Type: application/json" \
  -d '[
    { "contactId": "'"$SLACK_CONTACT_ID"'", "thresholdMinutes": 0, "repeatEveryMinutes": 0 },
    { "contactId": "'"$SMS_CONTACT_ID"'", "thresholdMinutes": 5, "repeatEveryMinutes": 15 }
  ]'

Maintenance windows#

GET, POST /maintenance-windows, PUT and DELETE /maintenance-windows/{id} with { name, monitorIds, startsAt, endsAt, recurrence: null | "daily" | "weekly" | "monthly", timeZone }. The response adds active. See Maintenance windows for an example.

Status pages#

Method and path	Description
`GET /status-pages`, `GET /status-pages/{id}`	List or read pages (editor model, with `publicUrl`).
`POST /status-pages`, `PUT /status-pages/{id}`, `DELETE /status-pages/{id}`	Create, update, delete.
`POST /status-pages/{id}/announcements`	`{ "title", "body", "severity": "info" \| "warning" \| "critical" }` — published and e-mailed to subscribers.
`GET /status-pages/{id}/subscribers`	Subscribers (paginated).

The public, read-only view of a page is available without a key at GET /public/status-pages/{slug}, and its badge at GET /public/status-pages/{slug}/badge.svg.

Heartbeats#

Heartbeat URLs need no key: GET, POST or HEAD https://api.isituprightnow.com/api/v1/heartbeat/{token}. See Heartbeat monitors.

Webhooks (outgoing)#

To receive alerts in your own systems, add a Webhook alert contact. We send a JSON payload like this for every alert:

json

{
  "event": "monitor.up",
  "monitor": { "id": "8b0c7d3e-3f5a-4a49-9a51-2f1f0f4c6a10", "name": "Website — homepage", "target": "https://www.example.com/" },
  "status": "Up",
  "title": "Website — homepage is UP",
  "message": "isituprightnow: Website — homepage is UP after 4m 0s (https://www.example.com/)",
  "locale": "en",
  "occurredAt": "2026-10-03T14:09:12.000Z",
  "cause": null,
  "regions": ["eu-central", "us-east"],
  "incidentId": "5e1f2a9b-77c4-4d3e-9a0f-6b2d8c1e4f55",
  "downtimeSeconds": 240,
  "responseMs": null,
  "expiresAt": null,
  "link": "https://isituprightnow.com/app/incidents/5e1f2a9b-77c4-4d3e-9a0f-6b2d8c1e4f55"
}

event is monitor.down, monitor.up, monitor.slow, ssl.expiring, domain.expiring or test. Every field, custom body templates and delivery rules are described in Alerts → Webhooks. Protect your endpoint with a secret header (for example Authorization: Bearer <random>) configured on the contact, and answer with any 2xx status within 10 seconds.

Didn't find what you were looking for? Contact us.