Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 UK1 US1-FED US2-FED

Link a page to an incident

copy Copy pageCopied

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.ap2.datadoghq.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.datadoghq.eu/api/v2/incidents/{incident_id}/pages/linkhttps://api.ddog-gov.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.us2.ddog-gov.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.uk1.datadoghq.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.datadoghq.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.us3.datadoghq.com/api/v2/incidents/{incident_id}/pages/linkhttps://api.us5.datadoghq.com/api/v2/incidents/{incident_id}/pages/link

Overview

Link an existing on-call page to an incident. This endpoint requires the incident_write permission.

OAuth apps require the incident_write authorization scope to access this endpoint.

Arguments

Path Parameters

Name

Type

Description

incident_id [required]

string

The UUID of the incident.

Request

Body Data (required)

On-call page link payload.

Expand All

Field

Type

Description

data [required]

object

On-call page data in a link request.

attributes

object

Attributes for linking a page to an incident.

key

string

The key of the on-call page.

page_target

object

The target of an on-call page.

identifier [required]

string

The identifier of the page target.

type [required]

string

The type of the page target.

team_id

string

The team ID associated with the page (deprecated, use page_target instead).

id [required]

string

The ID of the on-call page to link.

type [required]

enum

On-call page resource type. Allowed enum values: page

{
  "data": {
    "attributes": {
      "key": "PAGE-12345",
      "page_target": {
        "identifier": "my-oncall-team",
        "type": "team_handle"
      },
      "team_id": "team-abc-123"
    },
    "id": "PAGE-12345",
    "type": "page"
  }
}

Response

Created

Response with an incident integration metadata.

Expand All

Field

Type

Description

data [required]

object

Incident integration metadata from a response.

attributes

object

Incident integration metadata's attributes for a create request.

created

date-time

Timestamp when the incident todo was created.

incident_id

string

UUID of the incident this integration metadata is connected to.

integration_type [required]

int32

A number indicating the type of integration this metadata is for. 1 indicates Slack; 7 indicates Microsoft Teams; 8 indicates Jira.

metadata [required]

 <oneOf>

Incident integration metadata's metadata attribute.

Object 1

object

Incident integration metadata for the Slack integration.

channels [required]

[object]

Array of Slack channels in this integration metadata.

channel_id [required]

string

Slack channel ID.

channel_name [required]

string

Name of the Slack channel.

redirect_url [required]

string

URL redirecting to the Slack channel.

team_id

string

Slack team ID.

Object 2

object

Incident integration metadata for the Jira integration.

issues [required]

[object]

Array of Jira issues in this integration metadata.

account [required]

string

URL of issue's Jira account.

issue_key

string

Jira issue's issue key.

issuetype_id

string

Jira issue's issue type.

project_key [required]

string

Jira issue's project keys.

redirect_url

string

URL redirecting to the Jira issue.

Object 3

object

Incident integration metadata for the Microsoft Teams integration.

teams [required]

[object]

Array of Microsoft Teams in this integration metadata.

ms_channel_id [required]

string

Microsoft Teams channel ID.

ms_channel_name [required]

string

Microsoft Teams channel name.

ms_tenant_id [required]

string

Microsoft Teams tenant ID.

redirect_url [required]

string

URL redirecting to the Microsoft Teams channel.

modified

date-time

Timestamp when the incident todo was last modified.

status

int32

A number indicating the status of this integration metadata. 0 indicates unknown; 1 indicates pending; 2 indicates complete; 3 indicates manually created; 4 indicates manually updated; 5 indicates failed.

id [required]

string

The incident integration metadata's ID.

relationships

object

The incident's integration relationships from a response.

created_by_user

object

Relationship to user.

data [required]

object

Relationship to user object.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

last_modified_by_user

object

Relationship to user.

data [required]

object

Relationship to user object.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Integration metadata resource type. Allowed enum values: incident_integrations

default: incident_integrations

included

[ <oneOf>]

Included related resources that the user requested.

<type=users>

object

User object returned by the API.

attributes

object

Attributes of user object returned by the API.

created_at

date-time

The ISO 8601 timestamp of when the user account was created.

