GET/{heartbeat_id}

Send a heartbeat (GET)

Send a heartbeat ping (GET). Use this from scripts or cron jobs to signal completion. Note: This endpoint uses oonchk.com, not api.onlineornot.com.

This operation does not require authentication

Path parameters

heartbeat_id:string
Heartbeat ID

Responses

StatusMeaningDescription
200OKAccepted for asynchronous processing, with an empty body. Does not guarantee the ping was recorded: missing, paused, early pings and processing failures can still return 200. Request body and query are ignored.
404Not FoundInvalid heartbeat ID
429Too Many RequestsToo many requests for this heartbeat ID. Retry later.
500Internal Server ErrorInternal Server Error

Request

GET
/{heartbeat_id}
curl --request GET \
  --url https://oonchk.com/a1b2c3d4 \
  --header 'Accept: text/plain'

404 Response

"string"
POST/{heartbeat_id}

Send a heartbeat (POST)

Send a heartbeat ping (POST). Use this from scripts or cron jobs to signal completion. Note: This endpoint uses oonchk.com, not api.onlineornot.com.

This operation does not require authentication

Path parameters

heartbeat_id:string
Heartbeat ID

Responses

StatusMeaningDescription
200OKAccepted for asynchronous processing, with an empty body. Does not guarantee the ping was recorded: missing, paused, early pings and processing failures can still return 200. Request body and query are ignored.
404Not FoundInvalid heartbeat ID
429Too Many RequestsToo many requests for this heartbeat ID. Retry later.
500Internal Server ErrorInternal Server Error

Request

POST
/{heartbeat_id}
curl --request POST \
  --url https://oonchk.com/a1b2c3d4 \
  --header 'Accept: text/plain'

404 Response

"string"
GET/v1/heartbeats

List all heartbeats

Retrieve a paginated list of all heartbeat monitors

Requires HEARTBEAT_CHECKS:READ; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Query parameters

page:integeroptional
Page number of paginated results, starting at 1.
Default: 1
per_page:integeroptional
Number of items per page. Defaults to 20. Continue requesting subsequent pages until the accumulated item count reaches result_info.total_count or a page is empty.
Default: 20
search:stringoptional
Search term to filter results.

Responses

StatusMeaningDescription
200OKReturns a list of OnlineOrNot Heartbeats. May also return a canonical failure envelope with success: false at HTTP200.
400Bad RequestInvalid request
401UnauthorizedMissing or invalid credentials
403ForbiddenInsufficient permissions
500Internal Server ErrorInternal Server Error

Response Schema

success:boolean
false
result:null
errors:object[]
messages:[any]

Request

GET
/v1/heartbeats
curl --request GET \
  --url https://api.onlineornot.com/v1/heartbeats \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "result": [
    {
      "id": "a1b2c3d4",
      "name": "Daily backup job",
      "status": "UP",
      "last_seen": "2021-01-01T00:00:00.000Z",
      "report_period": 3600,
      "report_period_cron": "0 0 * * *",
      "timezone": "America/New_York",
      "grace_period": 300,
      "reminder_alert_interval_minutes": 1440,
      "alert_priority": "LOW",
      "created_at": "2021-01-01T00:00:00.000Z",
      "updated_at": "2021-01-01T00:00:00.000Z"
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 1,
    "total_count": 1
  },
  "success": true,
  "errors": [],
  "messages": []
}
POST/v1/heartbeats

Create a heartbeat.

Create a new heartbeat monitor for cron jobs or scheduled tasks

Requires HEARTBEAT_CHECKS:EDIT; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Body parameters

