Monitive Incidents API

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.

        '