Start a game session

POST /v1/me/sessions

• Operation ID: createGameSession
• Tags: Game sessions
• Base URL: http://localhost:8787

Starts a cloud-gaming session for the caller. The plan tier is the ceiling for resolved stream settings. An open link reuses the runtime idempotency key; failed or ended links return idempotency_key_used. Returned stream values are resolved locally: the current adapter does not forward yuv444 or audioChannels, and actual support depends on the streaming backend.

Workflow: Integration guide.

Authentication: Platform user Bearer JWT. Acts only on the caller's own data.

Idempotency: Send a fresh 8-128 character key per user action; retries of the same action reuse it.

Authentication

• Auth: Platform user Bearer JWT (Authorization: Bearer <access_token>).

Parameters

Name	In	Type	Required	Description
idempotency-key	header	string	yes	Min length: 8. Max length: 128

Request body

Required: yes.

Content type: application/json

Schema: object

Field	Type	Required	Description
appSlug	string	yes	Min length: 1. Max length: 100. Pattern: ^[a-z0-9][a-z0-9_-]*$
runtimeAppId	string	no	Min length: 1. Max length: 200
create_lobby	boolean	no	Default: false
preferences	object	no	-
preferences.width	integer	no	Min: 320. Max: 7680
preferences.height	integer	no	Min: 240. Max: 4320
preferences.fps	integer	no	Min: 1. Max: 360
preferences.bitrateKbps	integer	no	Min: 1000. Max: 150000
preferences.hdr	boolean	no	-
preferences.yuv444	boolean	no	-
preferences.audioChannels	integer	no	Min: 1. Max: 8

Example

{
  "appSlug": "example-game",
  "create_lobby": false,
  "preferences": {
    "width": 1280,
    "height": 720,
    "fps": 30
  }
}

Responses

201

Session created; stream fields report locally resolved settings.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object

Field	Type	Required	Description
sessionId	string	yes	-
playUrl	string	yes	-
token	string	yes	-
display	object	yes	-
display.width	integer	yes	-
display.height	integer	yes	-
display.fps	integer	yes	-
display.hdr	boolean	no	-
stream	object	yes	-
stream.width	integer	yes	-
stream.height	integer	yes	-
stream.fps	integer	yes	-
stream.bitrateKbps	integer	yes	-
stream.hdr	boolean	yes	-
stream.yuv444	boolean	yes	-
stream.audioChannels	integer	yes	-

Example

{
  "sessionId": "sess_example",
  "playUrl": "https://play.example.com/s/sess_example",
  "token": "<MEMBER_TOKEN>",
  "display": {
    "width": 1920,
    "height": 1080,
    "fps": 60,
    "hdr": false
  },
  "stream": {
    "width": 1280,
    "height": 720,
    "fps": 30,
    "bitrateKbps": 3000,
    "hdr": false,
    "yuv444": false,
    "audioChannels": 2
  }
}

Errors

400

Request validation failed.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ValidationErrorBody)

Field	Type	Required	Description
success	boolean	yes	One of: false
error	object	yes	-
error.name	string	yes	One of: "ZodError"
error.issues	object[]	yes	-
error.issues[].code	string	yes	-
error.issues[].path	(string | number)[]	yes	-
error.issues[].message	string	yes	-

Request validation

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "custom",
        "path": [
          "field"
        ],
        "message": "Invalid value"
      }
    ]
  }
}

401

Missing, malformed, expired or wrong-audience Bearer token (missing_token, invalid_token, invalid_audience).

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody)

Field	Type	Required	Description
error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
details	any	no	Optional structured context. For 403 it is { perm }.

Error response

{
  "error": "missing_token"
}

402

insufficient_credits: the account has no credits.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "insufficient_credits"
}

403

forbidden (inactive account), banned, or plan_required.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "forbidden"
}

404

app_not_found: no enabled runtime app for the game or runtimeAppId.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "app_not_found"
}

409

concurrent_limit, idempotency_key_conflict or idempotency_key_used.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "concurrent_limit"
}

500

Unexpected server error (internal). No details are returned.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "internal"
}

503

unavailable: the runtime could not create the session; retry. Maintenance can refuse this write before authentication (degraded blocks session start and checkout; lockdown blocks other public/user writes).

• Header x-request-id: Request identifier; quote it when reporting an error.
• Header Retry-After: Maintenance retry delay in seconds; present for panic_mode. Example: 30. Content type: application/json

Schema: object (ErrorBody) | object (MaintenanceErrorBody)

Field	Type	Required	Description
(variant 1).error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
(variant 1).details	any	no	Optional structured context. For 403 it is { perm }.
(variant 2).error	string	yes	One of: "panic_mode"
(variant 2).level	string	yes	One of: "degraded", "lockdown"
(variant 2).reason	string | null	yes	-

Error response

{
  "error": "unavailable"
}

Dependency unavailable

{
  "error": "unavailable"
}

Maintenance lockdown

{
  "error": "panic_mode",
  "level": "lockdown",
  "reason": "Scheduled maintenance"
}

Examples

curl

curl -X POST 'http://localhost:8787/v1/me/sessions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'idempotency-key: 7d0f3c52-9a1e-4b6f-8c2d-5e4a3b2c1d0e' \
  -H 'Content-Type: application/json' \
  --data '{"appSlug":"example-game","create_lobby":false,"preferences":{"width":1280,"height":720,"fps":30}}'

TypeScript

const accessToken = process.env.ACCESS_TOKEN; // user JWT from your sign-in flow

const response = await fetch("http://localhost:8787/v1/me/sessions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "idempotency-key": "7d0f3c52-9a1e-4b6f-8c2d-5e4a3b2c1d0e",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "appSlug": "example-game",
    "create_lobby": false,
    "preferences": {
      "width": 1280,
      "height": 720,
      "fps": 30
    }
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = response.status === 204 || response.status === 205
  ? undefined
  : response.headers.get("content-type")?.includes("json")
    ? await response.json()
    : await response.text();