REST API

Manage Spot Downtime from code: create monitors when you deploy a new service, pause them or schedule maintenance during a release, post incident updates and pull uptime history into your own reports. The API uses JSON over HTTPS and is available on every plan.

Authentication

Create a key in the app under Settings → API keys (owners and admins). Choose Read only for dashboards and reports, or Read & write for scripts that change things. Send it as a bearer token:

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/monitors" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

A key works in one workspace only and acts as the person who created it. It stops working if they leave the workspace.
Keys can't reach billing, team, account or API key settings.
The key is shown once. Store it as a secret (a CI secret or environment variable), never in code. Delete it in the app if it leaks; requests with it then get 401.

Your workspace ID is shown with a copy button at the top of Settings → API keys, and in every monitor as workspace_id.

Errors and limits

Errors return a status code and a JSON body with a human-readable error, for example {"error": "This API key is read-only."}.

Status	Meaning
`400`	The request isn't valid, such as a bad URL or an interval faster than your plan allows. The message says what to fix.
`401`	The key is missing, wrong or deleted.
`402`	A plan limit, such as the number of monitors. Upgrade or remove something.
`403`	The key is read-only, or the endpoint isn't available with an API key.
`404`	Not found in this key's workspace.
`429`	More than 120 requests a minute with this key. Wait for the time in the Retry-After header.

Example: maintenance during deploys

Schedule a 15-minute maintenance window at the start of a deploy, so a restart isn't counted as downtime or alerted:

bash

START=$(date -u +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u -d "+15 minutes" +%Y-%m-%dT%H:%M:%SZ)
curl -X POST "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/maintenance" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"title\": \"Deploy\", \"starts_at\": \"$START\", \"ends_at\": \"$END\", \"monitor_ids\": [\"$MONITOR_ID\"]}"

When the deploy finishes, check it straight away with POST /monitors/{mid}/check, and end the window early with PATCH /maintenance/{id}.

Workspace

GET/workspaces/{wid}

Get the workspace. The workspace's name, plan and usage, including its monitor limit and fastest check interval.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: The workspace with its plan and usage.

Monitors

GET/workspaces/{wid}/monitors

List monitors. Every monitor in the workspace with its current status, last check and 24-hour uptime.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/monitors" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: An array of monitors.

json

[
  {
    "id": "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f",
    "workspace_id": "1651d39c-77d4-41de-b457-ccdd8ff616bf",
    "name": "Checkout",
    "url": "https://shop.example.com/cart",
    "type": "http",
    "keyword": "Add to cart",
    "ssl_expires_at": "2027-01-14T23:59:59Z",
    "config": {},
    "interval_sec": 60,
    "paused": false,
    "status": "up",
    "last_checked_at": "2026-10-12T09:41:05Z",
    "last_latency_ms": 182,
    "last_status_code": 200,
    "last_error": null,
    "created_at": "2026-09-30T14:02:11Z",
    "uptime_24h": 99.93,
    "maintenance": false
  }
]

POST/workspaces/{wid}/monitors

Create a monitor. Types: http (website), api, tcp (url is host:port), dns (url is a domain), ping (a host or IP) and heartbeat (no url; the response includes its ping_url). The interval can't be faster than the plan allows. Needs a read & write key.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl -X POST "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/monitors" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Checkout","type":"http","url":"https://shop.example.com/cart","keyword":"Add to cart","interval_sec":60}'

Response 201: The new monitor.

json

{
  "id": "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f",
  "workspace_id": "1651d39c-77d4-41de-b457-ccdd8ff616bf",
  "name": "Checkout",
  "url": "https://shop.example.com/cart",
  "type": "http",
  "keyword": "Add to cart",
  "ssl_expires_at": "2027-01-14T23:59:59Z",
  "config": {},
  "interval_sec": 60,
  "paused": false,
  "status": "up",
  "last_checked_at": "2026-10-12T09:41:05Z",
  "last_latency_ms": 182,
  "last_status_code": 200,
  "last_error": null,
  "created_at": "2026-09-30T14:02:11Z",
  "uptime_24h": 99.93,
  "maintenance": false
}

