Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API 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.
openapi: 3.2.0
info:
title: UptimeMonitoring.com Feed 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: Feed
paths:
/feed/{token}:
get:
summary: Public JSON incident feed (unauthenticated, token-gated)
security: []
description: 'Returns a trimmed view of recent incidents for the account owning this
token. No sensitive configuration is exposed. Rate-limited at 20
requests per minute per token.'
parameters:
- name: token
in: path
required: true
schema:
type: string
description: Feed token (prefix `fd_`).
responses:
'200':
description: Feed
content:
application/json:
schema:
$ref: '#/components/schemas/FeedResponse'
'403':
description: Owning account is suspended
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown or rotated token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
headers:
Retry-After:
schema:
type: integer
description: Seconds until the current window ends.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Feed
operationId: getFeedByToken
x-operation-id-source: derived
/feed/{token}/rss:
get:
summary: Public Atom/RSS incident feed (unauthenticated, token-gated)
security: []
parameters:
- name: token
in: path
required: true
schema:
type: string
responses:
'200':
description: Atom feed
content:
application/atom+xml:
schema:
type: string
'404':
description: Unknown or rotated token
'429':
description: Rate limit exceeded
headers:
Retry-After:
schema:
type: integer
tags:
- Feed
operationId: getFeedByTokenRss
x-operation-id-source: derived
components:
schemas:
Error:
type: object
required:
- error
properties:
error:
type: string
example:
error: something went wrong
FeedIncident:
type: object
properties:
id:
type: integer
format: int64
monitor_name:
type: string
monitor_url:
type: string
monitor_type:
type: string
type:
type: string
enum:
- down
- flapping
started_at:
type: string
format: date-time
resolved_at:
type:
- string
- 'null'
format: date-time
FeedResponse:
type: object
properties:
account:
type: object
properties:
github_username:
type: string
incidents:
type: array
items:
$ref: '#/components/schemas/FeedIncident'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'API key (`umk_live_*`) or session token from OAuth exchange.
'