Ingest API Reference

The Ingest API is the data collection interface used by game engine plugins and custom integrations to send sessions, events, uploads, and bug reports to Forge Logger.

Base URL

https://ingest.forgelogger.dev

All paths below are relative to this base URL.

Authentication

Every request must include a Logger Token in the Authorization header:

Authorization: Bearer flg_your_token_here

Tokens are scoped to a specific project and environment. Create them in the dashboard under Settings or via the management API.

Endpoints

Method	Endpoint	Description
`POST`	`/v1/ingest/sessions`	Start a new game session
`POST`	`/v1/ingest/events`	Submit telemetry events (single or batch)
`POST`	`/v1/ingest/uploads`	Create a pre-signed upload URL
`POST`	`/v1/ingest/reports`	Submit a bug report
`GET`	`/health`	Health check

Typical flow

Start a session — call /sessions when the game launches. Cache the returned sessionId.
Send events — stream telemetry events to /events during gameplay.
Upload files — when a bug report needs attachments, create upload targets via /uploads, then PUT the binary to the pre-signed URL.
Submit a report — send the bug report to /reports referencing the session, events, and uploads.

Enums

These enum values are shared across all ingest endpoints:

Enum	Values
Severity	`low`, `medium`, `high`, `critical`
Reporter type	`player`, `tester`, `qa`, `internal`, `system`
Attachment type	`screenshot`, `video`, `save_state`, `log_bundle`, `other`
Build channel	`dev`, `qa`, `alpha`, `beta`, `staging`, `prod`
Export provider	`github`, `gitlab`, `jira`, `discord`, `webhook`

Error handling

The API returns standard HTTP status codes:

Code	Meaning
`201`	Resource created successfully
`400`	Validation error — check the response body for details
`401`	Missing or invalid token
`403`	Token does not have access to this project/environment
`429`	Rate limited — implement exponential back-off
`500`	Server error — retry with back-off

Notes

Idempotency — POST /reports supports an optional clientRequestId (UUID) for idempotent submissions.
Batch events — POST /events accepts a single object or an array of up to 200 events.
Token prefix — all logger tokens start with flg_. Dashboard JWT tokens are not accepted.