Monitive Feed.xml API

openapi: 3.2.0
info:
  title: UptimeMonitoring.com Feed.xml 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.xml
paths:
  /feed.xml:
    get:
      summary: Public platform-news Atom feed (unauthenticated)
      security: []
      description: 'Public Atom XML feed rendering currently active platform announcements

        from the shared `announcements` table. No `Authorization` header is

        required. The feed contains at most 50 entries, ordered descending

        by `published_at` (with a stable secondary `id` tiebreaker).


        Active means `published_at now()`). Empty active sets still return a valid Atom

        envelope with zero `` rows so aggregator-cache content hashes

        stay stable.


        Cache-Control is `public, max-age=300` — Cloudflare in front of the

        API will respect the hint. Announcements are not time-critical, so

        a 5-minute window is acceptable.


        `` semantics: the feed-level `` is a best-effort

        change marker, not a linearizable version counter. It is the

        GREATEST of four signals — an edit to any announcement (including

        one that unpublishes a row by pushing `published_at` into the

        future), a scheduled announcement crossing into visibility, an

        active announcement crossing into expiry, or a hard delete — and

        it never exceeds the current time. Writes to *different*

        announcement rows take no shared lock, so two concurrent edits can

        commit in an order where the marker does not advance past a value

        a reader already observed even though a new change became visible

        in that window. Treat `` as a "poll again soon" hint, not

        a guarantee that an unchanged value means nothing changed since

        your last read. Per-entry `` is the later of that

        announcement''s last edit and its `published_at`, clamped so it

        never exceeds the current time — a just-published scheduled

        announcement reads `updated == published` rather than

        updated-before-published, and a row whose last-edit timestamp

        is ahead of real time (clock skew, or accumulated

        strict-advance drift) reads the current time instead of that

        future value. Timestamps use full sub-second precision (RFC

        3339 with fractional seconds) so edits within the same

        wall-clock second still render distinct values.'
      responses:
        '200':
          description: Atom feed
          headers:
            Cache-Control:
              schema:
                type: string
              description: Always `public, max-age=300`.
          content:
            application/atom+xml:
              schema:
                type: string
        '500':
          description: Database error rendering the feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Feed.xml
      operationId: getFeedXml
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
      example:
        error: something went wrong
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key (`umk_live_*`) or session token from OAuth exchange.

        '