Datadog Monitor Muting API

openapi: 3.2.0
info:
  title: Datadog Monitors Monitor Muting API
  description: The Datadog Monitors API allows you to create, update, delete, and mute monitors that watch a metric or check and notify your team when a defined threshold has been exceeded. Monitors support a variety of types including metric threshold, anomaly detection, outlier detection, forecasting, composite, service check, event, log, and APM monitors. Each monitor can have customizable notification channels, escalation policies, and scheduling for downtime.
  version: v1
  contact:
    name: Datadog Support
    url: https://www.datadoghq.com/support/
  termsOfService: https://www.datadoghq.com/legal/terms/
servers:
- url: https://api.datadoghq.com
  description: Datadog API Production Server
security:
- apiKeyAuth: []
- appKeyAuth: []
tags:
- name: Monitor Muting
  description: Mute and unmute monitors to suppress notifications
paths:
  /api/v1/monitor/{monitor_id}/mute:
    post:
      operationId: muteMonitor
      summary: Datadog Mute a Monitor
      description: Mutes the specified monitor to suppress alert notifications for all groups or specific scopes. Optionally specify an end time after which the monitor automatically unmutes. While muted, the monitor continues to evaluate the query but does not send alert notifications. Useful for planned maintenance or known issues.
      tags:
      - Monitor Muting
      parameters:
      - $ref: '#/components/parameters/monitorIdParam'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorMuteSettings'
      responses:
        '200':
          description: Successfully muted monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Bad request - invalid mute settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions to mute this monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - monitor with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/monitor/{monitor_id}/unmute:
    post:
      operationId: unmuteMonitor
      summary: Datadog Unmute a Monitor
      description: Unmutes a previously muted monitor to resume alert notifications. Optionally specify a scope to unmute only specific groups. If no scope is specified, the monitor is unmuted globally across all groups. Notifications resume immediately for any groups that are in an alert or warning state.
      tags:
      - Monitor Muting
      parameters:
      - $ref: '#/components/parameters/monitorIdParam'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorUnmuteSettings'
      responses:
        '200':
          description: Successfully unmuted monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Bad request - invalid unmute settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions to unmute this monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - monitor with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Monitor:
      type: object
      description: A Datadog monitor that watches a metric or check and alerts when thresholds are exceeded
      required:
      - type
      - query
      - name
      - message
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier of the monitor, assigned by Datadog upon creation
          example: 42
        type:
          type: string
          description: The type of monitor that determines the query language and alerting behavior
          enum:
          - composite
          - event alert
          - log alert
          - metric alert
          - process alert
          - query alert
          - rum alert
          - service check
          - synthetics alert
          - trace-analytics alert
          - slo alert
          - event-v2 alert
          - audit alert
          - ci-pipelines alert
          - ci-tests alert
          - error-tracking alert
          - database-monitoring alert
          - network-performance alert
          example: composite
        query:
          type: string
          description: The monitor query expression using Datadog's query language for the specified monitor type
          example: avg:system.cpu.user{*}
        name:
          type: string
          description: A descriptive name for the monitor used for identification in dashboards and notifications
          example: Example Monitor
        message:
          type: string
          description: The notification message body sent when the monitor triggers, supports template variables and @-mentions
          example: CPU usage is high on {{host.name}}
        tags:
          type: array
          description: List of tags to associate with the monitor for filtering and organization
          items:
            type: string
        options:
          $ref: '#/components/schemas/MonitorOptions'
        priority:
          type: integer
          description: The monitor priority level from 1 (highest) to 5 (lowest), used for sorting and filtering
          minimum: 1
          maximum: 5
          example: 42
        state:
          $ref: '#/components/schemas/MonitorState'
        creator:
          $ref: '#/components/schemas/Creator'
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the monitor was created
          example: example_value
        modified:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the monitor was last modified
          example: example_value
        deleted:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 timestamp when the monitor was deleted, or null if not deleted
          example: example_value
        restricted_roles:
          type: array
          description: List of role IDs whose members can edit this monitor; empty means all users can edit
          items:
            type: string
    MonitorGroupState:
      type: object
      description: The state of a single monitor group (a unique combination of tag values)
      properties:
        status:
          type: string
          description: The current alert status for this monitor group
          enum:
          - Alert
          - Ignored
          - No Data
          - OK
          - Skipped
          - Unknown
          - Warn
          example: Alert
        name:
          type: string
          description: The name of the monitor group, represented as a comma-separated list of tag:value pairs
          example: Example Monitor
        last_triggered_ts:
          type: integer
          format: int64
          description: Unix timestamp in seconds of the last time this group triggered an alert
          example: 42
        last_notified_ts:
          type: integer
          format: int64
          description: Unix timestamp in seconds of the last time a notification was sent for this group
          example: 42
        last_resolved_ts:
          type: integer
          format: int64
          description: Unix timestamp in seconds of the last time this group resolved from an alert state
          example: 42
    APIErrorResponse:
      type: object
      description: Standard API error response returned for failed requests
      required:
      - errors
      properties:
        errors:
          type: array
          description: List of error messages describing the failure
          items:
            type: string
    MonitorUnmuteSettings:
      type: object
      description: Settings for unmuting a monitor including optional scope
      properties:
        scope:
          type: string
          description: The scope expression specifying which monitor groups to unmute; omit to unmute all groups
          example: example_value
        all_scopes:
          type: boolean
          description: When true, unmutes all scopes including those previously muted with different scope expressions
          example: true
    Creator:
      type: object
      description: Information about the user who created the monitor
      properties:
        id:
          type: integer
          description: The unique numeric ID of the creator user
          example: 42
        name:
          type: string
          description: The display name of the creator user
          example: Example Monitor
        email:
          type: string
          format: email
          description: The email address of the creator user
          example: user@example.com
        handle:
          type: string
          description: The Datadog handle (username) of the creator user
          example: example_value
    MonitorMuteSettings:
      type: object
      description: Settings for muting a monitor including scope and expiration
      properties:
        scope:
          type: string
          description: The scope expression specifying which monitor groups to mute (e.g., env:prod, host:web-01)
          example: example_value
        end:
          type: integer
          format: int64
          description: Unix timestamp in seconds when the mute expires; omit for indefinite mute
          example: 42
    MonitorOptions:
      type: object
      description: Configuration options for a monitor controlling evaluation, notification, and recovery behavior
      properties:
        thresholds:
          $ref: '#/components/schemas/MonitorThresholds'
        notify_no_data:
          type: boolean
          description: Whether to send a notification when there is no data for the monitored metric
          default: false
          example: true
        no_data_timeframe:
          type: integer
          description: The number of minutes after which the monitor reports no data (minimum 2x the evaluation timeframe)
          example: 42
        require_full_window:
          type: boolean
          description: Whether the monitor requires a full evaluation window of data before alerting
          example: true
        notify_audit:
          type: boolean
          description: Whether to send notifications to auditors when the monitor is changed
          example: true
        renotify_interval:
          type: integer
          description: The number of minutes between re-notifications while the monitor remains in an alert state (0 to disable)
          example: 42
        renotify_statuses:
          type: array
          description: Monitor status types that trigger re-notification messages
          items:
            type: string
            enum:
            - alert
            - warn
            - no data
        escalation_message:
          type: string
          description: The message to include with re-notification alerts instead of the main message
          example: CPU usage is high on {{host.name}}
        timeout_h:
          type: integer
          description: The number of hours after which an automatically resolving alert times out
          example: 42
        evaluation_delay:
          type: integer
          description: The time in seconds to delay evaluation, used to ensure all data arrives before checking thresholds
          example: 42
        new_group_delay:
          type: integer
          description: The number of seconds to delay notification for new monitor groups to allow transient issues to resolve
          example: 42
        include_tags:
          type: boolean
          description: Whether to include group scope tags in notification subject and body
          default: true
          example: true
        silenced:
          type: object
          description: Map of monitor scopes to Unix timestamps indicating when each scope's mute expires (0 for indefinite)
          additionalProperties:
            type: integer
            nullable: true
        aggregation:
          type: object
          description: Aggregation settings used for anomaly and outlier monitors
          properties:
            type:
              type: string
              description: The type of aggregation function applied to the metric
            metric:
              type: string
              description: The metric name used in the aggregation
            group_by:
              type: string
              description: The tag key to group the aggregation by
    MonitorThresholds:
      type: object
      description: Alert threshold values for metric and service check monitors
      properties:
        critical:
          type: number
          format: double
          description: The threshold value that triggers a CRITICAL alert notification
          example: 95.5
        critical_recovery:
          type: number
          format: double
          description: The threshold value at which a CRITICAL alert recovers to OK state
          example: 95.5
        warning:
          type: number
          format: double
          description: The threshold value that triggers a WARNING alert notification
          example: 95.5
        warning_recovery:
          type: number
          format: double
          description: The threshold value at which a WARNING alert recovers to OK state
          example: 95.5
        ok:
          type: number
          format: double
          description: The threshold for service check monitors indicating an OK state (used with service check monitors)
          example: 95.5
        unknown:
          type: number
          format: double
          description: The threshold for service check monitors indicating an UNKNOWN state
          example: 95.5
    MonitorState:
      type: object
      description: The current evaluation state of the monitor across all groups
      properties:
        groups:
          type: object
          description: Map of monitor group names to their current state information
          additionalProperties:
            $ref: '#/components/schemas/MonitorGroupState'
  parameters:
    monitorIdParam:
      name: monitor_id
      in: path
      required: true
      description: The unique numeric ID of the monitor to operate on
      schema:
        type: integer
        format: int64
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: DD-API-KEY
      description: Datadog API key for authenticating requests
    appKeyAuth:
      type: apiKey
      in: header
      name: DD-APPLICATION-KEY
      description: Datadog application key for write operations and sensitive read operations
externalDocs:
  description: Datadog Monitors API Documentation
  url: https://docs.datadoghq.com/api/latest/monitors/