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 NameDescription
heartbeatNameName 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.

FieldMandatoryDescriptionLimit
nametrueName of the heartbeat200 chars
descriptionfalseAn optional description of the heartbeat10000 chars
intervaltrueSpecifies how often a heartbeat message should be expected.Min 1
intervalUnittrueInterval specified as minutes, hours or days
enabledtrueEnable/disable heartbeat monitoring
ownerTeamfalseOwner team of the heartbeat, consisting id and/or name of the owner team
alertMessagefalseSpecifies the alert message for heartbeat expiration alert. If this is not provided, default alert message is "HeartbeatName is expired"130 chars
alertTagsfalseSpecifies the alert tags for heartbeat expiration alert20 x 50 chars
alertPriorityfalseSpecifies 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 NameDescription
heartbeatNameName 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 NameDescription
heartbeatNameName of the heartbeat

JSON Body Fields

FieldMandatoryDescriptionLimit
descriptionfalseAn optional description of the heartbeat10000 chars
intervalfalseSpecifies how often a heartbeat message should be expected.Min 1
intervalUnitfalseInterval specified as minutes, hours or days
enabledfalseEnable/disable heartbeat monitoring
ownerTeamfalseOwner 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.
alertMessagefalseSpecifies the alert message for heartbeat expiration alert. If this is not provided, default alert message is "HeartbeatName is expired"130 chars
alertTagsfalseSpecifies the alert tags for heartbeat expiration alert20x50 chars
alertPriorityfalseSpecifies 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 NameDescription
heartbeatNameName 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 NameDescription
heartbeatNameName 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 NameDescription
heartbeatNameName 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"
}

Updated 6 months ago


Heartbeat API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.