Ingestion Endpoint

The ingestion endpoint records that a monitored event occurred.

Request

GET  https://heartbeet.downfall24.com/api/v1/beet/:token
POST https://heartbeet.downfall24.com/api/v1/beet/:token

Path parameters

POST body (optional)

{
  "value": 42
}

The value field is stored for future use. It is not currently used in anomaly detection.

Headers (POST only, when sending body)

Content-Type: application/json

Response

The endpoint always returns a 200 OK with a 1×1 transparent GIF body, regardless of whether the event was recorded successfully. This is intentional — image beacon integrations must not cause JavaScript errors or visible broken images.

HTTP/1.1 200 OK
Content-Type: image/gif

Rate limiting

Requests are rate-limited to 60 per 10 seconds per token (sliding window, via Upstash Redis).

Exceeded rate limit responses:

HTTP/1.1 429 Too Many Requests

The response body is still the 1×1 GIF to avoid breaking image beacon integrations.

Examples

HTML image beacon

<img
  src="https://heartbeet.downfall24.com/api/v1/beet/beet_abc123xyz"
  width="1"
  height="1"
  alt=""
  style="display:none"
/>

JavaScript fetch

fetch('https://heartbeet.downfall24.com/api/v1/beet/beet_abc123xyz', {
  method: 'POST',
  keepalive: true,
})

curl

curl -s "https://heartbeet.downfall24.com/api/v1/beet/beet_abc123xyz" > /dev/null

Python

import requests
requests.get('https://heartbeet.downfall24.com/api/v1/beet/beet_abc123xyz')

Node.js

await fetch('https://heartbeet.downfall24.com/api/v1/beet/beet_abc123xyz')

GitHub Actions

- name: Ping Heartbeet
  run: curl -s "${{ secrets.HEARTBEET_BEET_URL }}" > /dev/null

Security

Tokens are opaque random strings. They are not tied to API keys or user sessions — anyone with the token can record events. Keep your token private. Rotate it immediately if it is exposed.

Tokens can be rotated on the beet detail page. The old token is invalidated immediately upon rotation.