Monitive Incidents API
The Incidents API from Monitive — 2 operation(s) for incidents.
The Incidents API from Monitive — 2 operation(s) for incidents.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/uptimemonitoring-com:uptimemonitoring-com-incidents-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: UptimeMonitoring.com Incidents API
version: 0.1.0
description: 'API-first uptime monitoring for developers, deploy pipelines, and AI agents.
## Authentication
All `/api/v1` endpoints require a Bearer token — either an API key (`umk_live_*`)
or a session token obtained via GitHub OAuth. The `/mcp` endpoint additionally
accepts OAuth 2.1 JWT access tokens (`eyJ...`) issued via the self-hosted
authorization server documented under the `OAuth` tag.
```
Authorization: Bearer umk_live_abc123...
```
## Rate limits
200 requests/minute per account. Exceeding the limit returns `429` with a
`Retry-After` header.
Responses that pass through the per-account rate-limiter carry the
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`
headers (decimal integers; `Reset` is a Unix epoch second at which
the bucket would be full again). In practice this is every
authenticated response under `/api/v1/*` whose request reached the
handler — earlier failures from the auth middleware (e.g. 401 missing
credentials, 403 suspended account) return before the limiter runs
and do NOT carry the trio. Routes mounted outside `/api/v1`
(notably `GET /api/v1/events/stream`, which has its own SSE
middleware stack) are not subject to this limiter and likewise do
not emit these headers. Successful responses on
`POST /api/v1/monitors` reflect the **global** 200/min bucket; the
per-route 20/min creation limit only surfaces its own headers when
it 429s. The trio is documented once here rather than referenced
into every individual response — see `components.headers` for the
schemas.
One exception: once a request presenting an API key enters an
authenticated route group through a registered route or mounted
subtree, while that key remains in the bounded pre-auth cache
(entries expire after 5 minutes, but may be evicted sooner once the
cache is at capacity), the global bucket is charged BEFORE
authentication and authorization run (issue #47) — so for that
cached key only, a `401` (key revoked while still cached), `403`,
`500`, or a `404` for an unmatched path inside a mounted subtree
also carries the `X-RateLimit-*` trio and spends one token. `429`
still comes first whenever the bucket is already empty. An uncached
key (first seen, expired, or evicted early at capacity), a session
token, an OAuth JWT, and any path outside every authenticated group
are all unaffected.
## Browser push notifications
Subscriptions registered via `POST /api/v1/push/subscribe` receive
fire-and-forget Web Push notifications on monitor state transitions
(down/up/flapping); per-monitor 5-minute throttle. No public API change
in this release — dispatch is internal to `internal/push.Dispatcher`.'
contact:
name: UptimeMonitoring.com
url: https://uptimemonitoring.com
license:
name: Proprietary
identifier: LicenseRef-Proprietary
servers:
- url: https://api.uptimemonitoring.com
description: Production
tags:
- name: Incidents
paths:
/api/v1/incidents:
get:
operationId: listIncidents
summary: List incidents
description: 'Returns incidents for the authenticated account with optional filtering
and pagination. Ordered by start time (newest first). A resolved
incident older than 30 days is never returned here (issue #357) —
this is a visibility floor enforced at read time, independent of
how long the underlying row is physically kept (95 days, so the
uptime-report worker and a status page''s 90-day daily history both
have enough lookback; see internal/retention/DECISIONS.md). An
open incident is never hidden by this floor, however old it is.'
tags:
- Incidents
security:
- bearerAuth: []
parameters:
- name: monitor_id
in: query
schema:
type: integer
format: int64
description: Filter by monitor ID.
- name: type
in: query
schema:
type: string
enum:
- down
- flapping
description: Filter by incident type.
- name: started_after
in: query
schema:
type: string
format: date-time
description: Only incidents started after this time (RFC3339).
- name: started_before
in: query
schema:
type: string
format: date-time
description: Only incidents started before this time (RFC3339).
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
description: Page size (1-100).
- name: offset
in: query
schema:
type: integer
minimum: 0
default: 0
description: Number of items to skip.
responses:
'200':
description: Paginated incident list.
content:
application/json:
schema:
type: object
properties:
incidents:
type: array
items:
$ref: '#/components/schemas/Incident'
total:
type: integer
description: Total matching incidents (for pagination).
limit:
type: integer
offset:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/AccountSuspended'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/incidents/{incidentID}:
get:
operationId: getIncident
summary: Get incident
description: 'Returns a single incident with its evidence snapshot. Same 30-day
visibility floor as `GET /incidents` (issue #357): a resolved
incident older than 30 days 404s here as if it did not exist.'
tags:
- Incidents
security:
- bearerAuth: []
parameters:
- name: incidentID
in: path
required: true
schema:
type: string
pattern: ^([0-9]+|[0-9a-hjkmnp-tv-z]{6}-[1-9][0-9]*)$
description: 'Numeric incident id or ref (issue #412), e.g. "k7q2mx-3". A ref whose handle belongs to a different account, or whose number doesn''t resolve, 404s the same as a nonexistent numeric id.'
responses:
'200':
description: Incident details.
content:
application/json:
schema:
type: object
properties:
incident:
$ref: '#/components/schemas/Incident'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/AccountSuspended'
'404':
description: Incident not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
CheckResult:
type: object
properties:
timestamp:
type: string
format: date-time
region:
type: string
status_code:
type: integer
error_class:
type: string
dns_ms:
type: number
tls_ms:
type: number
connect_ms:
type: number
ttfb_ms:
type: number
download_ms:
type: number
content_length:
type: integer
format: int64
response_hash:
type: string
packet_loss_pct:
type: number
minimum: 0
maximum: 100
description: 'Ping-only packet loss percentage (0-100). Omitted (not present
in the object) when not measured — every non-ping check result,
and a ping probe-side failure that never reached the target. A
measured 0% loss is present with value 0, distinct from omitted.
'
Error:
type: object
required:
- error
properties:
error:
type: string
example:
error: something went wrong
Incident:
type: object
properties:
id:
type: integer
format: int64
number:
type: integer
format: int64
description: 'This incident''s per-account sequence number (issue #412), assigned once at creation and never reused.'
ref:
type: string
description: Stable "<account handle>-<number>" reference, e.g. "k7q2mx-3" — accepted anywhere `{incidentID}` appears in a path.
monitor_ref:
type: string
description: The owning monitor's own ref (issue
monitor_id:
type: integer
format: int64
account_id:
type: integer
format: int64
type:
type: string
enum:
- down
- flapping
started_at:
type: string
format: date-time
resolved_at:
type:
- string
- 'null'
format: date-time
description: Null if the incident is still ongoing.
evidence:
type: array
description: Snapshot of the evidence ring buffer at the time of the state transition.
items:
$ref: '#/components/schemas/CheckResult'
created_at:
type: string
format: date-time
maintenance:
type: boolean
description: 'True when this incident opened while the monitor''s maintenance
window was active (issue #361) — or, for a down-to-flapping or
flapping-to-down handoff, inherited from the incident it
replaced. A monitor-wide down/flapping alert is suppressed for
every recipient while this is true, and the recovery ("up")
alert is suppressed too once every incident the recovery
resolved carries this flag.
'
responses:
RateLimited:
description: 'Per-account dispatcher rate limit exceeded (200 requests/minute).
The `Retry-After` header gives the integer seconds until at least
one token has refilled. The `X-RateLimit-*` trio reflects the
bucket whose rejection produced this response — usually the global
200/min cap; on `POST /api/v1/monitors` a 429 may instead reflect
the per-route 20/min creation limit.
'
headers:
Retry-After:
schema:
type: integer
description: Seconds until the next allowed request.
X-RateLimit-Limit:
$ref: '#/components/headers/XRateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/XRateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/XRateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: account rate limit exceeded; retry in 1s
Unauthorized:
description: Missing or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: invalid credentials
AccountSuspended:
description: 'Account is currently suspended. On `POST /api/v1/monitors`, and on
a `PUT /api/v1/monitors/{monitorID}` that changes `url` or `type`
(issue #335), this can also be returned by the per-account
port-scan heuristic when the triggering request crossed the
port-fan threshold inside the sliding window (10 minutes by
default; `SCAN_WINDOW`). A host-fan trip does NOT suspend the
account — see the 429 response instead.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: account suspended; contact support
BadRequest:
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
XRateLimitReset:
schema:
type: integer
description: 'Unix epoch seconds at which the bucket would be full again if no
further requests are made. Sub-second fragments are rounded up so
`Reset - now` is never less than the actual refill duration.
'
XRateLimitLimit:
schema:
type: integer
description: 'Bucket capacity for the limiter that produced this response. `200`
for the global per-account dispatcher cap; `20` on a 429 from the
per-route monitor-create limiter.
'
XRateLimitRemaining:
schema:
type: integer
description: 'Tokens left in the bucket after this request was charged
(floor of the post-charge token count). `0` on a 429 means the
request was rejected with the bucket empty.
'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'API key (`umk_live_*`) or session token from OAuth exchange.
'