openapi: 3.1.0
info:
  title: Datadog Incidents API
  description: >-
    The Datadog Incidents API allows you to manage incident response,
    as well as associated attachments, metadata, and todos. It also supports
    creating, updating, deleting, and retrieving services associated with
    incidents. Incidents capture the full lifecycle of an outage or issue
    including detection, investigation, remediation, and post-mortem analysis.
    The Incidents feature requires the Incident Management product and
    appropriate permissions within your Datadog organization.
  version: 'v2'
  contact:
    name: Datadog Support
    url: https://www.datadoghq.com/support/
  termsOfService: https://www.datadoghq.com/legal/terms/
externalDocs:
  description: Datadog Incidents API Documentation
  url: https://docs.datadoghq.com/api/latest/incidents/
servers:
- url: https://api.datadoghq.com
  description: Datadog API Production Server
tags:
- name: Incident Teams
  description: Manage teams associated with incidents
- name: Incidents
  description: Create and manage incident records
security:
- apiKeyAuth: []
- appKeyAuth: []
paths:
  /api/v2/incidents:
    post:
      operationId: createIncident
      summary: Datadog Create an Incident
      description: >-
        Creates a new incident record in Datadog Incident Management. An incident
        captures an outage or issue, including its title, severity, status,
        customer impact description, and associated fields. Creating an incident
        triggers notifications to configured responders and creates a dedicated
        Slack channel if configured. The incident is assigned a unique ID and
        timestamped at creation time. Custom fields configured in your
        organization settings can be set on incident creation.
      tags:
      - Incidents
      parameters:
      - name: include
        in: query
        required: false
        description: Comma-separated list of related resources to include in the response (e.g., attachments, responders)
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentCreateRequest'
      responses:
        '201':
          description: Incident created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentResponse'
        '400':
          description: Bad request - invalid incident payload 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 create incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - referenced resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listIncidents
      summary: Datadog List Incidents
      description: >-
        Returns a paginated list of incidents for your Datadog organization.
        Results can be filtered by incident state, severity, and date range.
        Supports including related resources such as users, teams, services,
        and attachments. Incidents are returned in reverse chronological order
        by default. Use cursor-based pagination for large datasets.
      tags:
      - Incidents
      parameters:
      - name: include
        in: query
        required: false
        description: Comma-separated list of related resources to include (e.g., attachments, responders, commander)
        schema:
          type: string
        example: example_value
      - name: page[size]
        in: query
        required: false
        description: The number of incidents to return per page (default 10, max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        example: 42
      - name: page[offset]
        in: query
        required: false
        description: The offset for pagination (number of records to skip)
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 42
      - name: filter[state]
        in: query
        required: false
        description: Filter incidents by their current state
        schema:
          type: string
          enum: [active, stable, resolved]
        example: active
      - name: filter[severity]
        in: query
        required: false
        description: Filter incidents by severity level (SEV-1 to SEV-5)
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful response with list of incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentsResponse'
        '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 incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - incidents feature is not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/incidents/{incident_id}:
    get:
      operationId: getIncident
      summary: Datadog Get the Details of an Incident
      description: >-
        Returns the full details of a specific incident identified by its unique
        ID. Includes the incident title, status, severity, customer impact
        description, timeline, custom fields, and optionally associated
        responders, services, teams, and attachments. Use the include parameter
        to fetch related resources in a single request.
      tags:
      - Incidents
      parameters:
      - $ref: '#/components/parameters/incidentIdParam'
      - name: include
        in: query
        required: false
        description: Comma-separated list of related resources to include in the response
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successful response with incident details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions to view this incident
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - incident with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateIncident
      summary: Datadog Update an Existing Incident
      description: >-
        Updates an existing incident with new information. Supports partial
        updates using JSON merge patch semantics. Can update the incident title,
        status, severity, customer impact fields, custom fields, and notification
        handles. Status transitions trigger automatic timeline entries and
        notifications to responders. Resolving an incident records the resolution
        time and optionally captures customer impact duration.
      tags:
      - Incidents
      parameters:
      - $ref: '#/components/parameters/incidentIdParam'
      - name: include
        in: query
        required: false
        description: Comma-separated list of related resources to include in the response
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentUpdateRequest'
      responses:
        '200':
          description: Incident updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentResponse'
        '400':
          description: Bad request - invalid update payload or field values
          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 incident
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - incident with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteIncident
      summary: Datadog Delete an Existing Incident
      description: >-
        Permanently deletes the incident with the specified ID. This action
        cannot be undone. Deleting an incident removes all associated timeline
        events, attachments, and todos. Associated Slack channels are not
        automatically archived. Only users with the Incident Management write
        permission can delete incidents.
      tags:
      - Incidents
      parameters:
      - $ref: '#/components/parameters/incidentIdParam'
      responses:
        '204':
          description: No content - incident deleted successfully
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions to delete this incident
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - incident with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/teams:
    post:
      operationId: createIncidentTeam
      summary: Datadog Create a New Incident Team
      description: >-
        Creates a new incident team that can be associated with incidents for
        organizing responders. Teams help route incidents to the appropriate
        on-call groups and provide a way to track ownership and responsibility
        during incident response. Teams can be referenced when creating or
        updating incidents.
      tags:
      - Incident Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentTeamCreateRequest'
      responses:
        '201':
          description: Incident team created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentTeamResponse'
        '400':
          description: Bad request - invalid team 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 incident teams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listIncidentTeams
      summary: Datadog Get a List of Incident Teams
      description: >-
        Returns a paginated list of all incident teams configured in your
        Datadog organization. Teams can be filtered by name. Incident teams
        are used to organize responders and route incidents to appropriate
        groups. Returns team names and IDs for use when associating teams
        with incidents.
      tags:
      - Incident Teams
      parameters:
      - name: filter[query]
        in: query
        required: false
        description: Filter teams by name using a substring search
        schema:
          type: string
        example: avg:system.cpu.user{*}
      - name: page[size]
        in: query
        required: false
        description: The number of teams to return per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        example: 42
      - name: page[offset]
        in: query
        required: false
        description: The number of records to skip for pagination
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 42
      responses:
        '200':
          description: Successful response with list of incident teams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentTeamsResponse'
        '400':
          description: Bad request - invalid filter or pagination 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 incident teams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/teams/{team_id}:
    get:
      operationId: getIncidentTeam
      summary: Datadog Get Details of an Incident Team
      description: >-
        Returns the full details of a specific incident team identified by
        its unique ID, including the team name, creation time, and optional
        included resources such as team members.
      tags:
      - Incident Teams
      parameters:
      - $ref: '#/components/parameters/teamIdParam'
      responses:
        '200':
          description: Successful response with incident team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentTeamResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions to view this team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - team with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateIncidentTeam
      summary: Datadog Update an Existing Incident Team
      description: >-
        Updates the name or configuration of an existing incident team.
        Team membership is managed separately through user management
        endpoints. Changes take effect immediately for all future
        incident associations.
      tags:
      - Incident Teams
      parameters:
      - $ref: '#/components/parameters/teamIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentTeamUpdateRequest'
      responses:
        '200':
          description: Incident team updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentTeamResponse'
        '400':
          description: Bad request - invalid team update payload
          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 team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - team with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteIncidentTeam
      summary: Datadog Delete an Existing Incident Team
      description: >-
        Permanently deletes an incident team. The team is disassociated from
        any incidents that reference it. This action cannot be undone.
        Incidents that referenced the deleted team will no longer show the
        team association.
      tags:
      - Incident Teams
      parameters:
      - $ref: '#/components/parameters/teamIdParam'
      responses:
        '204':
          description: No content - incident team deleted successfully
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions to delete this team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - team with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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
  parameters:
    incidentIdParam:
      name: incident_id
      in: path
      required: true
      description: The unique string identifier of the incident
      schema:
        type: string
    teamIdParam:
      name: team_id
      in: path
      required: true
      description: The unique string identifier of the incident team
      schema:
        type: string
  schemas:
    IncidentCreateRequest:
      type: object
      description: Request body for creating a new incident
      required:
      - data
      properties:
        data:
          type: object
          description: The incident creation data
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource type identifier for incidents
              enum: [incidents]
            attributes:
              $ref: '#/components/schemas/IncidentCreateAttributes'
    IncidentCreateAttributes:
      type: object
      description: Attributes for creating a new incident
      required:
      - title
      - customer_impacted
      properties:
        title:
          type: string
          description: The title of the incident describing what is affected and the nature of the issue
          example: Example Monitor
        customer_impacted:
          type: boolean
          description: Whether the incident is causing direct customer impact (required field for all incidents)
          example: true
        customer_impact_scope:
          type: string
          description: Description of the customer groups or features affected by this incident
          example: example_value
        customer_impact_start:
          type: string
          format: date-time
          description: ISO 8601 timestamp when customer impact started, if known
          example: example_value
        severity:
          type: string
          description: The severity level of the incident using SEV-N notation
          enum: [SEV-1, SEV-2, SEV-3, SEV-4, SEV-5, UNKNOWN]
          example: SEV-1
        state:
          type: string
          description: The initial state of the incident
          enum: [active, stable, resolved]
          default: active
          example: active
        fields:
          type: object
          description: Custom fields for the incident as configured in your organization settings
          additionalProperties:
            type: object
        notification_handles:
          type: array
          description: List of user and team notification handles to page on incident creation
          items:
            type: object
            properties:
              handle:
                type: string
                description: The Datadog handle or integration channel to notify
              display_name:
                type: string
                description: The display name for this notification handle
    IncidentResponse:
      type: object
      description: Response wrapper for a single incident
      properties:
        data:
          $ref: '#/components/schemas/Incident'
        included:
          type: array
          description: Related resources included in the response based on the include query parameter
          items:
            type: object
    IncidentsResponse:
      type: object
      description: Response containing a paginated list of incidents
      properties:
        data:
          type: array
          description: List of incident objects
          items:
            $ref: '#/components/schemas/Incident'
        included:
          type: array
          description: Related resources included in the response based on the include query parameter
          items:
            type: object
        meta:
          type: object
          description: Metadata about the incidents list response
          properties:
            pagination:
              type: object
              description: Pagination information for navigating through results
              properties:
                next_offset:
                  type: integer
                  description: The offset to use in the next request to retrieve the next page
                prev_offset:
                  type: integer
                  description: The offset to use to retrieve the previous page
                size:
                  type: integer
                  description: The number of incidents in this page
                total_count:
                  type: integer
                  description: The total number of incidents matching the filter criteria
    Incident:
      type: object
      description: A Datadog incident record representing an outage or service disruption
      properties:
        id:
          type: string
          description: The unique string identifier of the incident
          example: abc-123-def
        type:
          type: string
          description: The resource type identifier (always 'incidents')
          example: metric alert
        attributes:
          $ref: '#/components/schemas/IncidentAttributes'
        relationships:
          type: object
          description: Relationships to associated resources such as commander, teams, and services
          properties:
            commander:
              type: object
              description: The incident commander responsible for coordinating the response
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The unique ID of the commander user
                    type:
                      type: string
                      description: The resource type (users)
    IncidentAttributes:
      type: object
      description: The attributes of an incident record
      properties:
        title:
          type: string
          description: The title of the incident describing what is affected
          example: Example Monitor
        public_id:
          type: integer
          description: The sequential human-readable public ID of the incident within the organization
          example: 42
        state:
          type: string
          description: The current state of the incident in its lifecycle
          enum: [active, stable, resolved]
          example: active
        severity:
          type: string
          description: The severity level of the incident
          enum: [SEV-1, SEV-2, SEV-3, SEV-4, SEV-5, UNKNOWN]
          example: SEV-1
        customer_impacted:
          type: boolean
          description: Whether the incident is causing direct customer impact
          example: true
        customer_impact_scope:
          type: string
          description: Description of the scope of customer impact for this incident
          example: example_value
        customer_impact_start:
          type: string
          format: date-time
          description: ISO 8601 timestamp when customer impact began
          example: example_value
        customer_impact_end:
          type: string
          format: date-time
          description: ISO 8601 timestamp when customer impact ended
          example: example_value
        customer_impact_duration:
          type: integer
          description: Duration of customer impact in seconds
          example: 42
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the incident was created
          example: example_value
        modified:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the incident was last modified
          example: example_value
        detected:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the incident was first detected
          example: example_value
        resolved:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the incident was marked as resolved
          example: example_value
        time_to_detect:
          type: integer
          description: Time in seconds from incident start to detection
          example: 42
        time_to_internal_response:
          type: integer
          description: Time in seconds from detection to first responder acknowledgement
          example: 42
        time_to_repair:
          type: integer
          description: Time in seconds from detection to resolution
          example: 42
        fields:
          type: object
          description: Custom field values for the incident as defined in organization settings
          additionalProperties:
            type: object
        notification_handles:
          type: array
          description: List of notification handles that were paged for this incident
          items:
            type: object
    IncidentUpdateRequest:
      type: object
      description: Request body for updating an existing incident
      required:
      - data
      properties:
        data:
          type: object
          description: The incident update data
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource type identifier
              enum: [incidents]
            id:
              type: string
              description: The unique ID of the incident to update
            attributes:
              $ref: '#/components/schemas/IncidentUpdateAttributes'
    IncidentUpdateAttributes:
      type: object
      description: Attributes to update on an existing incident
      properties:
        title:
          type: string
          description: The updated title of the incident
          example: Example Monitor
        state:
          type: string
          description: The updated state of the incident (transitioning to resolved records resolution time)
          enum: [active, stable, resolved]
          example: active
        severity:
          type: string
          description: The updated severity level of the incident
          enum: [SEV-1, SEV-2, SEV-3, SEV-4, SEV-5, UNKNOWN]
          example: SEV-1
        customer_impacted:
          type: boolean
          description: Updated flag indicating whether the incident has customer impact
          example: true
        customer_impact_scope:
          type: string
          description: Updated description of the customer impact scope
          example: example_value
        customer_impact_end:
          type: string
          format: date-time
          description: ISO 8601 timestamp when customer impact ended (set when marking impact as resolved)
          example: example_value
        fields:
          type: object
          description: Updated custom field values for the incident
          additionalProperties:
            type: object
        notification_handles:
          type: array
          description: Updated list of notification handles for the incident
          items:
            type: object
    IncidentTeamCreateRequest:
      type: object
      description: Request body for creating a new incident team
      required:
      - data
      properties:
        data:
          type: object
          description: The incident team creation data
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource type identifier for incident teams
              enum: [teams]
            attributes:
              type: object
              description: The incident team attributes
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the incident team for display and identification
    IncidentTeamUpdateRequest:
      type: object
      description: Request body for updating an existing incident team
      required:
      - data
      properties:
        data:
          type: object
          description: The incident team update data
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource type identifier for incident teams
              enum: [teams]
            id:
              type: string
              description: The unique ID of the incident team to update
            attributes:
              type: object
              description: The updated incident team attributes
              required:
              - name
              properties:
                name:
                  type: string
                  description: The updated name for the incident team
    IncidentTeam:
      type: object
      description: A team associated with incident response
      properties:
        id:
          type: string
          description: The unique string identifier of the incident team
          example: abc-123-def
        type:
          type: string
          description: The resource type identifier (always 'teams')
          example: metric alert
        attributes:
          type: object
          description: The incident team attributes
          properties:
            name:
              type: string
              description: The display name of the incident team
            created:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the team was created
            modified:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the team was last modified
    IncidentTeamResponse:
      type: object
      description: Response wrapper for a single incident team
      properties:
        data:
          $ref: '#/components/schemas/IncidentTeam'
    IncidentTeamsResponse:
      type: object
      description: Response containing a list of incident teams
      properties:
        data:
          type: array
          description: List of incident team objects
          items:
            $ref: '#/components/schemas/IncidentTeam'
    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