GET/monitors/{mid}

Get a monitor. One monitor, with its last 50 checks and uptime over 24 hours, 7 and 30 days.

Parameter	In	Description
`mid`	path	Monitor ID.

bash

curl "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: The monitor and its stats.

json

{
  "monitor": {
    "id": "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f",
    "workspace_id": "1651d39c-77d4-41de-b457-ccdd8ff616bf",
    "name": "Checkout",
    "url": "https://shop.example.com/cart",
    "type": "http",
    "keyword": "Add to cart",
    "ssl_expires_at": "2027-01-14T23:59:59Z",
    "config": {},
    "interval_sec": 60,
    "paused": false,
    "status": "up",
    "last_checked_at": "2026-10-12T09:41:05Z",
    "last_latency_ms": 182,
    "last_status_code": 200,
    "last_error": null,
    "created_at": "2026-09-30T14:02:11Z",
    "uptime_24h": 99.93,
    "maintenance": false
  },
  "stats": {
    "uptime_24h": 99.93,
    "uptime_7d": 99.98,
    "uptime_30d": 99.97
  }
}

PATCH/monitors/{mid}

Update, pause or resume a monitor. Send only the fields to change. Set paused to true before a deploy and back to false after, or use a maintenance window. Needs a read & write key.

Parameter	In	Description
`mid`	path	Monitor ID.

bash

curl -X PATCH "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paused":true}'

Response 200: The updated monitor.

json

{
  "id": "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f",
  "workspace_id": "1651d39c-77d4-41de-b457-ccdd8ff616bf",
  "name": "Checkout",
  "url": "https://shop.example.com/cart",
  "type": "http",
  "keyword": "Add to cart",
  "ssl_expires_at": "2027-01-14T23:59:59Z",
  "config": {},
  "interval_sec": 60,
  "paused": true,
  "status": "up",
  "last_checked_at": "2026-10-12T09:41:05Z",
  "last_latency_ms": 182,
  "last_status_code": 200,
  "last_error": null,
  "created_at": "2026-09-30T14:02:11Z",
  "uptime_24h": 99.93,
  "maintenance": false
}

DELETE/monitors/{mid}

Delete a monitor. Deletes the monitor with its checks and incidents. This can't be undone. Needs a read & write key.

Parameter	In	Description
`mid`	path	Monitor ID.

bash

curl -X DELETE "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 204: Deleted.

POST/monitors/{mid}/check

Check a monitor now. Runs a check straight away, for example right after a deploy, and records it like a scheduled one. Needs a read & write key.

Parameter	In	Description
`mid`	path	Monitor ID.

bash

curl -X POST "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID/check" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: The monitor after the check.

json

{
  "id": "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f",
  "workspace_id": "1651d39c-77d4-41de-b457-ccdd8ff616bf",
  "name": "Checkout",
  "url": "https://shop.example.com/cart",
  "type": "http",
  "keyword": "Add to cart",
  "ssl_expires_at": "2027-01-14T23:59:59Z",
  "config": {},
  "interval_sec": 60,
  "paused": false,
  "status": "up",
  "last_checked_at": "2026-10-12T09:41:05Z",
  "last_latency_ms": 182,
  "last_status_code": 200,
  "last_error": null,
  "created_at": "2026-09-30T14:02:11Z",
  "uptime_24h": 99.93,
  "maintenance": false
}

History

GET/monitors/{mid}/series

Response times and uptime over time. Buckets of average response time and failed checks for a time range, as shown on the monitor's chart.

Parameter	In	Description
`mid`	path	Monitor ID.
`range`	query	Time range. Defaults to 24h; ranges beyond your plan's history are refused. One of `24h`, `7d`, `30d`, `90d`, `1y`, `2y`.

bash

curl "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID/series" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: The series for the range.

