openapi: 3.1.0
info:
  title: isitup API
  version: 1.0.0
  summary: Manage monitors and read uptime data from your own tools.
  description: |
    The isitup REST API lets you manage monitors and read check results, incidents and status pages
    for your account. It speaks JSON over HTTPS and is available on every plan.

    **Authentication.** Create a token under *App > API* and send it as `Authorization: Bearer <token>`.
    A token is bound to one account; every request is scoped to that account, so resources belonging to other
    accounts answer `404`.

    **Rate limits.** 120 requests per minute per token. Every response carries `X-RateLimit-Limit`,
    `X-RateLimit-Remaining` and `X-RateLimit-Reset` (epoch seconds). Exceeding the limit returns `429` with a
    `Retry-After` header.

    **Pagination.** List endpoints accept `page` and `per_page` (default 25, maximum 100; check results default 100,
    maximum 1000). The response body has `meta` and `links`; the same information is sent in the `Link`,
    `X-Page`, `X-Per-Page`, `X-Total-Count` and `X-Total-Pages` headers.

    **Errors.** Every error has the same shape: `{"error": {"code", "status", "message", "details"}}`.
    `details` maps field names to messages for validation errors.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://isitup.app/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: The account the token belongs to.
  - name: Monitors
    description: Create, change, pause and delete monitors. Plan limits and validations match the web app.
  - name: Check results
    description: Individual check results of a monitor.
  - name: Incidents
    description: Downtime incidents opened by failed checks.
  - name: Status pages
    description: Read-only access to your status pages.