disabled

boolean

Whether the user account is deactivated. Disabled users cannot log in.

email

string

The email address of the user, used for login and notifications.

handle

string

The unique handle (username) of the user, typically matching their email prefix.

icon

string

URL of the user's profile icon, typically a Gravatar URL derived from the email address.

last_login_time

date-time

The ISO 8601 timestamp of the user's most recent login, or null if the user has never logged in.

mfa_enabled

boolean

Whether multi-factor authentication (MFA) is enabled for the user's account.

modified_at

date-time

The ISO 8601 timestamp of when the user account was last modified.

name

string

The full display name of the user as shown in the Datadog UI.

service_account

boolean

Whether this is a service account rather than a human user. Service accounts are used for programmatic API access.

status

string

The current status of the user account (for example, Active, Pending, or Disabled).

title

string

The job title of the user (for example, "Senior Engineer" or "Product Manager").

uuid

string

The globally unique identifier (UUID) of the user.

verified

boolean

Whether the user's email address has been verified.

id

string

ID of the user.

relationships

object

Relationships of the user object returned by the API.

org

object

Relationship to an organization.

data [required]

object

Relationship to organization object.

id [required]

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

other_orgs

object

Relationship to organizations.

data [required]

[object]

Relationships to organization objects.

id [required]

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

other_users

object

Relationship to users.

data [required]

[object]

Relationships to user objects.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

roles

object

Relationship to roles.

data

[object]

An array containing type and the unique identifier of a role.

id

string

The unique identifier of the role.

type

enum

Roles type. Allowed enum values: roles

default: roles

type

enum

Users resource type. Allowed enum values: users

default: users

{
  "data": {
    "attributes": {
      "created": "2019-09-19T10:00:00.000Z",
      "incident_id": "00000000-aaaa-0000-0000-000000000000",
      "integration_type": 1,
      "metadata": {
        "channels": [
          {
            "channel_id": "C0123456789",
            "channel_name": "#example-channel-name",
            "redirect_url": "https://slack.com/app_redirect?channel=C0123456789\u0026team=T01234567",
            "team_id": "T01234567"
          }
        ]
      },
      "modified": "2019-09-19T10:00:00.000Z",
      "status": "integer"
    },
    "id": "00000000-0000-0000-1234-000000000000",
    "relationships": {
      "created_by_user": {
        "data": {
          "id": "00000000-0000-0000-2345-000000000000",
          "type": "users"
        }
      },
      "last_modified_by_user": {
        "data": {
          "id": "00000000-0000-0000-2345-000000000000",
          "type": "users"
        }
      }
    },
    "type": "incident_integrations"
  },
  "included": [
    {
      "attributes": {
        "created_at": "2019-09-19T10:00:00.000Z",
        "disabled": false,
        "email": "string",
        "handle": "string",
        "icon": "string",
        "last_login_time": "2019-09-19T10:00:00.000Z",
        "mfa_enabled": false,
        "modified_at": "2019-09-19T10:00:00.000Z",
        "name": "string",
        "service_account": false,
        "status": "string",
        "title": "string",
        "uuid": "string",
        "verified": false
      },
      "id": "string",
      "relationships": {
        "org": {
          "data": {
            "id": "00000000-0000-beef-0000-000000000000",
            "type": "orgs"
          }
        },
        "other_orgs": {
          "data": [
            {
              "id": "00000000-0000-beef-0000-000000000000",
              "type": "orgs"
            }
          ]
        },
        "other_users": {
          "data": [
            {
              "id": "00000000-0000-0000-2345-000000000000",
              "type": "users"
            }
          ]
        },
        "roles": {
          "data": [
            {
              "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
              "type": "roles"
            }
          ]
        }
      },
      "type": "users"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict - page already linked to incident.

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  ## default
# 

# Path parameters
export incident_id="CHANGE_ME"
# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/incidents/${incident_id}/pages/link" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "key": "PAGE-12345",
      "page_target": {
        "identifier": "my-oncall-team",
        "type": "team_handle"
      }
    },
    "id": "PAGE-12345",
    "type": "page"
  }
}
EOF