openapi: 3.0.3
info:
  title: Better Stack Escalation Policies Monitors API
  description: Better Stack is a comprehensive infrastructure monitoring and observability platform combining uptime monitoring, log management, incident management, and status pages. The API covers both the Uptime (on-call, monitors, heartbeats, status pages) and Telemetry (logs, metrics, sources, dashboards, alerts) product areas.
  version: v2
  contact:
    name: Better Stack Support
    url: https://betterstack.com/docs/
  x-generated-from: documentation
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, policies)
- url: https://betterstack.com/api/v2
  description: Better Stack Telemetry API v2
security:
- bearerAuth: []
tags:
- name: Monitors
  description: Manage uptime monitors for URLs, APIs, and services
paths:
  /monitors:
    get:
      operationId: listMonitors
      summary: Better Stack List Monitors
      description: Returns a paginated list of all monitors for the authenticated team.
      tags:
      - Monitors
      parameters:
      - name: team_name
        in: query
        description: Filter monitors belonging to a specified team when using a global API token.
        required: false
        schema:
          type: string
        example: my-team
      - name: url
        in: query
        description: Filter monitors by target URL.
        required: false
        schema:
          type: string
        example: https://example.com
      - name: pronounceable_name
        in: query
        description: Filter monitors by pronounceable name.
        required: false
        schema:
          type: string
        example: Production API
      responses:
        '200':
          description: Paginated list of monitors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListResponse'
              examples:
                ListMonitors200Example:
                  summary: Default listMonitors 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: '123456'
                      type: monitor
                      attributes:
                        url: https://example.com
                        pronounceable_name: Production API
                        monitor_type: status
                        status: up
                        check_frequency: 180
                        verify_ssl: true
                        call: false
                        sms: true
                        email: true
                        push: true
                        regions:
                        - us
                        - eu
                        created_at: '2025-01-15T10:00:00Z'
                        updated_at: '2026-04-01T08:30:00Z'
                    pagination:
                      first: https://uptime.betterstack.com/api/v2/monitors?page=1
                      last: https://uptime.betterstack.com/api/v2/monitors?page=5
                      prev: null
                      next: https://uptime.betterstack.com/api/v2/monitors?page=2
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMonitor
      summary: Better Stack Create Monitor
      description: Creates a new uptime monitor.
      tags:
      - Monitors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreateRequest'
            examples:
              CreateMonitorRequestExample:
                summary: Default createMonitor request
                x-microcks-default: true
                value:
                  url: https://example.com
                  pronounceable_name: Production API
                  monitor_type: status
                  check_frequency: 180
                  verify_ssl: true
                  email: true
                  sms: false
                  call: false
                  push: true
                  regions:
                  - us
                  - eu
      responses:
        '201':
          description: Monitor created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorSingleResponse'
              examples:
                CreateMonitor201Example:
                  summary: Default createMonitor 201 response
                  x-microcks-default: true
                  value:
                    data:
                      id: '500123'
                      type: monitor
                      attributes:
                        url: https://example.com
                        pronounceable_name: Production API
                        monitor_type: status
                        status: pending
                        check_frequency: 180
                        verify_ssl: true
                        call: false
                        sms: false
                        email: true
                        push: true
                        regions:
                        - us
                        - eu
                        created_at: '2026-04-19T10:00:00Z'
                        updated_at: '2026-04-19T10:00:00Z'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /monitors/{id}:
    get:
      operationId: getMonitor
      summary: Better Stack Get Monitor
      description: Returns a single monitor by ID.
      tags:
      - Monitors
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the monitor.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Monitor details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorSingleResponse'
              examples:
                GetMonitor200Example:
                  summary: Default getMonitor 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: '500123'
                      type: monitor
                      attributes:
                        url: https://example.com
                        pronounceable_name: Production API
                        monitor_type: status
                        status: up
                        check_frequency: 180
                        verify_ssl: true
                        call: false
                        sms: true
                        email: true
                        push: true
                        regions:
                        - us
                        - eu
                        created_at: '2025-01-15T10:00:00Z'
                        updated_at: '2026-04-01T08:30:00Z'
        '404':
          description: Monitor not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateMonitor
      summary: Better Stack Update Monitor
      description: Updates an existing monitor.
      tags:
      - Monitors
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the monitor.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorUpdateRequest'
            examples:
              UpdateMonitorRequestExample:
                summary: Default updateMonitor request
                x-microcks-default: true
                value:
                  pronounceable_name: Updated API Monitor
                  check_frequency: 300
      responses:
        '200':
          description: Monitor updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorSingleResponse'
              examples:
                UpdateMonitor200Example:
                  summary: Default updateMonitor 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: '500123'
                      type: monitor
                      attributes:
                        url: https://example.com
                        pronounceable_name: Updated API Monitor
                        monitor_type: status
                        status: up
                        check_frequency: 300
                        verify_ssl: true
                        call: false
                        sms: true
                        email: true
                        push: true
                        regions:
                        - us
                        - eu
                        created_at: '2025-01-15T10:00:00Z'
                        updated_at: '2026-04-19T10:00:00Z'
        '404':
          description: Monitor not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMonitor
      summary: Better Stack Delete Monitor
      description: Deletes an existing monitor.
      tags:
      - Monitors
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the monitor.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: Monitor deleted successfully.
        '404':
          description: Monitor not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /monitors/{id}/response-times:
    get:
      operationId: getMonitorResponseTimes
      summary: Better Stack Get Monitor Response Times
      description: Returns response time metrics for a specific monitor.
      tags:
      - Monitors
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the monitor.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Response time data for the monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseTimesResponse'
              examples:
                GetMonitorResponseTimes200Example:
                  summary: Default getMonitorResponseTimes 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - at: '2026-04-19T10:00:00Z'
                      response_time: 142
                      region: us
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /monitors/{id}/availability:
    get:
      operationId: getMonitorAvailability
      summary: Better Stack Get Monitor Availability
      description: Returns availability summary for a specific monitor.
      tags:
      - Monitors
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the monitor.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Availability summary for the monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'
              examples:
                GetMonitorAvailability200Example:
                  summary: Default getMonitorAvailability 200 response
                  x-microcks-default: true
                  value:
                    data:
                      availability: 99.98
                      downtime_duration: 86
                      number_of_incidents: 2
                      longest_incident_duration: 61
                      average_incident_duration: 43
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AvailabilityResponse:
      title: Availability Response
      description: Availability summary metrics.
      type: object
      properties:
        data:
          type: object
          properties:
            availability:
              type: number
              description: Availability percentage.
              example: 99.98
            downtime_duration:
              type: integer
              description: Total downtime duration in seconds.
              example: 86
            number_of_incidents:
              type: integer
              description: Number of incidents in the period.
              example: 2
            longest_incident_duration:
              type: integer
              description: Duration of the longest incident in seconds.
              example: 61
            average_incident_duration:
              type: integer
              description: Average incident duration in seconds.
              example: 43
    MonitorObject:
      title: Monitor Object
      description: A single monitor resource following JSON:API format.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the monitor.
          example: '500123'
        type:
          type: string
          description: Resource type identifier.
          example: monitor
        attributes:
          $ref: '#/components/schemas/MonitorAttributes'
    MonitorListResponse:
      title: Monitor List Response
      description: Paginated list of monitors.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MonitorObject'
        pagination:
          $ref: '#/components/schemas/Pagination'
    MonitorCreateRequest:
      title: Monitor Create Request
      description: Request body for creating a new monitor.
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: The URL to monitor.
          example: https://example.com
        pronounceable_name:
          type: string
          description: Human-readable name for the monitor.
          example: Production API
        monitor_type:
          type: string
          description: Type of monitoring check.
          enum:
          - status
          - expected_status_code
          - keyword
          - keyword_absence
          - ping
          - tcp
          example: status
        check_frequency:
          type: integer
          description: Check interval in seconds.
          example: 180
        verify_ssl:
          type: boolean
          description: Whether to verify SSL certificate.
          example: true
        email:
          type: boolean
          description: Alert via email.
          example: true
        sms:
          type: boolean
          description: Alert via SMS.
          example: false
        call:
          type: boolean
          description: Alert via phone call.
          example: false
        push:
          type: boolean
          description: Alert via push notification.
          example: true
        regions:
          type: array
          items:
            type: string
          description: Regions to monitor from.
          example:
          - us
          - eu
        policy_id:
          type: string
          nullable: true
          description: Escalation policy ID.
          example: '300010'
    ErrorResponse:
      title: Error Response
      description: Standard error response.
      type: object
      properties:
        errors:
          type: array
          description: List of error details.
          items:
            type: object
            properties:
              title:
                type: string
                description: Human-readable error title.
                example: Unauthorized
              detail:
                type: string
                description: Detailed error message.
                example: Invalid API token
    MonitorUpdateRequest:
      title: Monitor Update Request
      description: Request body for updating an existing monitor (all fields optional).
      type: object
      properties:
        url:
          type: string
          format: uri
          description: New URL to monitor.
          example: https://example.com
        pronounceable_name:
          type: string
          description: New human-readable name.
          example: Updated API Monitor
        check_frequency:
          type: integer
          description: New check interval in seconds.
          example: 300
        verify_ssl:
          type: boolean
          description: SSL verification setting.
          example: true
        email:
          type: boolean
          description: Alert via email.
          example: true
        sms:
          type: boolean
          description: Alert via SMS.
          example: false
        call:
          type: boolean
          description: Alert via phone call.
          example: false
        push:
          type: boolean
          description: Alert via push notification.
          example: true
    Pagination:
      title: Pagination
      description: Pagination links for list responses following JSON:API specification.
      type: object
      properties:
        first:
          type: string
          format: uri
          description: URL of the first page.
          example: https://uptime.betterstack.com/api/v2/monitors?page=1
        last:
          type: string
          format: uri
          description: URL of the last page.
          example: https://uptime.betterstack.com/api/v2/monitors?page=5
        prev:
          type: string
          format: uri
          nullable: true
          description: URL of the previous page, or null.
          example: null
        next:
          type: string
          format: uri
          nullable: true
          description: URL of the next page, or null.
          example: https://uptime.betterstack.com/api/v2/monitors?page=2
    ResponseTimesResponse:
      title: Response Times Response
      description: Response time metrics for a monitor.
      type: object
      properties:
        data:
          type: array
          description: Array of response time data points.
          items:
            type: object
            properties:
              at:
                type: string
                format: date-time
                description: Timestamp of the measurement.
                example: '2026-04-19T10:00:00Z'
              response_time:
                type: integer
                description: Response time in milliseconds.
                example: 142
              region:
                type: string
                description: Region where the check was performed.
                example: us
    MonitorAttributes:
      title: Monitor Attributes
      description: Attributes of an uptime monitor.
      type: object
      properties:
        url:
          type: string
          format: uri
          description: The URL being monitored.
          example: https://example.com
        pronounceable_name:
          type: string
          description: Human-readable name for the monitor.
          example: Production API
        monitor_type:
          type: string
          description: Type of monitoring check.
          enum:
          - status
          - expected_status_code
          - keyword
          - keyword_absence
          - ping
          - tcp
          - udp
          - smtp
          - pop
          - imap
          example: status
        status:
          type: string
          description: Current operational status of the monitor.
          enum:
          - paused
          - pending
          - maintenance
          - up
          - validating
          - down
          example: up
        monitor_group_id:
          type: string
          nullable: true
          description: ID of the monitor group this monitor belongs to.
          example: null
        policy_id:
          type: string
          nullable: true
          description: ID of the escalation policy for this monitor.
          example: '300010'
        check_frequency:
          type: integer
          description: How often to check the URL in seconds.
          example: 180
        verify_ssl:
          type: boolean
          description: Whether to verify SSL certificate validity.
          example: true
        ssl_expiration:
          type: integer
          nullable: true
          description: Days before SSL expiration to start alerting.
          example: 30
        call:
          type: boolean
          description: Whether to alert via phone call.
          example: false
        sms:
          type: boolean
          description: Whether to alert via SMS.
          example: true
        email:
          type: boolean
          description: Whether to alert via email.
          example: true
        push:
          type: boolean
          description: Whether to alert via push notification.
          example: true
        regions:
          type: array
          description: Geographic regions from which to check the monitor.
          items:
            type: string
          example:
          - us
          - eu
        created_at:
          type: string
          format: date-time
          description: When the monitor was created.
          example: '2025-01-15T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the monitor was last updated.
          example: '2026-04-01T08:30:00Z'
        paused_at:
          type: string
          format: date-time
          nullable: true
          description: When the monitor was paused, if applicable.
          example: null
    MonitorSingleResponse:
      title: Monitor Single Response
      description: Single monitor response.
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MonitorObject'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use a global API token or a team-scoped Uptime API token obtained from Better Stack Settings → API tokens.