paths:
  /account:
    get:
      tags: [Account]
      operationId: getAccount
      summary: Get the current account
      description: Returns the account of the token with its plan limits and current usage.
      responses:
        "200":
          description: The account.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: "#/components/schemas/Account"
              example:
                data:
                  id: 42
                  name: Acme Inc.
                  plan: pro
                  timezone: Europe/Berlin
                  created_at: "2026-01-12T09:30:00.000Z"
                  limits: { monitors: 200, min_interval_seconds: 30, status_pages: 5, browser_checks: 5, seats: 5, history_days: 365 }
                  usage: { monitors: 12, status_pages: 1, browser_checks: 0 }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /monitors:
    get:
      tags: [Monitors]
      operationId: listMonitors
      summary: List monitors
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - name: status
          in: query
          description: Only monitors with this status.
          schema: { type: string, enum: [pending, up, down, paused] }
        - name: kind
          in: query
          description: Only monitors of this kind.
          schema: { $ref: "#/components/schemas/MonitorKind" }
        - name: url
          in: query
          description: Only monitors with exactly this URL (or hostname for domain monitors).
          schema: { type: string }
        - name: q
          in: query
          description: Case-insensitive search in the monitor name.
          schema: { type: string }
      responses:
        "200":
          description: A page of monitors, oldest first.
          headers:
            Link: { $ref: "#/components/headers/Link" }
            X-Total-Count: { $ref: "#/components/headers/TotalCount" }
          content:
            application/json:
              schema:
                type: object
                required: [data, meta, links]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Monitor" }
                  meta: { $ref: "#/components/schemas/PageMeta" }
                  links: { $ref: "#/components/schemas/PageLinks" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Monitors]
      operationId: createMonitor
      summary: Create a monitor
      description: |
        Subject to the plan's monitor count, minimum check interval and browser check limits; violations are
        reported as `validation_failed` (422) with the same messages as the web app.
        Heartbeat monitors need no `url`; the response contains the URL your job must ping.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MonitorInput" }
            examples:
              website:
                summary: Website monitor
                value: { name: Marketing site, kind: http, url: "https://example.com", interval_seconds: 60 }
              heartbeat:
                summary: Heartbeat (cron job) monitor
                value: { name: Nightly backup, kind: heartbeat, interval_seconds: 86400 }
      responses:
        "201":
          description: The created monitor.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Monitor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /monitors/{id}:
    parameters:
      - $ref: "#/components/parameters/MonitorId"
    get:
      tags: [Monitors]
      operationId: getMonitor
      summary: Get a monitor
      responses:
        "200":
          description: The monitor.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Monitor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      tags: [Monitors]
      operationId: updateMonitor
      summary: Update a monitor
      description: Send only the attributes you want to change.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MonitorInput" }
            example: { name: Marketing site (EU), interval_seconds: 120 }
      responses:
        "200":
          description: The updated monitor.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Monitor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Monitors]
      operationId: deleteMonitor
      summary: Delete a monitor
      description: Permanently deletes the monitor with its check results and incidents.
      responses:
        "204":
          description: Deleted.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /monitors/{id}/pause:
    parameters:
      - $ref: "#/components/parameters/MonitorId"
    post:
      tags: [Monitors]
      operationId: pauseMonitor
      summary: Pause a monitor
      description: Stops checks and alerts until the monitor is resumed. Pausing a paused monitor is a no-op.
      responses:
        "200":
          description: The paused monitor.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Monitor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /monitors/{id}/resume:
    parameters:
      - $ref: "#/components/parameters/MonitorId"
    post:
      tags: [Monitors]
      operationId: resumeMonitor
      summary: Resume a monitor
      description: Schedules an immediate check. Resuming a monitor that is not paused is a no-op.
      responses:
        "200":
          description: The resumed monitor (status `pending` until the first check).
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Monitor" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationFailed" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /monitors/{id}/check_results:
    parameters:
      - $ref: "#/components/parameters/MonitorId"
    get:
      tags: [Check results]
      operationId: listCheckResults
      summary: List check results of a monitor
      description: |
        Newest first. Without `from`/`to` the last 24 hours are returned. The window never reaches back further
        than the plan's history (30 days on Free, 365 days on Pro and Agency).
      parameters:
        - $ref: "#/components/parameters/Page"
        - name: per_page
          in: query
          description: Results per page (default 100, maximum 1000).
          schema: { type: integer, minimum: 1, maximum: 1000, default: 100 }
        - name: from
          in: query
          description: Start of the time range, ISO 8601 (default `to` minus 24 hours).
          schema: { type: string, format: date-time }
        - name: to
          in: query
          description: End of the time range, ISO 8601 (default now).
          schema: { type: string, format: date-time }
        - name: region
          in: query
          description: Only results from this check region.
          schema: { type: string, examples: [eu-fra] }
        - name: outcome
          in: query
          schema: { type: string, enum: [success, failure] }
      responses:
        "200":
          description: A page of check results.
          headers:
            Link: { $ref: "#/components/headers/Link" }
            X-Total-Count: { $ref: "#/components/headers/TotalCount" }
          content:
            application/json:
              schema:
                type: object
                required: [data, meta, links]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/CheckResult" }
                  meta:
                    allOf:
                      - $ref: "#/components/schemas/PageMeta"
                      - type: object
                        properties:
                          monitor_id: { type: integer }
                          from: { type: string, format: date-time }
                          to: { type: string, format: date-time }
                  links: { $ref: "#/components/schemas/PageLinks" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /incidents:
    get:
      tags: [Incidents]
      operationId: listIncidents
      summary: List incidents
      description: Incidents of all monitors in the account, newest first.
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - name: status
          in: query
          schema: { type: string, enum: [open, resolved] }
        - name: monitor_id
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: A page of incidents.
          headers:
            Link: { $ref: "#/components/headers/Link" }
            X-Total-Count: { $ref: "#/components/headers/TotalCount" }
          content:
            application/json:
              schema:
                type: object
                required: [data, meta, links]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Incident" }
                  meta: { $ref: "#/components/schemas/PageMeta" }
                  links: { $ref: "#/components/schemas/PageLinks" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /incidents/{id}:
    get:
      tags: [Incidents]
      operationId: getIncident
      summary: Get an incident
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: The incident.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/Incident" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /status_pages:
    get:
      tags: [Status pages]
      operationId: listStatusPages
      summary: List status pages
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: A page of status pages.
          headers:
            Link: { $ref: "#/components/headers/Link" }
            X-Total-Count: { $ref: "#/components/headers/TotalCount" }
          content:
            application/json:
              schema:
                type: object
                required: [data, meta, links]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/StatusPage" }
                  meta: { $ref: "#/components/schemas/PageMeta" }
                  links: { $ref: "#/components/schemas/PageLinks" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /status_pages/{id}:
    get:
      tags: [Status pages]
      operationId: getStatusPage
      summary: Get a status page
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: The status page.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data: { $ref: "#/components/schemas/StatusPage" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API token created under App > API. Shown once at creation.
  parameters:
    Page:
      name: page
      in: query
      description: Page number, starting at 1.
      schema: { type: integer, minimum: 1, default: 1 }
    PerPage:
      name: per_page
      in: query
      description: Items per page (default 25, maximum 100).
      schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
    MonitorId:
      name: id
      in: path
      required: true
      description: Monitor id.
      schema: { type: integer, examples: [101] }
  headers:
    Link:
      description: RFC 8288 pagination links (`first`, `prev`, `next`, `last`).
      schema: { type: string }
    TotalCount:
      description: Total number of items across all pages.
      schema: { type: integer }
  responses:
    BadRequest:
      description: A parameter or the request body is malformed (`invalid_parameter`, `invalid_json`, `parameter_missing`).
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: invalid_parameter, status: 400, message: "Parameter 'from' must be an ISO 8601 timestamp, e.g. 2026-01-31T12:00:00Z", details: { from: ["must be an ISO 8601 timestamp, e.g. 2026-01-31T12:00:00Z"] } } }
    Unauthorized:
      description: The token is missing, unknown or revoked.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: unauthorized, status: 401, message: "Missing, invalid or revoked API token. Send 'Authorization: Bearer <token>'." } }
    NotFound:
      description: The resource does not exist or belongs to another account.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: not_found, status: 404, message: Resource not found. } }
    ValidationFailed:
      description: The record is invalid or a plan limit was hit.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: validation_failed, status: 422, message: "Validation failed: Interval seconds must be at least 60 seconds on the Free plan", details: { interval_seconds: ["must be at least 60 seconds on the Free plan"] } } }
    RateLimited:
      description: Too many requests; wait `Retry-After` seconds.
      headers:
        Retry-After: { description: Seconds until the limit resets., schema: { type: integer } }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: rate_limited, status: 429, message: Rate limit exceeded. Retry in 23 seconds. } }
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, status, message]
          properties:
            code: { type: string, description: Stable machine-readable code. }
            status: { type: integer, description: HTTP status. }
            message: { type: string, description: Human-readable explanation. }
            details:
              type: object
              description: Field name to list of messages (validation errors and bad parameters).
              additionalProperties:
                type: array
                items: { type: string }
    PageMeta:
      type: object
      properties:
        page: { type: integer }
        per_page: { type: integer }
        total: { type: integer }
        pages: { type: integer }
    PageLinks:
      type: object
      description: Absolute URLs; `prev` and `next` are null at the ends.
      properties:
        first: { type: string, format: uri }
        prev: { type: [string, "null"], format: uri }
        next: { type: [string, "null"], format: uri }
        last: { type: string, format: uri }
    MonitorKind:
      type: string
      enum: [http, keyword, ssl, domain, heartbeat, spam, form, checkout, indexing]
      description: |
        `http` checks a URL, `keyword` also looks for text, `ssl` and `domain` watch certificate and domain expiry,
        `heartbeat` expects a ping from your job, `form` and `checkout` are browser checks limited by plan.
    Account:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        plan: { type: string, enum: [free, pro, agency] }
        timezone: { type: string }
        created_at: { type: string, format: date-time }
        limits:
          type: object
          properties:
            monitors: { type: integer }
            min_interval_seconds: { type: integer }
            status_pages: { type: integer }
            browser_checks: { type: integer }
            seats: { type: integer }
            history_days: { type: integer }
        usage:
          type: object
          properties:
            monitors: { type: integer }
            status_pages: { type: integer }
            browser_checks: { type: integer }
    Monitor:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        kind: { $ref: "#/components/schemas/MonitorKind" }
        url: { type: [string, "null"] }
        status: { type: string, enum: [pending, up, down, paused] }
        interval_seconds: { type: integer }
        timeout_ms: { type: integer }
        http_method: { type: string }
        expected_status: { type: integer }
        keyword: { type: [string, "null"] }
        keyword_should_exist: { type: boolean }
        regions: { type: array, items: { type: string } }
        last_checked_at: { type: [string, "null"], format: date-time }
        last_response_ms: { type: [integer, "null"] }
        uptime_30d: { type: [number, "null"], description: "Percentage of successful checks in the last 30 days; null without results." }
        ssl_expires_at: { type: [string, "null"], format: date-time }
        domain_expires_at: { type: [string, "null"], format: date-time }
        heartbeat_token: { type: string, description: Heartbeat monitors only. }
        heartbeat_url: { type: string, format: uri, description: "Heartbeat monitors only: GET or POST here from your job." }
        paused_at: { type: [string, "null"], format: date-time }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      example:
        id: 101
        name: Marketing site
        kind: http
        url: "https://example.com"
        status: up
        interval_seconds: 60
        timeout_ms: 10000
        http_method: GET
        expected_status: 200
        keyword: null
        keyword_should_exist: true
        regions: []
        last_checked_at: "2026-11-16T07:00:12.000Z"
        last_response_ms: 187
        uptime_30d: 99.982
        ssl_expires_at: null
        domain_expires_at: null
        paused_at: null
        created_at: "2026-10-01T10:00:00.000Z"
        updated_at: "2026-11-16T07:00:12.000Z"
    MonitorInput:
      type: object
      properties:
        name: { type: string, maxLength: 120 }
        kind: { $ref: "#/components/schemas/MonitorKind" }
        url: { type: string, description: "http(s) URL; hostname for domain monitors; not needed for heartbeat monitors." }
        interval_seconds: { type: integer, maximum: 86400, description: Must be at least the plan's minimum (60 s Free, 30 s paid). Default 60. }
        timeout_ms: { type: integer, minimum: 1, maximum: 60000 }
        http_method: { type: string, enum: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS] }
        expected_status: { type: integer, minimum: 100, maximum: 599 }
        keyword: { type: string, description: Required for keyword monitors. }
        keyword_should_exist: { type: boolean }
        regions: { type: array, items: { type: string, enum: [eu-fra, us-nyc, ap-sgp] } }
    CheckResult:
      type: object
      properties:
        id: { type: integer }
        monitor_id: { type: integer }
        region: { type: string }
        outcome: { type: string, enum: [success, failure] }
        response_ms: { type: [integer, "null"] }
        http_status: { type: [integer, "null"] }
        error_message: { type: [string, "null"] }
        checked_at: { type: string, format: date-time }
      example:
        id: 9001
        monitor_id: 101
        region: eu-fra
        outcome: success
        response_ms: 187
        http_status: 200
        error_message: null
        checked_at: "2026-11-16T07:00:12.000Z"
    Incident:
      type: object
      properties:
        id: { type: integer }
        monitor_id: { type: integer }
        monitor_name: { type: string }
        status: { type: string, enum: [open, resolved] }
        cause: { type: [string, "null"] }
        confirmed_regions: { type: array, items: { type: string } }
        started_at: { type: string, format: date-time }
        resolved_at: { type: [string, "null"], format: date-time }
        acknowledged_at: { type: [string, "null"], format: date-time }
        duration_seconds: { type: integer }
    StatusPage:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }
        slug: { type: string }
        description: { type: [string, "null"] }
        public: { type: boolean }
        custom_domain: { type: [string, "null"] }
        monitor_ids: { type: array, items: { type: integer } }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
