openapi: 3.0.3
info:
  title: Better Stack Uptime API
  description: >-
    The Better Stack Uptime API provides programmatic access to manage uptime
    monitors, heartbeats, on-call schedules, incidents, status pages,
    integrations, team members, and reporting. The API follows the JSON:API
    specification and uses Bearer token authentication.
  version: v2
  contact:
    name: Better Stack Support
    url: https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/
  termsOfService: https://betterstack.com/terms
  license:
    name: Proprietary
    url: https://betterstack.com/terms
servers:
  - url: https://uptime.betterstack.com/api/v2
    description: Better Stack Uptime API v2
  - url: https://uptime.betterstack.com/api/v3
    description: Better Stack Uptime API v3 (incidents)
security:
  - BearerAuth: []
tags:
  - name: Monitors
    description: Manage uptime monitors for websites and services
  - name: Heartbeats
    description: Manage heartbeat monitors for cron jobs and background workers
  - name: Incidents
    description: View and manage incidents triggered by monitors
  - name: Status Pages
    description: Manage public status pages for communicating service health
paths:
  /monitors:
    get:
      operationId: listMonitors
      summary: List monitors
      description: Returns a paginated list of all monitors in your account.
      tags:
        - Monitors
      parameters:
        - name: team_name
          in: query
          description: Filter monitors belonging to a specified team when using global API token
          schema:
            type: string
        - name: url
          in: query
          description: Filter by monitor URL
          schema:
            type: string
        - name: pronounceable_name
          in: query
          description: Filter by monitor pronounceable name
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
      responses:
        '200':
          description: A list of monitors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createMonitor
      summary: Create a monitor
      description: Creates a new uptime monitor.
      tags:
        - Monitors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreateRequest'
      responses:
        '201':
          description: Monitor created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /monitors/{id}:
    get:
      operationId: getMonitor
      summary: Get a monitor
      description: Returns a single monitor by ID.
      tags:
        - Monitors
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: A single monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateMonitor
      summary: Update a monitor
      description: Updates an existing monitor.
      tags:
        - Monitors
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreateRequest'
      responses:
        '200':
          description: Monitor updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: deleteMonitor
      summary: Delete a monitor
      description: Deletes an existing monitor.
      tags:
        - Monitors
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: Monitor deleted
        '404':
          $ref: '#/components/responses/NotFound'
  /heartbeats:
    get:
      operationId: listHeartbeats
      summary: List heartbeats
      description: Returns a paginated list of all heartbeat monitors.
      tags:
        - Heartbeats
      parameters:
        - name: team_name
          in: query
          description: Filter by team name
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
      responses:
        '200':
          description: A list of heartbeats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createHeartbeat
      summary: Create a heartbeat
      description: Creates a new heartbeat monitor.
      tags:
        - Heartbeats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatCreateRequest'
      responses:
        '201':
          description: Heartbeat created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
  /heartbeats/{id}:
    get:
      operationId: getHeartbeat
      summary: Get a heartbeat
      description: Returns a single heartbeat by ID.
      tags:
        - Heartbeats
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: A single heartbeat
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateHeartbeat
      summary: Update a heartbeat
      description: Updates an existing heartbeat monitor.
      tags:
        - Heartbeats
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatCreateRequest'
      responses:
        '200':
          description: Heartbeat updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
    delete:
      operationId: deleteHeartbeat
      summary: Delete a heartbeat
      description: Deletes an existing heartbeat monitor.
      tags:
        - Heartbeats
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: Heartbeat deleted
  /status-pages:
    get:
      operationId: listStatusPages
      summary: List status pages
      description: Returns a list of all your status pages.
      tags:
        - Status Pages
      parameters:
        - name: team_name
          in: query
          description: Filter by team name
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
      responses:
        '200':
          description: A list of status pages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPageListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createStatusPage
      summary: Create a status page
      description: Creates a new status page.
      tags:
        - Status Pages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusPageCreateRequest'
      responses:
        '201':
          description: Status page created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPageResponse'
  /status-pages/{id}:
    get:
      operationId: getStatusPage
      summary: Get a status page
      description: Returns a single status page by ID.
      tags:
        - Status Pages
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: A single status page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPageResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateStatusPage
      summary: Update a status page
      description: Updates an existing status page.
      tags:
        - Status Pages
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusPageCreateRequest'
      responses:
        '200':
          description: Status page updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPageResponse'
    delete:
      operationId: deleteStatusPage
      summary: Delete a status page
      description: Deletes an existing status page.
      tags:
        - Status Pages
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: Status page deleted
  /incidents:
    get:
      operationId: listIncidents
      summary: List incidents
      description: Returns a list of all incidents with optional filtering.
      tags:
        - Incidents
      servers:
        - url: https://uptime.betterstack.com/api/v3
      parameters:
        - name: team_name
          in: query
          description: Filter by team name
          schema:
            type: string
        - name: from
          in: query
          description: Start date for filtering (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: End date for filtering (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: monitor_id
          in: query
          description: Filter by monitor ID
          schema:
            type: string
        - name: heartbeat_id
          in: query
          description: Filter by heartbeat ID
          schema:
            type: string
        - name: resolved
          in: query
          description: Filter by resolved status
          schema:
            type: boolean
        - name: acknowledged
          in: query
          description: Filter by acknowledged status
          schema:
            type: boolean
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
      responses:
        '200':
          description: A list of incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from Better Stack account settings
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: Resource identifier
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Validation errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Pagination:
      type: object
      properties:
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        prev:
          type: string
          format: uri
          nullable: true
        next:
          type: string
          format: uri
          nullable: true
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              detail:
                type: string
    MonitorAttributes:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Website or host to monitor
        pronounceable_name:
          type: string
          description: Human-readable name used in voice alerts
        monitor_type:
          type: string
          enum:
            - status
            - keyword
            - ping
            - tcp
            - udp
            - smtp
            - pop
            - imap
            - dns
            - playwright
          description: The type of check to perform
        monitor_group_id:
          type: string
          nullable: true
          description: Associated monitor group ID
        status:
          type: string
          enum:
            - up
            - down
            - validating
            - paused
            - pending
            - maintenance
          readOnly: true
        last_checked_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        check_frequency:
          type: integer
          description: Check interval in seconds
        request_timeout:
          type: integer
          description: Timeout in milliseconds (ports) or seconds (others)
        recovery_period:
          type: integer
          description: Time in seconds required before auto-resolving an incident
        confirmation_period:
          type: integer
          description: Delay in seconds before creating an incident
        call:
          type: boolean
          description: Enable phone call alerts
        sms:
          type: boolean
          description: Enable SMS alerts
        email:
          type: boolean
          description: Enable email alerts
        push:
          type: boolean
          description: Enable push notification alerts
        critical_alert:
          type: boolean
          description: Enable critical iOS alerts bypassing mute
        team_wait:
          type: integer
          description: Escalation delay in seconds
        policy_id:
          type: string
          nullable: true
          description: Alert policy ID
        expiration_policy_id:
          type: string
          nullable: true
          description: SSL/domain expiration alert policy ID
        verify_ssl:
          type: boolean
          description: Monitor SSL certificate validity
        ssl_expiration:
          type: integer
          nullable: true
          description: Alert days before SSL certificate expiry
        domain_expiration:
          type: integer
          nullable: true
          description: Alert days before domain expiry
        regions:
          type: array
          items:
            type: string
          description: Geographic regions to check from
        maintenance_from:
          type: string
          description: Maintenance window start time (HH:MM)
        maintenance_to:
          type: string
          description: Maintenance window end time (HH:MM)
        maintenance_timezone:
          type: string
          description: Timezone for maintenance window
        maintenance_days:
          type: array
          items:
            type: string
          description: Days of week for maintenance window
        proxy_host:
          type: string
          nullable: true
          description: Proxy host for check requests
        proxy_port:
          type: integer
          nullable: true
          description: Proxy port for check requests
        request_headers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
          description: Custom HTTP request headers
        request_body:
          type: string
          nullable: true
          description: Custom HTTP request body
        expected_status_codes:
          type: array
          items:
            type: integer
          description: HTTP status codes that indicate success
        required_keyword:
          type: string
          nullable: true
          description: Keyword that must be present in the response
        port:
          type: integer
          nullable: true
          description: Port number for TCP/UDP/SMTP/POP/IMAP checks
        playwright_script:
          type: string
          nullable: true
          description: Playwright script for synthetic monitoring
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        paused_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
    MonitorResource:
      type: object
      properties:
        id:
          type: string
          description: Monitor identifier
        type:
          type: string
          enum:
            - monitor
        attributes:
          $ref: '#/components/schemas/MonitorAttributes'
    MonitorResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MonitorResource'
    MonitorListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MonitorResource'
        pagination:
          $ref: '#/components/schemas/Pagination'
    MonitorCreateRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        pronounceable_name:
          type: string
        monitor_type:
          type: string
          enum:
            - status
            - keyword
            - ping
            - tcp
            - udp
            - smtp
            - pop
            - imap
            - dns
            - playwright
        check_frequency:
          type: integer
        request_timeout:
          type: integer
        recovery_period:
          type: integer
        confirmation_period:
          type: integer
        call:
          type: boolean
        sms:
          type: boolean
        email:
          type: boolean
        push:
          type: boolean
        regions:
          type: array
          items:
            type: string
        verify_ssl:
          type: boolean
        ssl_expiration:
          type: integer
        domain_expiration:
          type: integer
        expected_status_codes:
          type: array
          items:
            type: integer
        required_keyword:
          type: string
        request_headers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
        request_body:
          type: string
        policy_id:
          type: string
        port:
          type: integer
    HeartbeatAttributes:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Unique ping URL for the heartbeat
          readOnly: true
        name:
          type: string
          description: Heartbeat name
        period:
          type: integer
          description: Expected ping interval in seconds
        grace:
          type: integer
          description: Grace period in seconds before alerting
        call:
          type: boolean
        sms:
          type: boolean
        email:
          type: boolean
        push:
          type: boolean
        team_wait:
          type: integer
          description: Escalation delay in seconds
        heartbeat_group_id:
          type: string
          nullable: true
        team_name:
          type: string
        paused_at:
          type: string
          format: date-time
          nullable: true
        server_timezone:
          type: string
          nullable: true
        maintenance_from:
          type: string
        maintenance_to:
          type: string
        maintenance_timezone:
          type: string
        maintenance_days:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - paused
            - pending
            - up
            - down
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    HeartbeatResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - heartbeat
        attributes:
          $ref: '#/components/schemas/HeartbeatAttributes'
    HeartbeatResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/HeartbeatResource'
    HeartbeatListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/HeartbeatResource'
        pagination:
          $ref: '#/components/schemas/Pagination'
    HeartbeatCreateRequest:
      type: object
      required:
        - name
        - period
        - grace
      properties:
        name:
          type: string
        period:
          type: integer
        grace:
          type: integer
        call:
          type: boolean
        sms:
          type: boolean
        email:
          type: boolean
        push:
          type: boolean
        team_wait:
          type: integer
        heartbeat_group_id:
          type: string
    IncidentAttributes:
      type: object
      properties:
        name:
          type: string
          description: Incident name
        cause:
          type: string
          description: Root cause description
        status:
          type: string
          description: Current incident status
        started_at:
          type: string
          format: date-time
        acknowledged_at:
          type: string
          format: date-time
          nullable: true
        resolved_at:
          type: string
          format: date-time
          nullable: true
        acknowledged_by:
          type: string
          nullable: true
        resolved_by:
          type: string
          nullable: true
        team_name:
          type: string
        url:
          type: string
          format: uri
        http_method:
          type: string
        call:
          type: boolean
        sms:
          type: boolean
        email:
          type: boolean
        push:
          type: boolean
        regions:
          type: array
          items:
            type: string
        response_content:
          type: string
          nullable: true
        screenshot_url:
          type: string
          format: uri
          nullable: true
        metadata:
          type: object
          additionalProperties: true
    IncidentResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - incident
        attributes:
          $ref: '#/components/schemas/IncidentAttributes'
    IncidentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/IncidentResource'
        pagination:
          $ref: '#/components/schemas/Pagination'
    StatusPageAttributes:
      type: object
      properties:
        company_name:
          type: string
        company_url:
          type: string
          format: uri
        subdomain:
          type: string
        custom_domain:
          type: string
          nullable: true
        timezone:
          type: string
        theme:
          type: string
          enum:
            - light
            - dark
        layout:
          type: string
          enum:
            - vertical
            - horizontal
        aggregate_state:
          type: string
          enum:
            - operational
            - degraded_performance
            - partial_outage
            - major_outage
          readOnly: true
        subscribable:
          type: boolean
        password_enabled:
          type: boolean
        ip_allowlist:
          type: array
          items:
            type: string
        history:
          type: integer
          description: Incident history retention in days
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    StatusPageResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - status_page
        attributes:
          $ref: '#/components/schemas/StatusPageAttributes'
    StatusPageResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/StatusPageResource'
    StatusPageListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/StatusPageResource'
        pagination:
          $ref: '#/components/schemas/Pagination'
    StatusPageCreateRequest:
      type: object
      required:
        - company_name
        - subdomain
      properties:
        company_name:
          type: string
        company_url:
          type: string
          format: uri
        subdomain:
          type: string
        custom_domain:
          type: string
        timezone:
          type: string
        theme:
          type: string
          enum:
            - light
            - dark
        layout:
          type: string
          enum:
            - vertical
            - horizontal
        subscribable:
          type: boolean
        password_enabled:
          type: boolean
        history:
          type: integer