tupicGames
Step In
DEVELOPERS

API Reference

The tupic Game REST API lets you create games, manage assets, embed builds, and read leaderboards programmatically.

Base URL
https://games.tupic.com
Authentication
Routes that need auth read the token from the x-auth-token header (or the equivalent Authorization: Bearer header). Tokens come from the browser SSO flow via Keycloak and expire according to the IAM session.
Rate limits
All endpoints are rate-limited per user and per IP. Score submissions and asset generation jobs have stricter limits. Exceeding limits returns 429 Too Many Requests.
Errors
Errors are returned as JSON with an error field. Common status codes: 400 invalid request, 401 unauthenticated, 403 forbidden, 404 not found.

Authentication

Browser sign-in is handled by the web app with Tupic SSO (Keycloak) through NextAuth. The backend API does not expose public /auth/sso/* or /api/v1/auth/* routes; it only validates the Keycloak access token that the app sends on protected requests.

Discovery

Public endpoints for browsing games. No auth required.

GET
/api/v1/explore
List public games available to the community. Supports basic filtering by genre and recency.
GET
/api/v1/games/{game_id}/detail
Get the public detail page payload for a single game (title, genre, thumbnail, scores summary).
GET
/api/v1/games/{game_id}/play
Serve the playable HTML for a game. Public games work without auth; private games require a token.
GET
/play/{share_token}
Public-share endpoint. Lands on the game using a share token (no auth needed even for private games).

Games (CRUD)

Operations on games you own. All routes require auth.

GET
/api/v1/games
List games owned by the current organization.
auth: x-auth-token
POST
/api/v1/games
Create a new game record. The body specifies title and genre; logic generation happens via /generate.
auth: x-auth-token
GET
/api/v1/games/{game_id}
Fetch a single game record (status, metadata, asset slots).
auth: x-auth-token
PUT
/api/v1/games/{game_id}
Update game metadata such as title, description, or visibility.
auth: x-auth-token
DELETE
/api/v1/games/{game_id}
Delete a game and its associated builds.
auth: x-auth-token
POST
/api/v1/games/{game_id}/clone
Create a copy of an existing game as a new draft you can edit.
auth: x-auth-token
POST
/api/v1/games/{game_id}/share
Generate or rotate a public share token for the game.
auth: x-auth-token
POST
/api/v1/games/{game_id}/publish
Submit the game for review and public publishing.
auth: x-auth-token

Generation Engine

Endpoints that drive AI generation of game logic and assets.

GET
/api/v1/engine/genres
List supported genres (Platformer, Runner, Shooter, Puzzle, Quiz, ...). Each genre exposes its own questions and asset slots.
GET
/api/v1/engine/genres/{genre}/questions
Get the prompt questions specific to a genre (theme, mood, difficulty curve).
GET
/api/v1/engine/genres/{genre}/assets
List the asset slots a genre expects (player sprite, background, enemy, ...).
POST
/api/v1/engine/spec
Build a structured game spec from user answers. Returns a JSON spec used by /create-game.
auth: x-auth-token
POST
/api/v1/engine/create-game
Create a game from a spec. Triggers logic generation (Claude) and queues asset jobs.
auth: x-auth-token
POST
/api/v1/games/{game_id}/generate
Re-run logic generation for an existing game (e.g. after editing the spec).
auth: x-auth-token
POST
/api/v1/engine/assets/generate
Queue an asset generation job (Gemini / Imagen). Returns a job ID for polling.
auth: x-auth-token
GET
/api/v1/engine/assets/status/{job_id}
Poll the status of an asset generation job.
auth: x-auth-token

Embed & Sharing

Drop a game into your own site or share it on social channels.

GET
/api/v1/games/{game_id}/embed
Serve the game in embed mode -- minimal UI, no SDK toolbar. Suitable for iframe embedding.
GET
/api/v1/games/{game_id}/embed-code
Return ready-to-paste embed snippets: iframe HTML, share URL, and links for Telegram / WhatsApp / X / Facebook.

Scores & Leaderboards

Submit scores and read leaderboards. Score submissions are rate-limited and validated server-side.

POST
/api/v1/games/{game_id}/scores
Submit a score. The body includes score, time, and optional metadata. Auth is optional for public games.
auth: optional
GET
/api/v1/games/{game_id}/scores
List recent score submissions for a game.
GET
/api/v1/games/{game_id}/leaderboard
Lifetime leaderboard for a game.
GET
/api/v1/games/{game_id}/daily-board
Daily leaderboard reset every 24 hours.
GET
/api/v1/games/{game_id}/my-scores
List the authenticated user's scores on a game.
auth: x-auth-token

Tournaments

Create and join time-bound competitions on top of any game.

POST
/api/v1/tournaments
Create a tournament with start/end times, optional prize pool, and player limit.
auth: x-auth-token
GET
/api/v1/tournaments/{tournament_id}
Fetch a tournament (rules, leaderboard, status).
POST
/api/v1/tournaments/{tournament_id}/join
Join an open tournament.
auth: x-auth-token
GET
/api/v1/games/{game_id}/tournaments
List tournaments associated with a game.

Sessions

Track gameplay sessions for analytics. Session data is aggregated and never includes personally identifying information beyond a user ID.

POST
/api/v1/games/{game_id}/session
Track a play session: start, end, duration, and optional outcome. Works without auth for guest plays.
POST
/api/v1/games/{game_id}/like
Like a game. One like per user per game.
auth: x-auth-token

Export

Export your game outside tupic Game. Available on Professional and Enterprise plans.

GET
/api/v1/games/{game_id}/export/unity
Download a Unity-compatible project zip with assets, configuration, and C# scripts.
auth: x-auth-token