openapi: 3.0.0
info:
contact:
email: support@datadoghq.com
name: Datadog Support
url: https://www.datadoghq.com/support/
description: The Datadog API is an HTTP REST API. The API uses resource-oriented URLs to call the API, uses status codes to indicate the success or failure of requests, returns JSON from all requests, and uses standard HTTP response codes. Use the Datadog API to access the Datadog platform programmatically.
title: Datadog Account Monitor Muting API
version: '1.0'
servers:
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: The regional site for Datadog customers.
enum:
- datadoghq.com
- us3.datadoghq.com
- us5.datadoghq.com
- ap1.datadoghq.com
- datadoghq.eu
- ddog-gov.com
subdomain:
default: api
description: The subdomain where the API is deployed.
- url: '{protocol}://{name}'
variables:
name:
default: api.datadoghq.com
description: Full site DNS name.
protocol:
default: https
description: The protocol for accessing the API.
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: Any Datadog deployment.
subdomain:
default: api
description: The subdomain where the API is deployed.
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:
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
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
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'
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
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
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
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
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
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:
AuthZ:
description: This API uses OAuth 2 with the implicit grant flow.
flows:
authorizationCode:
authorizationUrl: /oauth2/v1/authorize
scopes:
apm_api_catalog_read: View API catalog and API definitions.
apm_api_catalog_write: Add, modify, and delete API catalog definitions.
apm_read: Read and query APM and Trace Analytics.
apm_service_catalog_read: View service catalog and service definitions.
apm_service_catalog_write: Add, modify, and delete service catalog definitions when those definitions are maintained by Datadog.
appsec_vm_read: View infrastructure, application code, and library vulnerabilities. This does not restrict API or inventory SQL access to the vulnerability data source.
cases_read: View Cases.
cases_write: Create and update cases.
ci_visibility_pipelines_write: Create CI Visibility pipeline spans using the API.
ci_visibility_read: View CI Visibility.
cloud_cost_management_read: View Cloud Cost pages and the cloud cost data source in dashboards and notebooks. For more details, see the Cloud Cost Management docs.
cloud_cost_management_write: Configure cloud cost accounts and global customizations. For more details, see the Cloud Cost Management docs.
code_analysis_read: View Code Analysis.
continuous_profiler_pgo_read: Read and query Continuous Profiler data for Profile-Guided Optimization (PGO).
create_webhooks: Create webhooks integrations.
dashboards_embed_share: Create, modify, and delete shared dashboards with share type 'embed'.
dashboards_invite_share: Create, modify, and delete shared dashboards with share type 'invite'.
dashboards_public_share: Generate public and authenticated links to share dashboards or embeddable graphs externally.
dashboards_read: View dashboards.
dashboards_write: Create and change dashboards.
data_scanner_read: View Data Scanner configurations.
data_scanner_write: Edit Data Scanner configurations.
embeddable_graphs_share: Generate public links to share embeddable graphs externally.
events_read: Read Events data.
hosts_read: List hosts and their attributes.
incident_notification_settings_write: Configure Incidents Notification settings.
incident_read: View incidents in Datadog.
incident_settings_write: Configure Incident Settings.
incident_write: Create, view, and manage incidents in Datadog.
metrics_read: View custom metrics.
monitor_config_policy_write: Edit and delete monitor configuration.
monitors_downtime: Set downtimes to suppress alerts from any monitor in an organization. Mute and unmute monitors. The ability to write monitors is not required to set downtimes.
monitors_read: View monitors.
monitors_write: Edit, delete, and resolve individual monitors.
org_management: Edit org configurations, including authentication and certain security preferences such as configuring SAML, renaming an org, configuring allowed login methods, creating child orgs, subscribing & unsubscribing from apps in the marketplace, and enabling & disabling Remote Configuration for the entire organization.
security_comments_read: Read comments of vulnerabilities.
security_monitoring_filters_read: Read Security Filters.
security_monitoring_filters_write: Create, edit, and delete Security Filters.
security_monitoring_findings_read: View a list of findings that include both misconfigurations and identity risks.
security_monitoring_notification_profiles_read: View Rule Security Notification rules.
security_monitoring_notification_profiles_write: Create, edit, and delete Security Notification rules.
security_monitoring_rules_read: Read Detection Rules.
security_monitoring_rules_write: Create and edit Detection Rules.
security_monitoring_signals_read: View Security Signals.
security_monitoring_suppressions_read: Read Rule Suppressions.
security_monitoring_suppressions_write: Write Rule Suppressions.
security_pipelines_read: View Security Pipelines.
security_pipelines_write: Create, edit, and delete CSM Security Pipelines.
slos_corrections: Apply, edit, and delete SLO status corrections. A user with this permission can make status corrections, even if they do not have permission to edit those SLOs.
slos_read: View SLOs and status corrections.
slos_write: Create, edit, and delete SLOs.
synthetics_global_variable_read: View, search, and use Synthetics global variables.
synthetics_global_variable_write: Create, edit, and delete global variables for Synthetics.
synthetics_private_location_read: View, search, and use Synthetics private locations.
synthetics_private_location_write: Create and delete private locations in addition to having access to the associated installation guidelines.
synthetics_read: List and view configured Synthetic tests and test results.
synthetics_write: Create, edit, and delete Synthetic tests.
teams_manage: Manage Teams. Create, delete, rename, and edit metadata of all Teams. To control Team membership across all Teams, use the User Access Manage permission.
teams_read: Read Teams data. A User with this permission can view Team names, metadata, and which Users are on each Team.
test_optimization_read: View Test Optimization.
timeseries_query: Query Timeseries data.
usage_read: View your organization's usage and usage attribution.
user_access_invite: Invite other users to your organization.
user_access_manage: Disable users, manage user roles, manage SAML-to-role mappings, and configure logs restriction queries.
user_access_read: View users and their roles and settings.
workflows_read: View workflows.
workflows_run: Run workflows.
workflows_write: Create, edit, and delete workflows.
tokenUrl: /oauth2/v1/token
type: oauth2
apiKeyAuth:
description: Your Datadog API Key.
in: header
name: DD-API-KEY
type: apiKey
x-env-name: DD_API_KEY
appKeyAuth:
description: Your Datadog APP Key.
in: header
name: DD-APPLICATION-KEY
type: apiKey
x-env-name: DD_APP_KEY
bearerAuth:
scheme: bearer
type: http
x-env-name: DD_BEARER_TOKEN
x-group-parameters: true
x-merge-override:
paths: false