Telemetry API¶

For whoever maintains the service. If you're putting telemetry in a game, you want Adding it to a game instead — you don't need any of this.

Base URL: https://telemetry.ardenttitanite.com Auth: X-Telemetry-Key header.

Two keys, and they must differ:

Key	For	Can
`INGEST_KEY`	The games	Write segments, register games
`READ_KEY`	Consumers	Read only

A leaked read key can't forge activity. That's the point of splitting them.

POST /v1/segments¶

{
  "eventId": "a-guid-generated-once-per-batch",
  "gameKey": "genesius",
  "placeId": "137231719757604",
  "jobId": "server-job-id",
  "serverTime": 1785735243003,
  "segments": [
    {
      "robloxId": "1234567890",
      "username": "Someone",
      "team": "Blue",
      "startedAt": 1785734043003,
      "endedAt": 1785735243003,
      "reason": "leave"
    }
  ]
}

Response	Means
`201 {duplicate: false}`	Stored
`200 {duplicate: true}`	Already had this `eventId`. Nothing counted twice.
`400`	Malformed. Retrying won't help.
`403`	Game isn't registered, or is disabled.
`401`	Wrong key.

Reuse eventId when retrying. That's the whole idempotency story — the sender never has to know whether its first attempt landed.

robloxId is a string. A Roblox ID above 2^53 rounds as a JSON number, and a rounded ID writes one player's session onto someone else's account.

POST /v1/games¶

Register a game. Holding the ingest key isn't enough to report — a game has to be registered too, so one game can be switched off without rotating everyone's key.

{ "gameKey": "genesius", "label": "GENESIUS Territory", "placeId": "137231719757604" }

POST /v1/games/:gameKey/disable¶

Stops that game reporting. Its existing records are untouched.

GET /v1/playtime¶

?gameKey=genesius&since=<ms>&until=<ms> — defaults to the last 7 days.

Computed from the raw rows on every request, excluded segments left out. Deliberately not a running total: a total that drifts can't be checked, whereas this can be recomputed and compared against the envelopes it came from.

GET /v1/stats¶

Envelope, segment, excluded and game counts. Good for a health check.

When a segment gets flagged¶

Reason	Rule
ends before it starts	`endedAt` earlier than `startedAt`
longer than the ceiling	over `MAX_SEGMENT_MS`, default 12 hours
starts in the future	beyond `MAX_CLOCK_SKEW_MS`, default 6 hours ahead
non-numeric timestamps	not a number

Flagged segments are stored, excluded from totals, and never deleted.

Running it¶

cd ~/titan-telemetry
git pull && npm ci && npm run build
sudo systemctl restart titan-telemetry
sudo journalctl -u titan-telemetry -f

Port 8794 on 127.0.0.1, published by the cloudflared-titan-telemetry tunnel. Database at ~/titan-telemetry/data/telemetry.sqlite.