Heartbeat API v2 Requests

Please refer to Heartbeat Monitoring page for preliminary information.

 

General Information

API Requests

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.

Authentication & Authorization

There are two ways for authentication:

  1. Authorization Header
  2. Header Key: Authorization
    Header Value: GenieKey $apiKey

    OR

    Header Key: Authorization
    Header Value: basic $apiKey(base64 encoded)
  3. Query Parameter “apiKey”
  4. Example:
    https://api.opsgenie.com/v2/heartbeats?apiKey=$apiKey

Response Codes

In the table below you can find the response codes and their descriptions.

Status Code Internal Code Description
200 - OK Successful
201 - Created A new entity is created
202 - Accepted Request is valid and will be processed asynchronously
400 - Bad Request (Syntax Error only) Invalid JSON body
401 - Unauthenticated (Not unauthorized) apiKey is invalid or integration is disabled
402 - Payment Required apiKey is valid but the account cannot do this action because of subscription plan
403 - Forbidden (Unauthorized) 40301 apiKey is valid but the apiKey cannot do this operation because of permissions
403 - Forbidden 40302 apiKey is valid and authorized but we do not support the request
404 - Not Found Resource or handler not found
405 - Method Not allowed URL is valid but HTTP method not supported
406 - Not Acceptable Requested format is not supported (Accept header)
409 - Conflict ID or name conflicts with another entity. E.g. heartbeat name already exists
410 - Gone Feature is deprecated
415 - Unsupported Media Type Request body format is not supported (Content-Type header)
416 - Requested Range not satisfiable The given range is not supported
422 - Unprocessable Entity Semantic errors in request body
428 - Pre Condition Required Entity is used by another entity (schedule, escalation, team, etc.)
429 - Too Many Request* Throttling
500 - Internal Server Error Internal server error
501 - Not Implemented Method not implemented
503 - Service Unavailable* Back-end servers are at capacity

Ping Heartbeat Request

Heartbeat request is used to send heartbeat from applications to OpsGenie. It takes the following parameters:

Available Methods

HTTP Method URL
GET, POST, PUT, PATCH https://api.opsgenie.com/v2/heartbeats/$heartbeatName/ping
Sample Requests
curl -X GET --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
curl -X POST --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
curl -X PUT --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
curl -X PATCH --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/ping'
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. Add heartbeat request takes the following parameters:

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

Mandatory Parameters

Parameter Limit
name Name of the heartbeat 200 chars
interval Specifies how often a heartbeat message should be expected. 
intervalUnit Interval specified as minutes, hours or days
enabled Enable/disable heartbeat monitoring

Optional Parameters

Parameter Limit
description An optional description of the heartbeat 10000 chars

Request Headers

Parameter
Content-Type application/json
Sample Request
curl -X POST --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' --header 'Content-Type: application/json' 'https://api.opsgenie.com/v2/heartbeats'-d'
{
    "name" : "HeartbeatName",
    "intervalUnit" : "minutes",
    "interval" : 10,
    "enabled" : true,
    "description": "sample heartbeat description"
}'
Response:
{
  "code": 201,
  "data": {
    "name": "HeartbeatName",
    "interval": 10,
    "enabled": true,
    "intervalUnit": "minutes",
    "expired": true
  },
  "took": 0,
  "requestId": "a19344d1-6ece-4c1c-9c02-cb062e1d21f9"
}
                

Get Heartbeat Request

This is a read request. Therefore, even if the integration of the API key is configured as read-only, the request will be accepted.

Get heartbeat request is used to retrieve details of heartbeat monitors in OpsGenie. It takes the following parameters:

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

Sample Request

curl -X GET --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'
Response:
{
  "code": 200,
  "data": {
    "name": "HeartbeatName",
    "description": "sample heartbeat",
    "interval": 10,
    "enabled": true,
    "intervalUnit": "minutes",
    "expired": true,
  },
  "took": 0,
  "requestId": "9bc9e05b-2f07-44b3-9be0-cb0ec0c45533"
}
                

Update Heartbeat Request 

Update Heartbeat request is used to change configuration of existing heartbeats.

Available Methods

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

Optional Parameters

Parameter Limit
interval Specifies how often a heartbeat message should be expected. 
intervalUnit Interval specified as minutes, hours or days
description An optional description of the heartbeat 10000 chars
enabled Enable/disable heartbeat monitoring

Request Headers

Parameter
Content-Type application/json
Sample Request
curl -X PATCH --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' --header 'Content-Type: application/json' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'-d'
{
    "interval": "5",
    "intervalUnit": "hours",
    "description": "updated heartbeat",
    "enabled": true
}'
Response:
{
  "code": 200,
  "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. It takes the following parameters:

Available Methods

HTTP Method URL
DELETE https://api.opsgenie.com/v2/heartbeats/$heartbeatName
Sample Request
curl -X DELETE --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName'
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. It takes the following parameters:

Available Methods

HTTP Method URL
POST, PUT, PATCH https://api.opsgenie.com/v2/heartbeats/$heartbeatName/enable
Sample Requests
curl -X POST --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/enable' 
curl -X PUT --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/enable' 
curl -X PATCH --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/enable' 
Response:
{
  "code": 200,
  "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. It takes the following parameters:

Available Methods

HTTP Method URL
POST, PUT, PATCH https://api.opsgenie.com/v2/heartbeats/$heartbeatName/disable
Sample Requests
curl -X POST --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/disable' 
curl -X PUT --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/disable' 
curl -X PATCH --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889' 'https://api.opsgenie.com/v2/heartbeats/HeartbeatName/disable' 
Response:
 {
  "code": 200,
  "data": {
    "name": "HeartbeatName",
    "enabled": false,
    "expired": true
  },
  "took": 0,
  "requestId": "1f77b0ea-dd20-40de-94ec-e875a09e8cc9"
}