name:string
report_period:integeroptional
Expected interval in seconds between heartbeat pings (for simple schedule)
report_period_cron:stringoptional
Cron expression for expected heartbeat schedule
timezone:stringoptional
Timezone for cron schedule
grace_period:integer
Grace period in seconds to wait after missed heartbeat before alerting
reminder_alert_interval_minutes:integeroptional
Interval in minutes between reminder alerts (-1 for never)
Default: 1440
user_alerts:string[]optional
User IDs to notify
slack_alerts:string[]optional
Slack integration IDs to notify
discord_alerts:string[]optional
Discord integration IDs to notify
webhook_alerts:string[]optional
IDs of webhooks to associate with this heartbeat
oncall_alerts:string[]optional
IDs of on-call integrations (Grafana, PagerDuty, Opsgenie, Spike)
incident_io_alerts:string[]optional
incident.io integration IDs to notify
microsoft_teams_alerts:string[]optional
Microsoft Teams integration IDs to notify
telegram_alerts:string[]optional
Telegram integration IDs to notify
pushover_alerts:string[]optional
Pushover integration IDs to notify
alert_priority:stringoptional
[Alert priority](https://onlineornot.com/docs/how-to/alerts/configure-priority).
Accepted values: "LOW" | "HIGH"
Default: "LOW"

Responses

StatusMeaningDescription
201CreatedCreate a new OnlineOrNot Heartbeat
400Bad RequestInvalid request
401UnauthorizedMissing or invalid credentials
403ForbiddenInsufficient permissions
500Internal Server ErrorInternal Server Error

Response Schema

result:any
*anonymous*:objectoptional
*anonymous*:objectoptional
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

POST
/v1/heartbeats
curl --request POST \
  --url https://api.onlineornot.com/v1/heartbeats \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --header 'X-OnlineOrNot-Organisation: string' \
  --data '{"name":"Daily backup job","report_period":86400,"grace_period":300}'

Response

{
  "result": {
    "id": "a1b2c3d4",
    "name": "Daily backup job",
    "status": "UP",
    "last_seen": "2021-01-01T00:00:00.000Z",
    "report_period": 3600,
    "report_period_cron": "0 0 * * *",
    "timezone": "America/New_York",
    "grace_period": 300,
    "reminder_alert_interval_minutes": 1440,
    "alert_priority": "LOW",
    "created_at": "2021-01-01T00:00:00.000Z",
    "updated_at": "2021-01-01T00:00:00.000Z",
    "user_alerts": [
      "string"
    ],
    "slack_alerts": [
      "string"
    ],
    "discord_alerts": [
      "string"
    ],
    "webhook_alerts": [
      "string"
    ],
    "oncall_alerts": [
      "string"
    ],
    "incident_io_alerts": [
      "string"
    ],
    "microsoft_teams_alerts": [
      "string"
    ],
    "telegram_alerts": [
      "string"
    ],
    "pushover_alerts": [
      "string"
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
GET/v1/heartbeats/{heartbeat_id}

Retrieve a heartbeat

Look up detailed information about a specific heartbeat monitor

Requires HEARTBEAT_CHECKS:READ; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

heartbeat_id:string
Heartbeat ID

Responses

StatusMeaningDescription
200OKRetrieve the specified OnlineOrNot Heartbeat
400Bad RequestInvalid request
401UnauthorizedMissing or invalid credentials
403ForbiddenInsufficient permissions
404Not FoundHeartbeat not found or unavailable
500Internal Server ErrorInternal Server Error

Response Schema

result:any
*anonymous*:objectoptional
*anonymous*:objectoptional
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

GET
/v1/heartbeats/{heartbeat_id}
curl --request GET \
  --url https://api.onlineornot.com/v1/heartbeats/a1b2c3d4 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "result": {
    "id": "a1b2c3d4",
    "name": "Daily backup job",
    "status": "UP",
    "last_seen": "2021-01-01T00:00:00.000Z",
    "report_period": 3600,
    "report_period_cron": "0 0 * * *",
    "timezone": "America/New_York",
    "grace_period": 300,
    "reminder_alert_interval_minutes": 1440,
    "alert_priority": "LOW",
    "created_at": "2021-01-01T00:00:00.000Z",
    "updated_at": "2021-01-01T00:00:00.000Z",
    "user_alerts": [
      "string"
    ],
    "slack_alerts": [
      "string"
    ],
    "discord_alerts": [
      "string"
    ],
    "webhook_alerts": [
      "string"
    ],
    "oncall_alerts": [
      "string"
    ],
    "incident_io_alerts": [
      "string"
    ],
    "microsoft_teams_alerts": [
      "string"
    ],
    "telegram_alerts": [
      "string"
    ],
    "pushover_alerts": [
      "string"
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
PATCH/v1/heartbeats/{heartbeat_id}

Update a heartbeat.

Modify the configuration of an existing heartbeat monitor

Requires HEARTBEAT_CHECKS:EDIT; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

heartbeat_id:string
Heartbeat ID

Body parameters

name:stringoptional
report_period:integernulloptional
Expected interval in seconds between heartbeat pings (for simple schedule)
report_period_cron:stringnulloptional
Cron expression for expected heartbeat schedule
timezone:stringnulloptional
Timezone for cron schedule
grace_period:integeroptional
Grace period in seconds to wait after missed heartbeat before alerting
reminder_alert_interval_minutes:integeroptional
Interval in minutes between reminder alerts (-1 for never)
user_alerts:string[]optional
User IDs to notify
slack_alerts:string[]optional
Slack integration IDs to notify
discord_alerts:string[]optional
Discord integration IDs to notify
webhook_alerts:string[]optional
IDs of webhooks to associate with this heartbeat
oncall_alerts:string[]optional
IDs of on-call integrations (Grafana, PagerDuty, Opsgenie, Spike)
incident_io_alerts:string[]optional
incident.io integration IDs to notify
microsoft_teams_alerts:string[]optional
Microsoft Teams integration IDs to notify
telegram_alerts:string[]optional
Telegram integration IDs to notify
pushover_alerts:string[]optional
Pushover integration IDs to notify
alert_priority:stringoptional
[Alert priority](https://onlineornot.com/docs/how-to/alerts/configure-priority).
Accepted values: "LOW" | "HIGH"
paused:booleanoptional
Whether the heartbeat is paused
muted:booleanoptional
Suppresses alerts without stopping heartbeat monitoring.

Responses

StatusMeaningDescription
200OKModify an OnlineOrNot Heartbeat
400Bad RequestInvalid request
401UnauthorizedMissing or invalid credentials
403ForbiddenInsufficient permissions
500Internal Server ErrorInternal Server Error

Response Schema

result:any
*anonymous*:objectoptional
*anonymous*:objectoptional
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

PATCH
/v1/heartbeats/{heartbeat_id}
curl --request PATCH \
  --url https://api.onlineornot.com/v1/heartbeats/a1b2c3d4 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --header 'X-OnlineOrNot-Organisation: string' \
  --data '{"report_period":7200,"grace_period":600}'

Response

{
  "result": {
    "id": "a1b2c3d4",
    "name": "Daily backup job",
    "status": "UP",
    "last_seen": "2021-01-01T00:00:00.000Z",
    "report_period": 3600,
    "report_period_cron": "0 0 * * *",
    "timezone": "America/New_York",
    "grace_period": 300,
    "reminder_alert_interval_minutes": 1440,
    "alert_priority": "LOW",
    "created_at": "2021-01-01T00:00:00.000Z",
    "updated_at": "2021-01-01T00:00:00.000Z",
    "user_alerts": [
      "string"
    ],
    "slack_alerts": [
      "string"
    ],
    "discord_alerts": [
      "string"
    ],
    "webhook_alerts": [
      "string"
    ],
    "oncall_alerts": [
      "string"
    ],
    "incident_io_alerts": [
      "string"
    ],
    "microsoft_teams_alerts": [
      "string"
    ],
    "telegram_alerts": [
      "string"
    ],
    "pushover_alerts": [
      "string"
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
DELETE/v1/heartbeats/{heartbeat_id}

Delete a heartbeat

Permanently delete a heartbeat monitor

Requires HEARTBEAT_CHECKS:EDIT; EDIT also grants READ. Session cookies are accepted only when no bearer credential is supplied.

Security: Bearer Auth

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Header parameters

X-OnlineOrNot-Organisation:stringoptional
Public organization ID to select from an OAuth grant. Required for grants authorizing multiple organizations. Omit for single-organization grants and API tokens.

Path parameters

heartbeat_id:string
Heartbeat ID

Responses

StatusMeaningDescription
200OKReturns the deleted OnlineOrNot Heartbeat's ID
400Bad RequestInvalid request
401UnauthorizedMissing or invalid credentials
403ForbiddenInsufficient permissions
500Internal Server ErrorInternal Server Error

Response Schema

result:object
success:boolean
Whether the API call was successful
errors:object[]
messages:object[]

Request

DELETE
/v1/heartbeats/{heartbeat_id}
curl --request DELETE \
  --url https://api.onlineornot.com/v1/heartbeats/a1b2c3d4 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'X-OnlineOrNot-Organisation: string'

Response

{
  "result": {
    "id": "a1b2c3d4"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Was this page helpful?