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.

HTTP Method	URL
GET, POST, PUT, PATCH	https://api.opsgenie.com/v2/heartbeats/:heartbeatName/ping

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.

HTTP Method	URL
POST	https://api.opsgenie.com/v2/heartbeats

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

HTTP Method	URL
GET	https://api.opsgenie.com/v2/heartbeats/:heartbeatName

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

HTTP Method	URL
GET	https://api.opsgenie.com/v2/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.

HTTP Method	URL
PATCH	https://api.opsgenie.com/v2/heartbeats/:heartbeatName

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.

HTTP Method	URL
DELETE	https://api.opsgenie.com/v2/heartbeats/:heartbeatName

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.

HTTP Method	URL
POST	https://api.opsgenie.com/v2/heartbeats/:heartbeatName/enable

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.

HTTP Method	URL
POST	https://api.opsgenie.com/v2/heartbeats/:heartbeatName/disable

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"
}