Cronitor Monitors API

openapi: 3.0.3
info:
  title: Cronitor Groups and Notifications Cronitor Telemetry API Monitors API
  description: The Groups API manages logical groupings of monitors for bulk operations and reporting. The Notifications API manages notification lists (alert routing) that specify where alerts are sent when monitors fire. Both APIs use HTTP Basic Auth with a Cronitor API key.
  version: v1
  contact:
    name: Cronitor Support
    url: https://cronitor.io/docs/groups-api
  license:
    name: Proprietary
    url: https://cronitor.io
servers:
- url: https://cronitor.io
  description: Cronitor production server
security:
- basicAuth: []
tags:
- name: Monitors
paths:
  /api/monitors:
    get:
      operationId: listMonitors
      summary: List monitors
      description: Returns a paginated list of monitors, with optional filtering.
      parameters:
      - name: type
        in: query
        schema:
          type: string
          enum:
          - job
          - check
          - heartbeat
          - site
      - name: group
        in: query
        schema:
          type: string
      - name: tag
        in: query
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
      - name: env
        in: query
        schema:
          type: string
      - name: search
        in: query
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          default: 50
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - created
          - name
          - -created
          - -name
      - name: withEvents
        in: query
        schema:
          type: boolean
      - name: withInvocations
        in: query
        schema:
          type: boolean
      - name: format
        in: query
        schema:
          type: string
          enum:
          - yaml
      responses:
        '200':
          description: Successful list response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListResponse'
        '403':
          description: Forbidden – invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Monitors
    post:
      operationId: createMonitor
      summary: Create a monitor
      description: Creates a single monitor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Monitor'
          application/yaml:
            schema:
              $ref: '#/components/schemas/BulkMonitorRequest'
      responses:
        '201':
          description: Monitor created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Monitors
    put:
      operationId: bulkUpsertMonitors
      summary: Bulk create or update monitors
      description: Creates or updates multiple monitors in a single request. Accepts JSON or YAML.
      parameters:
      - name: async
        in: query
        schema:
          type: boolean
        description: If true, returns 202 Accepted immediately and processes asynchronously.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMonitorRequest'
          application/yaml:
            schema:
              $ref: '#/components/schemas/BulkMonitorRequest'
      responses:
        '200':
          description: Monitors upserted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListResponse'
        '202':
          description: Accepted for async processing.
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Monitors
    delete:
      operationId: bulkDeleteMonitors
      summary: Bulk delete monitors
      description: Deletes multiple monitors specified in the request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                monitors:
                  type: array
                  items:
                    type: string
                  description: Array of monitor keys to delete.
      responses:
        '200':
          description: Monitors deleted.
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Monitors
  /api/monitors/{monitorKey}:
    parameters:
    - name: monitorKey
      in: path
      required: true
      schema:
        type: string
      description: Unique monitor key.
    get:
      operationId: getMonitor
      summary: Get a monitor
      description: Retrieves a single monitor by key.
      parameters:
      - name: withEvents
        in: query
        schema:
          type: boolean
      - name: withInvocations
        in: query
        schema:
          type: boolean
      - name: env
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Monitor object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '403':
          description: Forbidden.
        '404':
          description: Monitor not found.
      tags:
      - Monitors
    delete:
      operationId: deleteMonitor
      summary: Delete a monitor
      description: Deletes a single monitor by key.
      responses:
        '204':
          description: Monitor deleted.
        '403':
          description: Forbidden.
        '404':
          description: Monitor not found.
      tags:
      - Monitors
  /api/monitors/{monitorKey}/pause/{hours}:
    parameters:
    - name: monitorKey
      in: path
      required: true
      schema:
        type: string
    - name: hours
      in: path
      required: true
      schema:
        type: string
      description: Number of hours to pause; use 0 to resume. Omit for indefinite pause.
    get:
      operationId: pauseMonitor
      summary: Pause or resume a monitor
      description: Pauses a monitor for the specified number of hours, or resumes it if hours is 0.
      responses:
        '200':
          description: Updated monitor object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '403':
          description: Forbidden.
        '404':
          description: Monitor not found.
      tags:
      - Monitors
  /api/monitors/clone:
    post:
      operationId: cloneMonitor
      summary: Clone a monitor
      description: Duplicates an existing monitor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneRequest'
      responses:
        '201':
          description: Cloned monitor object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Validation error.
        '403':
          description: Forbidden.
        '404':
          description: Source monitor not found.
      tags:
      - Monitors
