Heartbeats API

Manage your heartbeats using simple HTTP API.

Do you need help with the integration?

Let us know at [email protected].

Obtaining an API token

Please, see Obtaining an API token.

get
Listing all existing heartbeats

https://betteruptime.com/api/v2/heartbeats
Returns the list of your heartbeats.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
The status attribute can have one of the following values: paused - the heartbeat was paused pending - the heartbeat was just created and it's waiting for the first request up - heartbeat received a request on time down - heartbeat did not receive a request on time
{
"data": [
{
"id": "12345",
"type": "heartbeat",
"attributes": {
"url": "https://betteruptime.com/api/v1/heartbeat/abcd1234abcd1234abcd1234",
"name": "Testing heartbeat",
"period": 10800,
"grace": 300,
"call": false,
"sms": false,
"email": true,
"push": true,
"team_wait": 180,
"heartbeat_group_id": null,
"sort_index": null,
"paused_at": null,
"created_at": "2020-05-05T11:41:49.327Z",
"updated_at": "2020-12-10T14:40:23.436Z",
"status": "up"
}
}
],
"pagination": {
"first": "https://betteruptime.com/api/v2/heartbeats?page=1",
"last": "https://betteruptime.com/api/v2/heartbeats?page=1",
"prev": null,
"next": null
}
}
Example cURL
Example cURL
curl --request GET \
--url https://betteruptime.com/api/v2/heartbeats \
--header 'Authorization: Bearer YOUR_API_TOKEN'

get
Getting a single heartbeat

https://betteruptime.com/api/v2/heartbeats/:heartbeat_id
Returns a single heartbeat.
Request
Response
Request
Path Parameters
heartbeat_id
required
string
The ID of your requested heartbeat
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
The requested heartbeat. The status attribute can have one of the following values: paused - the heartbeat was paused pending - the heartbeat was just created and it's waiting for the first request up - heartbeat received a request on time down - heartbeat did not receive a request on time
{
"data": {
"id": "12345",
"type": "heartbeat",
"attributes": {
"url": "https://betteruptime.com/api/v1/heartbeat/abcd1234abcd1234abcd1234",
"name": "Testing heartbeat",
"period": 10800,
"grace": 300,
"call": false,
"sms": false,
"email": true,
"push": true,
"team_wait": 180,
"heartbeat_group_id": null,
"sort_index": null,
"paused_at": null,
"created_at": "2020-05-05T11:41:49.327Z",
"updated_at": "2020-12-10T15:00:15.089Z",
"status": "up"
}
}
}
Example cURL
Example cURL
curl --request GET \
--url https://betteruptime.com/api/v2/heartbeats/12345 \
--header 'Authorization: Bearer YOUR_API_TOKEN'

post
Creating a heartbeat

https://betteruptime.com/api/v2/heartbeats
Returns a newly created heartbeat or validation errors.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Content-Type
required
string
application/json
Form Data Parameters
name
required
string
A name of the service for this heartbeat.
period
required
integer
How often should we expect this heartbeat? In seconds Minimum value: 30 seconds
grace
required
integer
Heartbeats can fluctuate; specify this value to control what is still acceptable Minimum value: 0 seconds We recommend setting this to approx. 20% of period
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long should we wait before escalating the incident alert to the team? Leave blank to disable escalating to the entire team.
heartbeat_group_id
optional
string
Set this attribute if you want to add this heartbeat to a heartbeat group.
sort_index
optional
integer
An index controlling the position of a heartbeat in the heartbeat group.
paused
optional
boolean
Set to true to pause monitoring — we won't notify you about downtime. Set to false to resume monitoring
Response
201: Created
Returns a newly created heartbeat
{
"data": {
"id": "12345",
"type": "heartbeat",
"attributes": {
"url": "https://betteruptime.com/api/v1/heartbeat/abcd1234abcd1234abcd1234",
"name": "Testing heartbeat",
"period": 10800,
"grace": 300,
"call": false,
"sms": false,
"email": true,
"push": true,
"team_wait": 180,
"heartbeat_group_id": null,
"sort_index": null,
"paused_at": null,
"created_at": "2020-05-05T11:41:49.327Z",
"updated_at": "2020-12-10T15:00:15.089Z"
}
}
}
422: Unprocessable Entity
Validation failed
{
"errors": {
"name": [
"Can't be blank."
]
}
}
Example cURL
Example cURL
curl --request POST \
--url https://betteruptime.com/api/v2/heartbeats \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Testing heartbeat",
"period": 10800,
"grace": 300
}'

patch
Updating an existing endpoint

https://betteruptime.com/api/v2/heartbeats/:heartbeat_id
Update an existing heartbeat configuration. Send only the parameters you wish to change (e.g. name)
Request
Response
Request
Path Parameters
heartbeat_id
required
string
The ID of the heartbeat you want to update
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Content-Type
required
string
application/json
Form Data Parameters
name
optional
string
A name of the service for this heartbeat.
period
optional
integer
How often should we expect this heartbeat? In seconds Minimum value: 30 seconds
grace
optional
integer
Heartbeats can fluctuate; specify this value to control what is still acceptable Minimum value: 0 seconds We recommend setting this to approx. 20% of period
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long should we wait before escalating the incident alert to the team? Leave blank to disable escalating to the entire team.
heartbeat_group_id
optional
string
Set this attribute if you want to add this heartbeat to a heartbeat group.
sort_index
optional
integer
An index controlling the position of a heartbeat in the heartbeat group.
paused
optional
boolean
Set to true to pause monitoring — we won't notify you about downtime. Set to false to resume monitoring
Response
200: OK
{
"data": {
"id": "12345",
"type": "heartbeat",
"attributes": {
"url": "https://betteruptime.com/api/v1/heartbeat/abcd1234abcd1234abcd1234",
"name": "Testing heartbeat, with an update",
"period": 10800,
"grace": 300,
"call": false,
"sms": false,
"email": true,
"push": true,
"team_wait": 180,
"heartbeat_group_id": null,
"sort_index": null,
"paused_at": null,
"created_at": "2020-05-05T11:41:49.327Z",
"updated_at": "2020-12-10T15:00:15.089Z"
}
}
}
Example cURL
Example cURL
curl --request PATCH \
--url https://betteruptime.com/api/v2/heartbeats/12345 \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Testing heartbeat, with an update"
}'

delete
Deleting an existing heartbeat

https://betteruptime.com/api/v2/heartbeats/:heartbeat_id
Request
Response
Request
Path Parameters
heartbeat_id
required
string
The ID of the heartbeat you want to delete
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
204: No Content
No content
Example cURL
Example cURL
curl --request DELETE \
--url https://betteruptime.com/api/v2/heartbeats/12345 \
--header 'Authorization: Bearer YOUR_API_TOKEN'