Heartbeat API

🚧

If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

General Information

📘

Create an API Integration and obtain your apiKey to make requests listed above. Please make sure that the integration is not restricted to access configurations. Otherwise, the integration will only be authorized to send Ping Heartbeat Request

Ping Heartbeat Request

❗️

Since Opsgenie process heartbeat ping requests asynchronously, it does not check if the heartbeat exists or not before responding.
Please note that receiving a PONG response does not necessarily mean that the heartbeat exists.

In-Line Parameters

Referred Name

Description

heartbeatName

Name of the heartbeat

Sample Requests

curl -X GET 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
curl -X POST 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
curl -X PUT 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
curl -X PATCH 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response

{
    "result": "PONG - Heartbeat received",
    "took": 0,
    "requestId": "111be080-6632-4897-a6e9-b8dc72f943c7"
}

Add Heartbeat Request

Add Heartbeat request is used to define heartbeats in Opsgenie. A heartbeat needs to be added, before sending heartbeat messages to Opsgenie. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

Field

Mandatory

Description

Limit

name

true

Name of the heartbeat

200 chars

description

false

An optional description of the heartbeat

10000 chars

interval

true

Specifies how often a heartbeat message should be expected.

Min 1

intervalUnit

true

Interval specified as minutes, hours or days

enabled

true

Enable/disable heartbeat monitoring

ownerTeam

false

Owner team of the heartbeat, consisting id and/or name of the owner team

alertMessage

false

Specifies the alert message for heartbeat expiration alert. If this is not provided, default alert message is "HeartbeatName is expired"

130 chars

alertTags

false

Specifies the alert tags for heartbeat expiration alert

20 x 50 chars

alertPriority

false

Specifies the alert priority for heartbeat expiration alert. If this is not provided, default priority is P3

🚧

If you are using the deprecated Heartbeat Version, you can not use alertMessage , alertTags and alertPriority fields. If you wish to use new Heartbeat Version, you can get further information from here.

🚧

If integration belongs to any team, it automatically overwrites ownerTeam object. Otherwise, id or name fields should be specified in ownerTeam

ownerTeam field example:

{
    "ownerTeam": {
        "name":"operations_team"
    }
}
{
    "ownerTeam": {
        "id":"8418d193-2alp-4490-b331-8c02cdd196b7"
    }
}

Sample Request

curl -X POST 'https://api.opsgenie.com/v2/heartbeats'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name" : "HeartbeatName",
    "description": "Sample heartbeat description",
    "intervalUnit" : "minutes",
    "interval" : 10,
    "enabled" : true,
    "ownerTeam": {
    	"name": "ops_team"
    },
    "alertMessage": "HeartbeatName is expired",
    "alertPriority": "P2"
}'

Response

{
    "data": {
        "name": "HeartbeatName",
        "description": "Sample heartbeat description",
        "interval": 10,
        "enabled": true,
        "intervalUnit": "minutes",
        "expired": true,
        "ownerTeam": {
          "id": "6c7be998-fad9-4491-a9a7-d99alp4c0ae5",
          "name": "ops_team"
        }
    },
    "took": 0,
    "requestId": "a19344d1-6ece-4c1c-9c02-cb062e1d21f9"
}

Get Heartbeat Request

In-Line Parameters

Referred Name

Description

heartbeatName

Name of the heartbeat

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response

{
    "data": {
        "name": "HeartbeatName",
        "description": "Sample heartbeat description",
        "interval": 10,
        "enabled": true,
        "intervalUnit": "minutes",
        "expired": true,
	      "ownerTeam": {
      			"id": "6c7be998-fad9-4491-a9a7-d99alp4c0ae5",
      			"name": "ops_team"
    		},
  			"alertMessage": "HeartbeatName is expired",
      	"alertTags": ["heartbeatTag1","heartbeatTag2"],
      	"alertPriority" : "P3"
    },
    "took": 0,
    "requestId": "9bc9e05b-2f07-44b3-9be0-cb0ec0c45533"
}

🚧

If you are using the deprecated Heartbeat Version, you can not use alertMessage , alertTags and alertPriority fields. If you wish to use new Heartbeat Version, you can get further information from here.

List Heartbeats

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/heartbeats'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response