components:
  schemas:
    MonitorListResponse:
      type: object
      properties:
        page:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 50
        count:
          type: integer
          example: 12
        monitors:
          type: array
          items:
            $ref: '#/components/schemas/Monitor'
    Monitor:
      type: object
      required:
      - key
      - type
      properties:
        key:
          type: string
          description: Unique monitor identifier.
          example: my-daily-backup
        name:
          type: string
          description: Human-readable display name.
          example: Daily Backup Job
        type:
          type: string
          enum:
          - job
          - check
          - heartbeat
          - site
          description: Monitor type.
        schedule:
          type: string
          description: Cron, interval, or time expression.
          example: 0 2 * * *
        schedules:
          type: array
          items:
            type: string
          description: Multiple schedule expressions.
        timezone:
          type: string
          description: IANA timezone string; defaults to account timezone.
          example: America/New_York
        assertions:
          type: array
          items:
            type: string
          description: Assertions validating metrics, response codes, body content, JSON fields, headers, or SSL certificates.
        notify:
          type: array
          items:
            type: string
          description: Notification list keys or direct integration strings.
          example:
          - devops-team
          - email:oncall@example.com
        realert_interval:
          type: string
          description: Follow-up alert timing (e.g. "1 hour").
          example: 1 hour
        grace_seconds:
          type: integer
          description: Pre-alert delay window in seconds.
          example: 60
        failure_tolerance:
          type: integer
          description: Consecutive failures tolerated before alerting.
          example: 0
        consecutive_alert_threshold:
          type: integer
          description: Failures before an alert fires.
          example: 1
        paused:
          type: boolean
          description: Whether the monitor is currently paused.
          example: false
        url:
          type: string
          format: uri
          description: URL to check (for check/site monitors).
          example: https://example.com/health
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - HEAD
          - OPTIONS
          - PATCH
          description: HTTP method for check monitors.
        body:
          type: string
          description: HTTP request body for check monitors.
        headers:
          type: object
          additionalProperties:
            type: string
          description: HTTP headers for check monitors.
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 15
          description: Request timeout for check monitors.
        follow_redirects:
          type: boolean
          description: Whether to follow HTTP redirects.
        verify_ssl:
          type: boolean
          description: Whether to verify SSL certificates.
        tags:
          type: array
          items:
            type: string
          description: Tags for grouping and filtering monitors.
        group:
          type: string
          description: Group key this monitor belongs to.
        env:
          type: string
          description: Environment identifier.
        created:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 creation timestamp.
        latest_event:
          type: object
          readOnly: true
          properties:
            stamp:
              type: integer
              description: Unix timestamp of the last event.
            state:
              type: string
              description: State of the last event.
        latest_issue:
          type: object
          nullable: true
          readOnly: true
          description: Most recent issue object, or null.
    CloneRequest:
      type: object
      required:
      - monitor_key
      properties:
        monitor_key:
          type: string
          description: Key of the monitor to clone.
        name:
          type: string
          description: Name for the cloned monitor.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message.
        errors:
          type: array
          items:
            type: string
          description: List of validation errors.
    BulkMonitorRequest:
      type: object
      description: Bulk monitor create/update payload.
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Monitor'
        checks:
          type: array
          items:
            $ref: '#/components/schemas/Monitor'
        heartbeats:
          type: array
          items:
            $ref: '#/components/schemas/Monitor'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your Cronitor API key as the username; leave the password blank.