GET/monitors/{mid}/export

Download checks as CSV. Every check, or one row per day with uptime, as CSV. Needs a key created by an owner or admin.

Parameter	In	Description
`mid`	path	Monitor ID.
`kind`	query	checks (every check) or daily (one row per day). Defaults to checks. One of `checks`, `daily`.
`range`	query	How far back. One of `24h`, `7d`, `30d`, `90d`, `1y`, `2y`.

bash

curl "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID/export?range=30d" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: A CSV file.

Incidents

GET/monitors/{mid}/incidents

List a monitor's incidents. Outages of one monitor, newest first, with their reason and duration.

Parameter	In	Description
`mid`	path	Monitor ID.

bash

curl "https://spotdowntime.com/api/v1/monitors/$MONITOR_ID/incidents" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: An array of incidents.

GET/workspaces/{wid}/incidents

List incidents. The 300 most recent incidents across every monitor in the workspace, newest first.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/incidents" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: An array of incidents.

json

[
  {
    "id": 412,
    "monitor_id": "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f",
    "monitor_name": "Checkout",
    "started_at": "2026-10-12T14:02:00Z",
    "resolved_at": "2026-10-12T14:07:12Z",
    "reason": "HTTP 503 (down from 3 of 3 regions: california, singapore, amsterdam)",
    "latest_update": "resolved",
    "updates": 2
  }
]

GET/incidents/{id}

Get an incident. One incident with the updates your team has posted.

Parameter	In	Description
`id`	path	Incident ID.

bash

curl "https://spotdowntime.com/api/v1/incidents/$ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: The incident and its updates.

POST/incidents/{id}/updates

Post an incident update. Adds an update, shown on status pages that include the monitor unless public is false. Needs a read & write key.

Parameter	In	Description
`id`	path	Incident ID.

bash

curl -X POST "https://spotdowntime.com/api/v1/incidents/$ID/updates" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"identified","message":"A database migration is slowing checkout. Rolling it back now.","public":true}'

Response 201: The new update's ID.

json

{
  "id": 1093
}

Maintenance

GET/workspaces/{wid}/maintenance

List maintenance windows. Upcoming, current and recent maintenance windows.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/maintenance" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: An array of maintenance windows.

POST/workspaces/{wid}/maintenance

Schedule maintenance. Pauses checks on the chosen monitors between starts_at and ends_at (at most 31 days), so planned work isn't counted as downtime or alerted. Shown on status pages ahead of time. Needs a read & write key.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl -X POST "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/maintenance" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Database upgrade","message":"Checkout may be unavailable for a few minutes.","starts_at":"2026-10-14T22:00:00Z","ends_at":"2026-10-14T22:30:00Z","monitor_ids":["8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f"],"notify_subscribers":false}'

Response 201: The new window.

json

{
  "id": "c0d875b7-e6c5-4772-81ff-7627098eba0a",
  "title": "Database upgrade",
  "message": "Checkout may be unavailable for a few minutes.",
  "starts_at": "2026-10-14T22:00:00Z",
  "ends_at": "2026-10-14T22:30:00Z",
  "monitor_ids": [
    "8f1c2d4e-5a6b-4c7d-9e0f-1a2b3c4d5e6f"
  ],
  "created_at": "2026-10-12T10:00:00Z"
}

PATCH/maintenance/{id}

Change or end maintenance. Change any field. To end a window early, set ends_at to the current time. Needs a read & write key.

Parameter	In	Description
`id`	path	Maintenance window ID.

bash

curl -X PATCH "https://spotdowntime.com/api/v1/maintenance/$ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ends_at":"2026-10-14T22:12:00Z"}'

Response 200: The updated window.

DELETE/maintenance/{id}

Delete maintenance. Removes the window. Checks resume straight away if it was in progress. Needs a read & write key.

Parameter	In	Description
`id`	path	Maintenance window ID.

bash

curl -X DELETE "https://spotdowntime.com/api/v1/maintenance/$ID" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 204: Deleted.

