> ## Documentation Index
> Fetch the complete documentation index at: https://docs.8bitedge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Games API — catalog metadata and pricing endpoints

> Retrieve retro game titles, slugs, and pricing data. Supports lookups by ID, slug, title, and console. Requires games.read scope.

The Games API provides read-only access to the 8bitedge retro game catalog. Every game title includes its display name, URL slug, console association, and market pricing across three conditions — loose, complete in box (CIB), and sealed new. You must have the `games.read` scope on your API key to call any of these endpoints.

## Base path

```
/api/v1/games
```

## Scope required

`games.read`

***

## The game object

Every endpoint that returns full game records uses the following shape:

| Field            | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `id`             | int    | Unique identifier                     |
| `game_name`      | string | Display name                          |
| `game_slug`      | string | URL-friendly slug                     |
| `console_id`     | int    | ID of the associated console          |
| `price_loose`    | string | Market price — cartridge or disc only |
| `price_complete` | string | Market price — complete in box (CIB)  |
| `price_new`      | string | Market price — sealed/new             |

**Example**

```json theme={null}
{
  "id": 123,
  "game_name": "Chrono Trigger",
  "game_slug": "chrono-trigger",
  "console_id": 19,
  "price_loose": "40.00",
  "price_complete": "95.50",
  "price_new": "300.00"
}
```

***

## GET /api/v1/games/titles

Returns a paginated list of game display titles with their IDs. Use this endpoint to build a searchable title index or to populate a dropdown. Results are ordered alphabetically by name.

### Query parameters

<ParamField query="limit" type="int">
  Number of results per page. Defaults to `25`. Capped by your plan's `max_page_size` — read `meta.pagination.per_page` in the response to confirm the effective value.
</ParamField>

<ParamField query="page" type="int">
  Page number when using page-mode pagination. Defaults to `1`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor token for cursor-mode pagination. Pass the value from `meta.pagination.next_cursor` in the previous response.
</ParamField>

<ParamField query="paginate" type="string">
  Pagination mode. Defaults to `page`. Set to `cursor` to switch to cursor-based pagination, which is more efficient for large or frequently-changing result sets.
</ParamField>

### Request

```bash theme={null}
curl "https://api.8bitedge.com/api/v1/games/titles" \
  -H "Authorization: Bearer $BITEDGE_API_KEY"
```

### Response 200

