{"openapi":"3.1.0","info":{"title":"Spot Downtime API","version":"1.0.0","description":"Manage monitors, maintenance and incidents from code. Create an API key under Settings → API keys in the app."},"servers":[{"url":"https://spotdowntime.com/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Workspace"},{"name":"Monitors"},{"name":"History"},{"name":"Incidents"},{"name":"Maintenance"},{"name":"Status pages & alerts"}],"paths":{"/workspaces/{wid}":{"get":{"operationId":"get-workspace","tags":["Workspace"],"summary":"Get the workspace","description":"The workspace's name, plan and usage, including its monitor limit and fastest check interval.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"The workspace with its plan and usage."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/workspaces/{wid}/monitors":{"get":{"operationId":"list-monitors","tags":["Monitors"],"summary":"List monitors","description":"Every monitor in the workspace with its current status, last check and 24-hour uptime.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"An array of monitors.","content":{"application/json":{"example":[{"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}]}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"create-monitor","tags":["Monitors"],"summary":"Create a monitor","description":"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 API key.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"201":{"description":"The new monitor.","content":{"application/json":{"example":{"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}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"description":"The monitor. Only url is required for a website check; name defaults to the host.","content":{"application/json":{"example":{"name":"Checkout","type":"http","url":"https://shop.example.com/cart","keyword":"Add to cart","interval_sec":60}}}}}},"/monitors/{mid}":{"get":{"operationId":"get-monitor","tags":["Monitors"],"summary":"Get a monitor","description":"One monitor, with its last 50 checks and uptime over 24 hours, 7 and 30 days.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The monitor and its stats.","content":{"application/json":{"example":{"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}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"update-monitor","tags":["Monitors"],"summary":"Update, pause or resume a monitor","description":"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 API key.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The updated monitor.","content":{"application/json":{"example":{"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}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"description":"Any of name, url, keyword (\"\" removes it), interval_sec, paused and config.","content":{"application/json":{"example":{"paused":true}}}}},"delete":{"operationId":"delete-monitor","tags":["Monitors"],"summary":"Delete a monitor","description":"Deletes the monitor with its checks and incidents. This can't be undone. Needs a read & write API key.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/monitors/{mid}/check":{"post":{"operationId":"check-now","tags":["Monitors"],"summary":"Check a monitor now","description":"Runs a check straight away, for example right after a deploy, and records it like a scheduled one. Needs a read & write API key.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The monitor after the check.","content":{"application/json":{"example":{"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}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/monitors/{mid}/series":{"get":{"operationId":"monitor-series","tags":["History"],"summary":"Response times and uptime over time","description":"Buckets of average response time and failed checks for a time range, as shown on the monitor's chart.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}},{"name":"range","in":"query","required":false,"description":"Time range. Defaults to 24h; ranges beyond your plan's history are refused.","schema":{"type":"string","enum":["24h","7d","30d","90d","1y","2y"]}}],"responses":{"200":{"description":"The series for the range."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/monitors/{mid}/export":{"get":{"operationId":"monitor-export","tags":["History"],"summary":"Download checks as CSV","description":"Every check, or one row per day with uptime, as CSV. Needs a key created by an owner or admin.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"checks (every check) or daily (one row per day). Defaults to checks.","schema":{"type":"string","enum":["checks","daily"]}},{"name":"range","in":"query","required":true,"description":"How far back.","schema":{"type":"string","enum":["24h","7d","30d","90d","1y","2y"]}}],"responses":{"200":{"description":"A CSV file."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/monitors/{mid}/incidents":{"get":{"operationId":"monitor-incidents","tags":["Incidents"],"summary":"List a monitor's incidents","description":"Outages of one monitor, newest first, with their reason and duration.","parameters":[{"name":"mid","in":"path","required":true,"description":"Monitor ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"An array of incidents."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/workspaces/{wid}/incidents":{"get":{"operationId":"workspace-incidents","tags":["Incidents"],"summary":"List incidents","description":"The 300 most recent incidents across every monitor in the workspace, newest first.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"An array of incidents.","content":{"application/json":{"example":[{"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}]}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/incidents/{id}":{"get":{"operationId":"get-incident","tags":["Incidents"],"summary":"Get an incident","description":"One incident with the updates your team has posted.","parameters":[{"name":"id","in":"path","required":true,"description":"Incident ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The incident and its updates."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/incidents/{id}/updates":{"post":{"operationId":"post-incident-update","tags":["Incidents"],"summary":"Post an incident update","description":"Adds an update, shown on status pages that include the monitor unless public is false. Needs a read & write API key.","parameters":[{"name":"id","in":"path","required":true,"description":"Incident ID.","schema":{"type":"string"}}],"responses":{"201":{"description":"The new update's ID.","content":{"application/json":{"example":{"id":1093}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"description":"status is investigating, identified, monitoring, resolved or update.","content":{"application/json":{"example":{"status":"identified","message":"A database migration is slowing checkout. Rolling it back now.","public":true}}}}}},"/workspaces/{wid}/maintenance":{"get":{"operationId":"list-maintenance","tags":["Maintenance"],"summary":"List maintenance windows","description":"Upcoming, current and recent maintenance windows.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"An array of maintenance windows."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"create-maintenance","tags":["Maintenance"],"summary":"Schedule maintenance","description":"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 API key.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"201":{"description":"The new window.","content":{"application/json":{"example":{"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"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"description":"Times are ISO 8601. notify_subscribers emails status page subscribers about the window.","content":{"application/json":{"example":{"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}}}}}},"/maintenance/{id}":{"patch":{"operationId":"update-maintenance","tags":["Maintenance"],"summary":"Change or end maintenance","description":"Change any field. To end a window early, set ends_at to the current time. Needs a read & write API key.","parameters":[{"name":"id","in":"path","required":true,"description":"Maintenance window ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"The updated window."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"description":"Any of title, message, starts_at, ends_at and monitor_ids.","content":{"application/json":{"example":{"ends_at":"2026-10-14T22:12:00Z"}}}}},"delete":{"operationId":"delete-maintenance","tags":["Maintenance"],"summary":"Delete maintenance","description":"Removes the window. Checks resume straight away if it was in progress. Needs a read & write API key.","parameters":[{"name":"id","in":"path","required":true,"description":"Maintenance window ID.","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/workspaces/{wid}/status-pages":{"get":{"operationId":"list-status-pages","tags":["Status pages & alerts"],"summary":"List status pages","description":"The workspace's status pages and the monitors each one shows.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"An array of status pages."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/workspaces/{wid}/alert-channels":{"get":{"operationId":"list-alert-channels","tags":["Status pages & alerts"],"summary":"List alert channels","description":"Where alerts go, with when each channel last delivered. Addresses are masked.","parameters":[{"name":"wid","in":"path","required":true,"description":"Workspace ID, shown at the top of Settings → API keys.","schema":{"type":"string"}}],"responses":{"200":{"description":"An array of alert channels."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key: Authorization: Bearer sd_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"The key is missing, wrong or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"That API key isn't valid. It may have been deleted."}}}},"Forbidden":{"description":"The key is read-only, or the endpoint isn't available with an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"This API key is read-only."}}}},"NotFound":{"description":"No such resource in the key's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Not found."}}}},"TooManyRequests":{"description":"More than 120 requests a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Too many requests with this API key. The limit is 120 a minute."}}}}}}}