Monitive Feed API

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.

        '