{
    "data": {
        "heartbeats": [
            {
                "name": "hb1",
                "description": "Heartbeat hb1 description",
                "interval": 5,
                "intervalUnit": "minutes",
                "enabled": true,
              	"ownerTeam": {
                    "id": "6c7be998-fad9-4491-a9a7-d99alp4c0ae5",
                    "name": "A team"
                },
                "alertMessage": "Heartbeat [hb1] is expired.",
                "alertTags": [],
                "alertPriority": "P3"
            },
            {
                "name": "hb2",
                "description": "Heartbeat hb2 description",
                "interval": 1,
                "intervalUnit": "minutes",
                "enabled": false,
              	"ownerTeam": {
                    "id": "6c7be998-fad9-4491-a9a7-d99alp4c0ae5",
                    "name": "A team"
                },
                "alertMessage": "Heartbeat [hb2] is expired.",
                "alertTags": [],
                "alertPriority": "P3"
            },
            {
                "name": "hb3",
                "description": "Heartbeat hb3 description",
                "interval": 10,
                "intervalUnit": "minutes",
                "enabled": false,
                "alertMessage": "Heartbeat [hb3] is expired.",
                "alertTags": [],
                "alertPriority": "P3"
            }
        ]
    },
    "took": 0.063,
    "requestId": "9bc9e05b-2f07-44b3-9be0-cb0ec0c45533"
}

Update Heartbeat Request (Partial)

Update Heartbeat request is used to change configuration of existing heartbeats. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

In-Line Parameters

Referred Name

Description

heartbeatName

Name of the heartbeat

JSON Body Fields

Field

Mandatory

Description

Limit

description

false

An optional description of the heartbeat

10000 chars

interval

false

Specifies how often a heartbeat message should be expected.

Min 1

intervalUnit

false

Interval specified as minutes, hours or days

enabled

false

Enable/disable heartbeat monitoring

ownerTeam

false

Owner team of the schedule, consisting id and/or name of the owner team. If ownerTeam is given with no id or name, then related heartbeat will be global. Note that, you can only update a team-based heartbeat to be global with using global integration apiKey.

alertMessage

false

Specifies the alert message for heartbeat expiration alert. If this is not provided, default alert message is "HeartbeatName is expired"

130 chars

alertTags

false

Specifies the alert tags for heartbeat expiration alert

20x50 chars

alertPriority

false

Specifies the alert priority for heartbeat expiration alert. If this is not provided, default priority is P3

🚧

If you are using the deprecated Heartbeat Version, you can not use alertMessage , alertTags and alertPriority fields. If you wish to use new Heartbeat Version, you can get further information from here.

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "interval": "5",
    "intervalUnit": "hours",
    "description": "updated heartbeat",
    "enabled": true,
    "alertPriority": "P2"
}'

Response

{
    "data": {
        "name": "HeartbeatName",
        "enabled": true,
        "expired": false
    },
    "took": 0,
    "requestId": "75a91218-0d78-4a17-a983-c290fe15906f"
}

Sample Request To Remove ownerTeam of Heartbeat

curl -X PATCH 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "interval": "5",
    "intervalUnit": "hours",
    "description": "updated heartbeat",
    "ownerTeam": {}
}'

Response

{
    "data": {
        "name": "HeartbeatName",
        "enabled": true,
        "expired": false
    },
    "took": 0,
    "requestId": "75a91218-0d78-4a17-a983-c290fe15906f"
}

Delete Heartbeat Request

Delete heartbeat request is used to delete monitored heartbeat in Opsgenie. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

In-Line Parameters

Referred Name

Description

heartbeatName

Name of the heartbeat

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response

{
    "result": "Deleted",
    "took": 0,
    "requestId": "70b60422-02fa-4568-8f46-a9c0e5409083"
}

Enable Heartbeat Request

Enable heartbeat request is used to enable monitored heartbeat in Opsgenie. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

In-Line Parameters

Referred Name

Description

heartbeatName

Name of the heartbeat

Sample Requests

curl -X POST 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/enable'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response

{
    "data": {
        "name": "HeartbeatName",
        "enabled": true,
        "expired": false
    },
    "took": 0,
    "requestId": "ee0ec5ae-0afc-49ab-862f-3c62612612f0"
}

Disable Heartbeat Request

Disable heartbeat request is used to disable monitored heartbeat in Opsgenie. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management.

In-Line Parameters

Referred Name

Description

heartbeatName

Name of the heartbeat

Sample Requests

curl -X POST 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/disable'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "data": {
        "name": "HeartbeatName",
        "enabled": false,
        "expired": true
    },
    "took": 0,
    "requestId": "1f77b0ea-dd20-40de-94ec-e875a09e8cc9"
}