HTTP API and transport
Understand the browser transport without moving credentials into a game.
Browser transport
The public SDK is the supported path for hosted games. The parent internally creates POST /api/v1/games/:slug/sessions and sends POST /api/v1/play/events with X-Play-Token. Do not duplicate that flow inside the iframe: it would bypass the launcher's session ownership and its event/reward UX. POST /api/v1/play/events takes eventId, name, data and optional protocolVersion:2 plus sequence. Successful results include accepted:true; new events also return duplicate:false, rewardsPending and the current status string. Errors carry a message, and the parent converts them into rejected acknowledgement callbacks. No SDK method returns the parent's play token.
Public read-only contract endpoint
GET /api/v1/developer/events/:slug is the documentation inspector's read-only endpoint. It returns the published game's title/slug/active release and published event names, descriptions, fields and minimum intervals for that release. It excludes draft/paused definitions, internal reward rules and credentials. An unpublished or unknown game returns 404.
// From your developer tooling, not needed inside the game's sandbox:
const response = await fetch('/api/v1/developer/events/island-hopper');
if (!response.ok) throw new Error('Published contract unavailable');
const contract = await response.json();Versioning and retry behavior
The SDK emits version 2 messages and protocolVersion:2 reports. The legacy envelope without protocolVersion is still accepted by the server, but new browser examples should use the injected V2 SDK. Accepted event IDs are idempotent only with matching payload/session. Do not generate a different ID to retry a valuable action or mix your own sequence counter with the SDK.
Server integrations
POST /api/v1/integrations/game-events is separate, signed and staff-provisioned. It requires an existing session scoped to the key's game. See the server reference before using it. There is no public key self-provisioning or general SDK authentication endpoint.