Get Games

Fetch the available games to add them to your catalogue. We recommend fetching games at least once a day.

Rather than listing individual marble tracks, some operators prefer displaying a single game entry in their catalogue. To accommodate this, we also provide a game item for our lobby, giving you complete flexibility in how you present our games.

The lobby entry is production-only

The lobby item is returned by this endpoint in production. It is not part of the staging catalogue — on staging, launch the lobby by passing the lobby code to Get Game URL directly. That code is the same in both environments and works in both.

Authentication

This endpoint is authenticated by IP whitelist — your server's outbound IP must match the address registered during onboarding. See Security for details. The X-Marbles-Signature header is not required and is ignored if sent.

Endpoint

POST /game/games

Request

POST /game/games HTTP/1.1
Host: api.marbles.xyz
Content-Type: application/json

{
  "operatorId": "abc123"
}

Parameters

Parameter	Type	Required	Description
`operatorId`	string	Yes	Your unique operator identifier provided by 155.io

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
    "type": "Game",
    "name": "Marble Plinko - Classic",
    "enabled": true,
    "assets": [
      {
        "type": "background",
        "extension": "webp",
        "url": "https://example.com/marble-plinko_background.webp"
      },
      {
        "type": "thumbnail",
        "extension": "webp",
        "url": "https://example.com/marble-plinko_poster.webp"
      }
    ],
    "blockedCountries": ["AU", "AE", "GB", "US"],
    "items": [
      "1ee9cb9d-e560-4e16-aafb-1d1d5a8db32c",
      "5d3b585e-4980-47e3-827d-b3cbfcdc929c"
    ],
    "allowedBetTypes": ["PickWinner", "StraightForecast", "ReverseForecast"],
    "createdAt": "2024-12-13T04:39:03.306865Z",
    "updatedAt": "2025-01-29T13:52:47.42136175Z"
  }
]

Response Fields

Field	Type	Description
`id`	string	Unique game identifier (UUID). Use this when launching games.
`type`	string	Always `"Game"`
`name`	string	Display name of the game
`enabled`	boolean	Whether the game is currently available. Only show games where `enabled: true`.
`assets`	array	Game assets for your catalogue (see below)
`blockedCountries`	array	ISO 3166-1 alpha-2 country codes where the game is blocked
`items`	array	UUIDs of selectable options in this game (see below)
`allowedBetTypes`	array	Bet types available for this game (see Bet Types)
`createdAt`	string	ISO 8601 timestamp when the game was created
`updatedAt`	string	ISO 8601 timestamp when the game was last modified

Retired IDs are disabled (enabled: false) — see Retired game IDs.

Assets

Each game includes assets for displaying in your game catalogue:

Asset Type	Description
`background`	Full-size background image for game detail pages
`thumbnail`	Square thumbnail image for game listings

{
  "type": "thumbnail",
  "extension": "webp",
  "url": "https://example.com/marble-plinko_poster.webp"
}

Items (Betting Options)

The items array contains UUIDs of the selectable options available in the game. Depending on the game type, these could be:

Marbles - Individual marble participants in a race
Ducks - Duck racers in duck racing games
Outcomes - Options like heads/tails in coin flip games

Players select which items they want to bet on. Different bet types allow picking a single winner, multiple items for forecast bets, or other combinations depending on the game configuration.

Error Responses

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid operator id",
  "details": "OperatorConfig with ID your-operator-id not found"
}

Error Statuses

Error	HTTP Code	Description
Invalid operator id	400	No operator exists for the provided `operatorId`
Validation error	400	Missing or invalid request fields (e.g. `Property 'OperatorID' is required`)
Bad request	400	Malformed JSON body

A 403 error page means your IP, not your payload

Requests from an IP that is not on your registered whitelist are blocked at our edge with an HTML 403 error page — they never reach the API and never produce a JSON error. If you see a 403, check your server's egress IP against the addresses you registered, before debugging the request itself.

On this page