01 · Foundations
Understand the current API model
OpenGame uses JSON application routes for account data and generation orchestration, plus direct responses for playable previews and artifact downloads.
Session authentication
The web routes documented here use the signed-in OpenGame browser session unless an endpoint explicitly states another scheme.
JSON envelopes
Successful JSON routes generally return code, message, and data. Errors include an HTTP status and a stable error code where available.
Asynchronous runs
Generation and Studio creation return HTTP 202 because work may continue after the initial request is accepted.
02 · Retired endpoint
Migrate generator calls to Studio
The legacy homepage creation endpoint is retired. It never creates a task or contacts the generation runtime; use the paid Studio endpoint for new work.
/api/generator/runsRetired. Signed-in requests return HTTP 402 with error code studio_credits_required and no task is created.
/api/generator/runs/:idRead one historical generator run owned by the current user. This read-only route remains available for old records.
/api/creditsRead spendable Studio balance, historical ledger totals, retired Free Generator balance, and recent credit history for the signed-in account.
const response = await fetch("/api/generator/runs", {
method: "POST",
credentials: "include",
headers: { "content-type": "application/json" },
body: JSON.stringify({
prompt: "Build a short neon arcade game with fast retries."
})
});
const payload = await response.json();
// HTTP 402: payload.error.code === "studio_credits_required"
// Create paid runs through POST /api/studio/runs instead.03 · Studio
Work with Studio runs
Studio exposes persistent run history and a focused creation payload for output mode, thread continuity, and asset behavior. Provider and model routing are managed by the server.
/api/studio/runs?limit=10List the current user’s most recent Studio runs. Limit is clamped between 1 and 20.
/api/studio/runsCreate and begin processing a Studio run. Supports quick HTML or game bundle modes plus optional thread, parent run, intent, artifact context, and asset mode fields. Provider and model selection are server-managed.
/api/studio/runs/:idRead a single Studio run and its serialized artifact state for the signed-in owner.
POST /api/studio/runs
Content-Type: application/json
{
"prompt": "Build a one-level browser platformer.",
"mode": "game_bundle",
"intent": "auto",
"assetMode": "auto"
}Quick HTML
Use quick_html for a focused, single-file playable result when speed and portability matter most.
Game bundle
Use game_bundle for advanced multi-file browser games with a manifest, assets, and a dedicated entry document.
04 · Delivery
Preview, download, and publish artifacts
Completed runs can expose an isolated preview, a downloadable artifact, and an optional public game publication.
/api/game-artifacts/:id/previewReturn the playable artifact preview. Access is resolved from the current session or a valid preview token.
/api/game-artifacts/:id/downloadDownload an artifact owned by the signed-in user. The response is the artifact file or bundle rather than a JSON envelope.
/api/game-publications/:artifactIdRead the current public publication record for an artifact owned by the signed-in user.
/api/game-publications/:artifactIdPublish an eligible HTML artifact with a title, description, optional controls, and optional structured SEO content.
/api/game-publications/:artifactIdUnpublish the signed-in owner’s public game while keeping the underlying generated artifact.
POST /api/game-publications/:artifactId
Content-Type: application/json
{
"title": "Neon Dash",
"description": "A fast one-button arcade challenge.",
"controls": ["Space — dash", "R — restart"]
}05 · Reliability
Handle expected failure states
Use the HTTP status for control flow and the response code for a stable application-level reason whenever it is present.
Sign in again before retrying the request.
Paid Studio Credits are required, or a retired free-generation endpoint was called.
The run or artifact does not exist for the current owner.
A public game URL could not be allocated.
The submitted payload failed validation.
The generation queue is temporarily unavailable.