openapi: 3.0.3
info:
  title: Cronitor Monitors API
  description: >-
    The Monitors API allows creating, updating, retrieving, deleting, cloning,
    and pausing monitors for cron jobs, heartbeats, uptime checks, and sites.
    Monitors are configured with schedules, assertions, and alert preferences
    via JSON or YAML payloads authenticated with HTTP Basic Auth using an API key.
  version: v1
  contact:
    name: Cronitor Support
    url: https://cronitor.io/docs/monitors-api
  license:
    name: Proprietary
    url: https://cronitor.io
servers:
  - url: https://cronitor.io
    description: Cronitor production server

security:
  - basicAuth: []

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your Cronitor API key as the username; leave the password blank.

  schemas:
    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.

    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'

    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'

    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.

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'

    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'

    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'

    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'

  /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.

    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.

  /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.

  /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.

  /api/search:
    get:
      operationId: searchMonitors
      summary: Advanced monitor search
      description: Search monitors using scoped query syntax.
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Scoped search query.
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListResponse'
        '403':
          description: Forbidden.