Status pages & alerts

GET/workspaces/{wid}/status-pages

List status pages. The workspace's status pages and the monitors each one shows.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/status-pages" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: An array of status pages.

GET/workspaces/{wid}/alert-channels

List alert channels. Where alerts go, with when each channel last delivered. Addresses are masked.

Parameter	In	Description
`wid`	path	Workspace ID, shown at the top of Settings → API keys.

bash

curl "https://spotdowntime.com/api/v1/workspaces/$WORKSPACE_ID/alert-channels" \
  -H "Authorization: Bearer $SPOT_DOWNTIME_API_KEY"

Response 200: An array of alert channels.

MCP server for AI assistants

Spot Downtime is also a remote MCP server (Model Context Protocol), so AI assistants like Claude, Cursor and GitHub Copilot in VS Code can check your monitors, investigate incidents and schedule maintenance when you ask in plain language: “Is anything down?”, “Put checkout in maintenance for 20 minutes”, “Why did the API go down last night?”

It uses the same API keys. A read-only key gives the assistant read tools only; a read & write key adds tools that change things. The key's workspace is used automatically.

Server URL	Transport	Authentication
`https://spotdowntime.com/api/v1/mcp`	Streamable HTTP	Authorization: Bearer sd_…

Claude Code

Replace sd_your_key with your key. --scope user makes it available in every project, not just the current folder.

bash

claude mcp add --transport http --scope user spot-downtime https://spotdowntime.com/api/v1/mcp \
  --header "Authorization: Bearer sd_your_key"

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

json

{
  "mcpServers": {
    "spot-downtime": {
      "url": "https://spotdowntime.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sd_your_key"
      }
    }
  }
}

VS Code (GitHub Copilot)

In .vscode/mcp.json. VS Code asks for the key once and stores it securely:

json

{
  "inputs": [
    {
      "id": "spotDowntimeKey",
      "type": "promptString",
      "description": "Spot Downtime API key",
      "password": true
    }
  ],
  "servers": {
    "spot-downtime": {
      "type": "http",
      "url": "https://spotdowntime.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:spotDowntimeKey}"
      }
    }
  }
}

Claude Desktop

In claude_desktop_config.json, through the mcp-remote bridge (needs Node.js):

json

{
  "mcpServers": {
    "spot-downtime": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://spotdowntime.com/api/v1/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer sd_your_key"
      }
    }
  }
}

Tools

Tool	What it does	Key
`get_workspace`	The workspace's plan, limits and usage.	Any
`list_monitors`	Every monitor with its status, last check and 24-hour uptime.	Any
`get_monitor`	One monitor with uptime over 24 hours, 7 and 30 days and its recent checks.	Any
`create_monitor`	Monitor a website, API, TCP port, DNS record, host or cron job.	Read & write
`update_monitor`	Change a monitor's name, URL, keyword or interval.	Read & write
`pause_monitor / resume_monitor`	Stop or restart checks on a monitor.	Read & write
`delete_monitor`	Delete a monitor (the assistant is told to confirm first).	Read & write
`check_monitor_now`	Run a check straight away.	Read & write
`get_response_times`	Response times and failures over 24 hours to 2 years.	Any
`list_incidents / get_incident`	Recent outages with reasons and durations, and their updates.	Any
`post_incident_update`	Post an update that appears on your status pages.	Read & write
`list_maintenance`	Upcoming, current and recent maintenance windows.	Any
`schedule_maintenance / end_maintenance`	Pause checks for planned work, then end it early.	Read & write
`list_status_pages / list_alert_channels`	Status pages and where alerts go.	Any

Tool calls count toward the key's limit of 120 requests a minute. Give an assistant a read-only key unless you want it to make changes, and review what it plans to do before approving write tools.

OpenAPI

The whole API is described in /openapi.json (OpenAPI 3.1). Import it into Postman or Insomnia, generate a client in your language, or give it to an AI coding tool.

Something missing or unclear? Tell us.