Sessions

Start a new game session. Sessions group all events, uploads, and reports that happen during a single play session. Call this endpoint once when the game launches and reuse the returned sessionId for all subsequent requests.

Endpoint

POST /v1/ingest/sessions

Request body

Field	Type	Required	Description
`build`	object	Yes	Build information
`build.version`	string	Yes	Semantic version, e.g. `"1.14.2"`
`build.platform`	string	Yes	Platform identifier, e.g. `"windows"`, `"linux"`, `"macos"`, `"android"`
`build.gitCommit`	string	No	Git commit hash, e.g. `"a1b2c3d4"`
`build.channel`	string	No	Build channel: `dev`, `qa`, `alpha`, `beta`, `staging`, `prod`
`player`	object	No	Player information
`player.externalId`	string	No	External player ID, e.g. `"steam_76561198000000000"`
`player.deviceId`	string	No	Device identifier, e.g. `"device-7f2e4a8c"`
`metadata`	object	No	Arbitrary key-value metadata

Response

Field	Type	Description
`sessionId`	string (UUID)	Unique session identifier
`buildId`	string (UUID)	Build record identifier
`startedAt`	string (ISO 8601)	Session start timestamp

Examples

cURL

curl -X POST \
  -H "Authorization: Bearer flg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "build": {
      "version": "1.14.2",
      "platform": "windows",
      "gitCommit": "a1b2c3d4",
      "channel": "dev"
    },
    "player": {
      "externalId": "steam_76561198000000000"
    },
    "metadata": {
      "difficulty": "hard",
      "region": "eu-west"
    }
  }' \
  https://ingest.forgelogger.dev/v1/ingest/sessions

Response

{
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "buildId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "startedAt": "2026-04-08T14:30:00.000Z"
}

Node.js

const res = await fetch('https://ingest.forgelogger.dev/v1/ingest/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    build: { version: '1.14.2', platform: 'windows' },
    player: { externalId: 'player-42' },
  }),
});
const { sessionId, buildId } = await res.json();

C#

var payload = new {
    build = new { version = "1.14.2", platform = "windows" },
    player = new { externalId = "player-42" },
};
 
var content = new StringContent(
    JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
 
var response = await httpClient.PostAsync(
    "https://ingest.forgelogger.dev/v1/ingest/sessions", content);
 
var body = await response.Content.ReadAsStringAsync();

Godot GDScript

var body := {
    "build": {
        "version": "1.14.2",
        "platform": OS.get_name().to_lower(),
        "gitCommit": "a1b2c3d4"
    },
    "player": { "externalId": "player-42" }
}
var headers := [
    "Content-Type: application/json",
    "Authorization: Bearer %s" % api_key
]
http.request(base_url + "/v1/ingest/sessions", headers,
    HTTPClient.METHOD_POST, JSON.stringify(body))

Notes

This endpoint is not idempotent. Each call creates a new session. Cache the sessionId and reuse it for the duration of the play session.
The buildId is created or reused based on the combination of version, platform, and gitCommit. If a matching build already exists, the existing ID is returned.
The channel field is optional but recommended — it allows filtering reports by build channel in the dashboard.