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 Monitors 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: Monitors
  description: Create, read, update, and delete monitors
paths:
  /api/v1/monitor:
    post:
      operationId: createMonitor
      summary: Datadog Create a Monitor
      description: Creates a new monitor with the specified configuration. The monitor type determines which query language and threshold options are available. Monitors can alert on metric thresholds, anomalies, log patterns, APM traces, synthetic test results, and more. Upon creation, Datadog begins evaluating the monitor against the defined query and will send notifications when alert conditions are met.
      tags:
      - Monitors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Monitor'
      responses:
        '200':
          description: Successfully created monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Bad request - invalid monitor configuration
          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 create monitors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listMonitors
      summary: Datadog List All Monitors
      description: Returns a paginated list of monitors for your Datadog organization. Results can be filtered by monitor type, group states, name tags, monitor tags, creator, and ID. Supports sorting by name, status, and type. Use this endpoint to audit your monitoring configuration or build monitoring dashboards.
      tags:
      - Monitors
      parameters:
      - name: group_states
        in: query
        required: false
        description: Comma-separated list of group states to filter monitors by (alert, ignored, no data, ok, skipped, unknown, warn)
        schema:
          type: string
        example: example_value
      - name: name
        in: query
        required: false
        description: Filter monitors by name substring match
        schema:
          type: string
        example: Example Monitor
      - name: tags
        in: query
        required: false
        description: Comma-separated list of tags to filter monitors by
        schema:
          type: string
        example: env:production
      - name: monitor_tags
        in: query
        required: false
        description: Comma-separated list of monitor-specific tags to filter by
        schema:
          type: string
        example: env:production
      - name: with_downtimes
        in: query
        required: false
        description: When true, includes downtime information in the response
        schema:
          type: boolean
        example: true
      - name: id_offset
        in: query
        required: false
        description: Monitor ID to start paginating from (for cursor-based pagination)
        schema:
          type: integer
        example: 42
      - name: page
        in: query
        required: false
        description: The page number to retrieve (zero-indexed, for offset-based pagination)
        schema:
          type: integer
          minimum: 0
        example: 42
      - name: page_size
        in: query
        required: false
        description: The number of monitors to return per page (default 100, max 1000)
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
        example: 42
      responses:
        '200':
          description: Successful response with list of monitors
          content:
            application/json:
              schema:
                type: array
                description: List of monitors matching the specified filters
                items:
                  $ref: '#/components/schemas/Monitor'
        '400':
          description: Bad request - invalid filter parameters
          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 list monitors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/monitor/{monitor_id}:
    get:
      operationId: getMonitor
      summary: Datadog Get a Monitor
      description: Returns the configuration and current status of a specific monitor identified by its ID. Includes the monitor query, notification settings, alert thresholds, and current group statuses. Optionally includes downtime and creator information.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/monitorIdParam'
      - name: group_states
        in: query
        required: false
        description: Comma-separated group states to include in the response (alert, ignored, no data, ok, skipped, unknown, warn)
        schema:
          type: string
        example: example_value
      - name: with_downtimes
        in: query
        required: false
        description: When true, includes active downtime information in the response
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successful response with monitor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Bad request - invalid monitor ID format
          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 view 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
    put:
      operationId: updateMonitor
      summary: Datadog Edit a Monitor
      description: Updates the configuration of an existing monitor identified by its ID. The request body replaces the entire monitor configuration, so include all desired fields in the update. Changes to the query or thresholds take effect immediately. Updating notification channels or message templates applies to future alerts.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/monitorIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorUpdateRequest'
      responses:
        '200':
          description: Successfully updated monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '400':
          description: Bad request - invalid monitor configuration or missing required fields
          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 update 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
    delete:
      operationId: deleteMonitor
      summary: Datadog Delete a Monitor
      description: Permanently deletes the monitor with the specified ID. Deletion cannot be undone. Active alerts and notifications for the monitor are immediately cancelled. Any associated SLOs referencing this monitor must be updated before the monitor can be deleted.
      tags:
      - Monitors
      parameters:
      - $ref: '#/components/parameters/monitorIdParam'
      - name: force
        in: query
        required: false
        description: When true, forcefully deletes the monitor even if it is referenced by SLOs or composite monitors
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully deleted monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedMonitor'
        '400':
          description: Bad request - monitor cannot be deleted (e.g., referenced by SLO)
          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 delete 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:
    MonitorUpdateRequest:
      type: object
      description: Request body for updating an existing monitor configuration
      properties:
        type:
          type: string
          description: The type of the monitor (changing type may reset other settings)
          example: metric alert
        query:
          type: string
          description: The updated monitor query expression
          example: avg:system.cpu.user{*}
        name:
          type: string
          description: The updated descriptive name for the monitor
          example: Example Monitor
        message:
          type: string
          description: The updated notification message body
          example: CPU usage is high on {{host.name}}
        tags:
          type: array
          description: The updated list of tags to associate with the monitor
          items:
            type: string
        options:
          $ref: '#/components/schemas/MonitorOptions'
        priority:
          type: integer
          description: The updated priority level (1 highest to 5 lowest)
          minimum: 1
          maximum: 5
          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
    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
    DeletedMonitor:
      type: object
      description: Response returned after successfully deleting a monitor
      properties:
        deleted_monitor_id:
          type: integer
          format: int64
          description: The ID of the monitor that was deleted
          example: 42
    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
    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