Ingestion for anything that isn't Godot
Building for the web or Node? The JavaScript SDK wraps everything below in a zero-dependency client with batching, an offline queue, and tab-close flushing. Unity developers use the Unity SDK, and LÖVE games use the LÖVE SDK. Everything else speaks plain HTTP.
The Godot SDK is a client for this same surface. If you're on Unity, Unreal, a browser game, or anything else, this is what to call directly. The ingest endpoints answer any web origin, so browser games on GitHub Pages, itch.io or your own site need no CORS setup.
Base URL
https://api.ravensight.io
POST /api/v1/session
Opens a session for a device. Auth: X-API-Key (your ingest key). The game identity comes from the key, never from the body.
Request
POST /api/v1/session
X-API-Key: gt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
{
"deviceId": "3f9ac2e17b5d4c0e8a61f2b9d7c04e5a-windows",
"gameVersion": "1.4.2",
"platform": "Windows"
}
Response, 201
{
"token": "st_9f2c...redacted",
"expiresAt": "2026-08-29T16:00:00.000Z",
"expiresIn": 86400
}
Errors: 400 missing_device_id when deviceId
is absent, 401 invalid_api_key or
missing_api_key, 403 tracking_disabled when
the game's kill switch is off, 429 rate_limited at more
than 60 session creations per minute for the game.
A live key is never refused over what a device sends here, because an
SDK would resend the same request for ever. A platform or
gameVersion loses any control characters (line breaks,
tabs, escape codes) and is then cut to 128 characters, one that is
neither text nor a number is left out, and a deviceId past
256 characters is stored as a short id derived from it by hash, so the
same device stays one device.
Distribution. The body may carry an optional
distribution, a string of at most 40 characters naming
where the build was distributed, such as native-release
or web-itch, with no control characters. It is stored on
the session as the client declared it and added to each of the
session's events as a distribution property unless the
event sends its own (400 invalid_distribution for
anything that is not such a string).
With a public key,
/session can also answer 403 key_expired,
403 key_paused, 403 origin_not_allowed when
the key enforces its origin list, 403 origin_required
when it also requires one and the request sends no
Origin, 403 version_not_allowed
when gameVersion is missing or not on the key's version
list, 403 public_key_forbidden for a doctor session or a
playtest run, which need the game's live key,
400 invalid_device_id for a device id that is not
text or over 256 characters, 400 invalid_platform or
invalid_game_version for one past 128 characters, not
text, or holding a control character such as a line break or tab, and 429 rate_limited from the key's own
session limits. The session token lives the key's
session_ttl_seconds, or until the key's expiry date if
that comes first.
Joining a session. Send joinToken, the
token of a live session from the same game, instead of a
deviceId, and the new session shares that session's
analytics session id and device id. Use it when a second client of
the same player, such as your game server, should report into the
player's session. The new session keeps its own
platform and gameVersion and never outlives
the one it joined. The answer carries the same token,
expiresAt and expiresIn plus
joined: true and synthetic, which the server
decides from the session that was joined, so your game server can
rely on it instead of a flag the browser sends. A fresh session's
answer carries neither field. A
deviceId in the same body never becomes the new
session's device id. A join from a
synthetic (playtest) session stays synthetic: the new session belongs
to the same run, its events are marked synthetic and are never
metered, and feedback sent through it is marked synthetic too. It
keeps the playtest's own platform whatever the body says, and once
the run or its job has finished, its events and feedback answer
403 playtest_job_closed. When a join from a synthetic
session also sends the player's own deviceId, that
device's real sessions in the same game from the last 15 minutes
join the run too, their events are marked synthetic, and the answer
adds adopted with how many. Events they sent before the
join were already counted on the event meter and are not refunded,
so have your game server open its session with the browser's session
token as joinToken before it tracks the sign-up, and
nothing is tracked as real first.
{
"joinToken": "st_9f2c...redacted",
"gameVersion": "1.4.2",
"platform": "dedicated-server"
}
A join from a playtest session that adopted one earlier session answers:
{
"token": "st_41ab...redacted",
"expiresAt": "2026-10-15T19:30:00.000Z",
"expiresIn": 3600,
"joined": true,
"synthetic": true,
"adopted": 1
}
A token that is unknown, expired, revoked, from another game, or from
a doctor session answers
401 invalid_join_token, the same answer for each, so a
token's existence never leaks; so does a join sent with
"platform": "doctor" or a playtest header. A
platform or gameVersion that is not a
string or number answers 400 invalid_platform or
invalid_game_version on a public key join; a live key joins,
stores a number as text and leaves anything else out. Joins count toward the same 60 a minute.
GET /api/v1/settings
Reads the tracking kill switch, and names the game the key belongs
to, so a client or the doctor can confirm it ships the key for the
game and environment it meant. Auth: X-API-Key.
Response, 200
{
"trackingEnabled": true,
"game": { "slug": "nebula-drifter", "name": "Nebula Drifter", "environment": "production" },
"key": { "kind": "live", "label": null }
}
slug is the key's own game id, never another game's, and
the answer never includes the key or its hash. key says
which kind of key answered: live for the game's
gt_live_ key, or public with the label you
gave a public key.
An address on the game's block list gets 403 ip_blocked,
and more than 30 reads a minute from one address on one key get
429 rate_limited with a Retry-After header.
POST /api/v1/track
Sends a single event. Auth: X-Session-Token (from step above).
Request
POST /api/v1/track
X-Session-Token: st_9f2c...redacted
Content-Type: application/json
{
"event": "level_completed",
"data": { "level": 3, "score": 15000, "time_seconds": 87.4 },
"timestamp": <unix milliseconds, within the last 90 days>
}
Response, 202
{ "accepted": 1 }
timestamp is optional and defaults to the time the server
receives the event. Send unix milliseconds, so that events in one
second keep their order in funnels and sessions. A value below
100,000,000,000 is read as unix seconds and stored on the whole second,
so a client that sends seconds keeps working exactly as it did, and
funnels read its events in one second by step. A timestamp in the
future is stored as now. For timestamps in milliseconds, a clock up to a
minute ahead moves its whole batch back by that much instead, so the
batch keeps its order. An event
whose timestamp is more than 90 days old is dropped: it is not stored and not charged,
and it is counted as timestamp_too_old on the
Implementation health card. The request still succeeds, so
accepted can be lower than the number of events you
sent, on this endpoint and on /track/batch.
A typed event that breaks its contract is
stored with rs_invalid rather than refused, and the 202
body adds "invalid": n only when there was one. A
purchase of 4.99 US dollars, in minor units:
{
"event": "gem_pack_bought",
"data": {
"rs_kind": "purchase",
"rs_amount": 499,
"rs_currency": "USD",
"rs_item_type": "gems",
"rs_item_id": "gem_pack_small"
}
}
POST /api/v1/track/batch
Sends up to 50 events in one call. Same auth as /track.
Request
POST /api/v1/track/batch
X-Session-Token: st_9f2c...redacted
Content-Type: application/json
{
"events": [
{ "event": "level_started", "data": { "level": 3 } },
{ "event": "checkpoint_reached", "data": { "idx": 2 } }
]
}
Response, 202
{ "accepted": 2, "duplicates": 0 }
duplicates counts events skipped because their
rs_event_id was already stored for that device on this
game within the key's dedupe window (at least 24 hours by default); they are
not stored twice and not charged (see
duplicates and retries).
A public key always answers both fields. The live key adds
duplicates only when an event in the request carried an
rs_event_id; otherwise its answer is
{ "accepted": 2 }.
Errors: 400 invalid_batch when events is
missing or empty, 400 batch_too_large above 50 events or
past the 512 KB body limit, so an SDK splits the batch and sends again,
400 missing_event if any entry lacks an
event name.
With a public key, the
key's policy adds these 400 answers, each naming the
index of the first event that broke it (0 on
/track): missing_event,
event_not_allowed (the name is not on the allowlist),
event_too_large (above max_event_bytes),
invalid_event_data, too_many_properties,
payload_too_deep, string_too_long,
invalid_number (a number that is not finite),
reserved_key (an rs_ key Ravensight does
not read, or an rs_kind outside its values) and
invalid_event_id. batch_too_large (above
max_batch) refuses the whole batch and has no index. A
session whose key was paused, revoked or expired answers
401 public_key_inactive: open a new session. It can also answer
429 public_key_ceiling when the batch would take the key
past its optional monthly ceiling; the whole batch is refused and
Retry-After runs to the start of the next UTC month. On
any key, 429 quota_exceeded with
reason: "needs_funds" means the included allowance is
used and the prepaid balance cannot buy the next block of events. Add
funds to keep accepting events. None of these refusals is charged.
Keys that start with rs_ in event data are reserved.
An rs_kind that is not one of the nine kinds,
level_start, level_complete,
death, none, purchase,
resource, progression, error
or health, and any other rs_ key Ravensight does not read, is stored
as sent and counted as rs_kind_unknown or
rs_key_unknown on the Implementation health card.
One is the server's own: rs_link, the
campaign link
a session arrived by. Send it as campaignLink on
POST /session, never in event data: one in event data is
replaced by the session's, or dropped.
What the dashboard reads from your events.
level, location and track in
data fold into one place, and the first non-empty one wins.
The level funnel counts three kinds at a place: level_start,
level_complete and death. Set
rs_kind to say which one an event is; without it the kind
is read from the event name. An event with a place and none of those
kinds is shown as navigation only, stays out of the funnel, and is
counted as place_without_kind on the Implementation health
card. Send rs_kind: "none" when the place is intentional.
The full rules are in
how the built-in detections read your events.
GET /api/v1/agent/suggestions
Experimental, machine-readable design suggestions from your weekly
digest. Auth: X-API-Key. Returns an empty array until a
digest has run for your game.
{ "suggestions": [] }
GET /api/v1/doctor/ping/:nonce
The read-back for the doctor's live check.
Auth: X-API-Key. A session opened with
"platform": "doctor" lives ten minutes, gets a device id
the server chooses, and may send only
ravensight_doctor_ping, ten a minute per game
(400 doctor_event_only for any other name, and for
feedback and player reports). Its events are kept out of your
analytics and your event usage. This endpoint
answers whether the ping whose rs_doctor value is
:nonce, 32 lowercase hex characters, was stored for the
key's game in the last 15 minutes.
Response, 200
{ "found": true, "acceptedAt": "2026-10-10T12:00:01.250Z" }
404 {"found": false, "error": "ping_not_found"} until
the event is stored, which can take a few seconds while it is
batched. 400 invalid_nonce for a malformed nonce,
429 rate_limited above 30 reads a minute for the game,
503 storage_unavailable when event storage is down. A
nonce sent by another game reads as not found.
POST /api/v1/feedback
Auth: X-Session-Token.
Request
POST /api/v1/feedback
X-Session-Token: st_9f2c...redacted
Content-Type: application/json
{
"message": "Level 3's second checkpoint feels unfair.",
"category": "suggestion",
"rating": 4
}
Response, 201
{ "id": "66c1f2a9d4e8b0021f9a7c31" }
category and rating are both optional.
When present, category must be one of bug,
suggestion, complaint, praise,
playtest, or other.
Errors
| Status | Error | Meaning |
|---|---|---|
| 400 | missing_device_id, missing_event, invalid_batch, batch_too_large, event_name_too_long, event_too_large, invalid_event_data, missing_message, message_too_long, invalid_category, invalid_feedback, doctor_event_only, invalid_nonce, invalid_distribution | Malformed request body or a payload ceiling (see Limits). |
| 400 | missing_event, event_not_allowed, batch_too_large, event_too_large, invalid_event_data, too_many_properties, payload_too_deep, string_too_long, invalid_number, reserved_key, invalid_event_id | A public key's policy refused an event. The answer carries the index of the first offending event (none for batch_too_large, which refuses the whole batch). Drop that event and never retry it. |
| 400 | invalid_device_id, invalid_platform, invalid_game_version | On a public key's /session: a device id that is not text or over 256 characters, or a platform or game version over 128 characters, not text, or holding a control character. A live key stores bounded values instead of refusing. |
| 401 | missing_api_key, invalid_api_key, invalid_join_token, or a missing/expired session token | Bad or absent credentials for the header the endpoint expects, or a joinToken that cannot be joined. |
| 404 | ping_not_found | The doctor's ping is not stored yet, or was never sent for this game. Only returned by GET /api/v1/doctor/ping/:nonce. |
| 403 | tracking_disabled | The game's server-side kill switch is off. Only returned by POST /api/v1/session. |
| 401 | public_key_inactive | The public key that opened this session is paused, revoked or expired. Open a new session, which answers the key's real state. |
| 403 | key_expired, key_paused, origin_not_allowed, origin_required, version_not_allowed, public_key_forbidden | A public key is expired or paused, its policy refused the origin, a missing origin or the version, or it called an endpoint public keys cannot use. Stop for this run. |
| 429 | rate_limited | Per-game ceiling hit: 60 session creations or 600 tracked events per minute, or one of a public key's own limits per key, session or device id. Carries a Retry-After header in seconds. |
| 429 | quota_exceeded | Monthly event quota reached for this account. Carries a Retry-After header, in seconds until the quota resets at the next UTC month. With reason: "needs_funds", the prepaid balance cannot buy the next block of events: add funds to keep accepting events. |
| 429 | public_key_ceiling | A public key reached the optional monthly ceiling its owner set. Carries a Retry-After header to the next UTC month. Nothing in the refused batch was stored or charged. |
| 503 | storage_unavailable | Event storage is temporarily unavailable. Carries Retry-After: 60; nothing was accepted or charged against quota. |