Each item in `data` contains an `id` and `display_game_name` (the game's display title). The `meta` and `links` objects follow the standard pagination envelope.

```json theme={null}
{
  "data": [
    { "id": 12, "display_game_name": "Aladdin" },
    { "id": 47, "display_game_name": "Battletoads" }
  ],
  "meta": {
    "pagination": { "mode": "page", "page": 1, "per_page": 25, "total": 842, "last_page": 34 }
  },
  "links": {
    "next": "https://api.8bitedge.com/api/v1/games/titles?page=2",
    "prev": null
  }
}
```

***

## GET /api/v1/games/slugs

Returns a paginated list of game URL slugs with their IDs. Use this when you need the machine-readable `game_slug` values — for example, to construct lookup URLs or to compare against an existing slug index. Results are ordered alphabetically by slug.

### Query parameters

<ParamField query="limit" type="int">
  Number of results per page. Defaults to `25`. Capped by your plan's `max_page_size`.
</ParamField>

<ParamField query="page" type="int">
  Page number for page-mode pagination. Defaults to `1`.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor token for cursor-mode pagination.
</ParamField>

<ParamField query="paginate" type="string">
  Pagination mode — `page` (default) or `cursor`.
</ParamField>

### Request

```bash theme={null}
curl "https://api.8bitedge.com/api/v1/games/slugs" \
  -H "Authorization: Bearer $BITEDGE_API_KEY"
```

### Response 200

Each item in `data` contains an `id` and `ebay_game_name` (the game's URL slug).

```json theme={null}
{
  "data": [
    { "id": 12, "ebay_game_name": "aladdin" },
    { "id": 47, "ebay_game_name": "battletoads" }
  ],
  "meta": {
    "pagination": { "mode": "page", "page": 1, "per_page": 25, "total": 842, "last_page": 34 }
  },
  "links": {
    "next": "https://api.8bitedge.com/api/v1/games/slugs?page=2",
    "prev": null
  }
}
```

***

## GET /api/v1/games/game/\{id}

Retrieves a single game by its numeric ID. This is the fastest way to fetch a specific title when you already have the ID — it returns the full game object directly under `data`, not wrapped in an array.

### Path parameters

<ParamField path="id" type="int" required>
  The numeric ID of the game to retrieve.
</ParamField>

### Request

```bash theme={null}
curl "https://api.8bitedge.com/api/v1/games/game/123" \
  -H "Authorization: Bearer $BITEDGE_API_KEY"
```

### Response 200

```json theme={null}
{
  "data": {
    "id": 123,
    "game_name": "Chrono Trigger",
    "game_slug": "chrono-trigger",
    "console_id": 19,
    "price_loose": "40.00",
    "price_complete": "95.50",
    "price_new": "300.00"
  }
}
```

### Error responses

| Status | `error.code` | When it occurs                              |
| ------ | ------------ | ------------------------------------------- |
| `404`  | `not_found`  | No game with that ID exists in the catalog. |

***

## GET /api/v1/games/slug/\{slug}

Finds all games whose slug matches the provided value. Because the same slug can be shared by the same title across different consoles (e.g., a game released on both the SNES and Game Boy), this endpoint always returns an array — never a single object.

### Path parameters

<ParamField path="slug" type="string" required>
  The URL slug to look up. URL-encode any characters that are not URL-safe (e.g., spaces become `%20`). Slugs are typically lowercase and hyphen-separated.
</ParamField>

### Request

```bash theme={null}
curl "https://api.8bitedge.com/api/v1/games/slug/chrono-trigger" \
  -H "Authorization: Bearer $BITEDGE_API_KEY"
```

### Response 200

`data` is always an array. When there are no matches, `data` is an empty array and `meta.count` is `0` — this is **not** a `404`.

```json theme={null}
{
  "data": [
    {
      "id": 123,
      "game_name": "Chrono Trigger",
      "game_slug": "chrono-trigger",
      "console_id": 19,
      "price_loose": "40.00",
      "price_complete": "95.50",
      "price_new": "300.00"
    }
  ],
  "meta": { "count": 1 }
}
```

***

## GET /api/v1/games/title/\{title}

Finds all games whose display title matches the provided value. The matching and response shape are identical to the slug lookup — you get an array of full game objects and a `meta.count`, even if only one title matches.

### Path parameters

<ParamField path="title" type="string" required>
  The display title to look up. URL-encode spaces and special characters — for example, `Super Mario Bros.` becomes `Super%20Mario%20Bros.`
</ParamField>

### Request

```bash theme={null}
curl "https://api.8bitedge.com/api/v1/games/title/Super%20Mario%20Bros." \
  -H "Authorization: Bearer $BITEDGE_API_KEY"
```

### Response 200

```json theme={null}
{
  "data": [
    {
      "id": 88,
      "game_name": "Super Mario Bros.",
      "game_slug": "super-mario-bros",
      "console_id": 7,
      "price_loose": "12.00",
      "price_complete": "35.00",
      "price_new": "180.00"
    }
  ],
  "meta": { "count": 1 }
}
```

***

## GET /api/v1/games/console/\{console\_id}

Returns a paginated list of full game objects for a specific console, ordered by name. Use this endpoint to browse or cache the complete game library for a platform. To find valid `console_id` values, call the [Consoles API](/api/consoles).

### Path parameters

<ParamField path="console_id" type="int" required>
  The numeric ID of the console whose games you want to list.
</ParamField>

### Query parameters

<ParamField query="limit" type="int">
  Number of results per page. Defaults to `25`. Capped by your plan's `max_page_size`.
</ParamField>

<ParamField query="page" type="int">
  Page number for page-mode pagination. Defaults to `1`.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor token for cursor-mode pagination.
</ParamField>

<ParamField query="paginate" type="string">
  Pagination mode — `page` (default) or `cursor`.
</ParamField>

### Request

```bash theme={null}
curl "https://api.8bitedge.com/api/v1/games/console/19?limit=50" \
  -H "Authorization: Bearer $BITEDGE_API_KEY"
```

### Response 200

```json theme={null}
{
  "data": [
    {
      "id": 123,
      "game_name": "Chrono Trigger",
      "game_slug": "chrono-trigger",
      "console_id": 19,
      "price_loose": "40.00",
      "price_complete": "95.50",
      "price_new": "300.00"
    }
  ],
  "meta": {
    "pagination": { "mode": "page", "page": 1, "per_page": 50, "total": 714, "last_page": 15 }
  },
  "links": {
    "next": "https://api.8bitedge.com/api/v1/games/console/19?limit=50&page=2",
    "prev": null
  }
}
```

<Note>
  An unrecognized `console_id` yields an empty `data` array with `total: 0` — it does **not** return a `404`. If you're getting an empty response, verify the ID against `GET /api/v1/consoles`.
</Note>

***

## Notes

<Note>
  Slug and title lookups (`/slug/{slug}` and `/title/{title}`) always return an array, even when only one game matches. This is intentional — the same title can exist across multiple consoles, and the response shape is consistent regardless of how many matches are found.
</Note>

<Tip>
  See the [Catalog Lookups guide](/guides/catalog-lookups) for recommended patterns, including how to combine title lookups with console filtering and how to efficiently paginate large console libraries.
</Tip>