Sending events

Everything in TopStats starts with an event, and every event reaches us the same way: a POST to one endpoint. There is no separate endpoint per event type and no SDK to learn first. You send JSON, we accept it, and it shows up in your dashboards.

The endpoint

Send every event to a single URL and authenticate with your API key as a Bearer token:

POST https://topstats.gg/v1/events
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

The API key alone decides which workspace and which environment the event lands in, so you never put a workspace id in the request. A production key writes to production, a development key writes to development. If you want to change where events go, you swap the key, not the payload.

The event payload

The request body is either one event object or a batch of them (see Batching). A single event has these six fields, and only these. Any field you send that is not on this list is rejected, which helps you catch typos early.

Notice the underscore on _source, _actor, _actorLabel and _timestamp. Those are reserved platform fields, and the underscore prefix keeps them from ever clashing with a property of your own. Your name and everything inside properties belong to you, so you are free to use a plain source or actor key in properties without colliding with the reserved ones.

Example

The curl tab is handy for a quick test from your terminal. The JavaScript tab is the shape you would use from a Node.js backend, reading the key from an environment variable so it never gets committed to your code.

curl -X POST https://topstats.gg/v1/events \
  -H "Authorization: Bearer ts_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "player_join",
    "properties": { "playtime": 42, "map": "desert", "perks": ["double_jump", "shield"] },
    "_source": "eu-west-1",
    "_actor": "user_123",
    "_actorLabel": "Ada Lovelace",
    "_timestamp": "2026-07-22T10:00:00Z"
  }'

The response

A successful call returns 202 Accepted with a small JSON body telling you how many events were stored:

{ "accepted": 1 }

The 202 status means "accepted for processing", so you do not have to wait for the event to appear in a dashboard before moving on. As long as you get a 202, the event is in.