> ## Documentation Index
> Fetch the complete documentation index at: https://doc.playsmart.api.dolly.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/games — Fetch game catalog and configuration

> Fetch the list of active games and their configuration from PlaySmart. Supports filtering by bundle ID to retrieve a single game's settings.

Call this endpoint at the start of a game session to get the current configuration for the games your player can access. The response includes ad settings, reward configuration, version requirements, and maintenance status for each active game. Use the optional `bundle_id` parameter to retrieve settings for your specific game without loading the full catalog.

## Endpoint

```text theme={null}
GET /v1/games
```

No authentication is required.

## Query parameters

<ParamField query="bundle_id" type="string">
  Filter the response to a single game by its Android package name or iOS bundle identifier (e.g. `com.example.mygame`). When omitted, all active games are returned.
</ParamField>

## Example requests

Without filtering — returns all active games:

```bash theme={null}
curl https://playsmart-gateway-1w8ko864.uc.gateway.dev/v1/games
```

With `bundle_id` — returns only the matching game:

```bash theme={null}
curl "https://playsmart-gateway-1w8ko864.uc.gateway.dev/v1/games?bundle_id=com.example.mygame"
```

## Response

### 200 OK

The response `data` field is an array of game objects.

<ResponseField name="game_id" type="number">
  A stable numeric identifier derived from the game's database ID. Safe to use as a local key across sessions.
</ResponseField>

<ResponseField name="name" type="string">
  The game's display name.
</ResponseField>

<ResponseField name="bundle_id" type="string">
  The Android package name or iOS bundle identifier (e.g. `com.example.mygame`).
</ResponseField>

<ResponseField name="play_store_url" type="string">
  The Google Play Store URL for the game.
</ResponseField>

<ResponseField name="thumbnail_url" type="string | null">
  URL for the game's artwork image. `null` if no thumbnail has been configured.
</ResponseField>

<ResponseField name="game_mode" type="string">
  The game's play mode. One of: `level_based`, `endless`, `hybrid`.
</ResponseField>

<ResponseField name="coins_enabled" type="boolean">
  Whether coin rewards are active for this game. When `false`, do not award or display coin rewards regardless of game events.
</ResponseField>

<ResponseField name="ads_enabled" type="boolean">
  Whether ads are enabled for this game. Check this alongside the global `ads_enabled` flag from `/v1/app-settings`.
</ResponseField>

<ResponseField name="ios_store_id" type="string">
  The iOS App Store identifier for this game.
</ResponseField>

<ResponseField name="version" type="string">
  The current version string for this game (e.g. `"1.4.2"`).
</ResponseField>

<ResponseField name="maintenance" type="boolean">
  If `true`, this game is unavailable. Show a maintenance UI and prevent the player from starting a session. This is `true` when either the game itself or the global app is in maintenance mode.
</ResponseField>

<ResponseField name="min_version_code" type="number">
  The minimum supported version code for this game. Prompt the player to update if their installed version code is below this value.
</ResponseField>

<ResponseField name="post_game_interstitial_every_n_games" type="number">
  Show a post-game interstitial ad after every N completed games for this specific game. Overrides the global setting from `/v1/app-settings`.
</ResponseField>

```json theme={null}
{
  "data": [
    {
      "game_id": 1738291045,
      "name": "Stack Blaster",
      "bundle_id": "com.example.stackblaster",
      "play_store_url": "https://play.google.com/store/apps/details?id=com.example.stackblaster",
      "thumbnail_url": "https://cdn.playsmart.io/thumbnails/stackblaster.png",
      "game_mode": "level_based",
      "coins_enabled": true,
      "ads_enabled": true,
      "ios_store_id": "com.example.stackblaster.ios",
      "version": "1.4.2",
      "maintenance": false,
      "min_version_code": 142,
      "post_game_interstitial_every_n_games": 3
    }
  ]
}
```