API

The API is the primary way of using heartbeat.sh after you've set up your server.

Use https://{your-subdomain}.heartbeat.sh/ as the base URL for all requests.

Sending A Heartbeat

Add or update a heartbeat specified by {name}. The name may contain alphanumeric characters, -, _, or :. Using : is a nice way to set up tags or namespaces for your heartbeats. For existing heartbeats, warning or error won't override the timeouts if left unspecified.

• Endpoint: beat/{name}

• Methods: POST, PUT

• Query:

  • warning: string or int; optional

    The warning timeout as an integer containing seconds or a string which can be parsed to seconds. Defaults to one minute if not specified.

  • error: string or int; optional

    The error timeout as an integer containing seconds or a string which can be parsed to seconds. Defaults to 5 times the warning timeout if not specified.

• Example:

  curl -X POST 'https://example.heartbeat.sh/beat/example:docs?warning=1d2h3m4s&error=4d3h2m1s'

  {
    "Name": "example:docs",
    "Warning": 93784,
    "Error": 356521,
    "Age": 0,
    "Status": "OK",
    "LastBeat": "2020-08-27T07:40:16.995067227Z"
  }

Getting Heartbeats

Download all your heartbeats in a format that is easy for programs to understand.

• Endpoint: heartbeats/{type}

• Methods: GET

• Query:

  • type: string; optional

    Either text or json. Defaults to json

• Default Example:

  curl 'https://example.heartbeat.sh/heartbeats/'

  {
    "Heartbeats": [
      {
        "Name": "example:docs",
        "Warning": 93784,
        "Error": 356521,
        "Age": 38062,
        "Status": "OK",
        "LastBeat": "2020-09-01T00:00:02Z"
      },
      {
        "Name": "example:js",
        "Warning": 93600,
        "Error": 172800,
        "Age": 85641,
        "Status": "OK",
        "LastBeat": "2020-08-31T10:47:03Z"
      }
    ]
  }

• Text Example:

  curl 'https://example.heartbeat.sh/heartbeats/text'

  example:docs                     OK      2020-09-01 00:00:02 UTC 10h37m44s    26h3m4s      4d3h2m1s    
  example:js                       OK      2020-08-31 10:47:03 UTC 23h50m43s    26h0m0s      2d0s