# Ingestion for anything that isn't Godot

Building for the web or Node? The [JavaScript SDK](https://ravensight.io/docs/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](https://github.com/Reality-Software-Entertainment/ravensight-unity), and LÖVE games use the [LÖVE SDK](https://ravensight.io/docs/love-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](https://ravensight.io/docs/public-builds/)**, `/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](https://ravensight.io/docs/public-builds/).

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](https://ravensight.io/docs/dashboard/#typed-events) 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](https://ravensight.io/docs/public-builds/#public-timestamps-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](https://ravensight.io/docs/public-builds/)**, 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](https://ravensight.io/docs/campaign-links/#campaign-links-players) 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](https://ravensight.io/docs/dashboard/#detection-rules).

## 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](https://ravensight.io/docs/doctor/). 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. |

Source: https://ravensight.io/docs/http-api/
Last updated: 2026-11-15
