> ## 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.

# Consoles API — retro platform reference data

> List and retrieve retro game consoles by ID. Requires consoles.read scope. Used to resolve console IDs for game and demand endpoints.

The Consoles API returns a catalog of all retro game platforms supported by 8bitedge. Use it to build console pickers for your UI, resolve human-readable platform names from numeric IDs, or determine which `console_id` values to pass when filtering game or demand queries by platform. You must have the `consoles.read` scope on your API key to call these endpoints.

## Scope required

`consoles.read`

## The console object

Every console endpoint returns records in the following shape:

```json theme={null}
{ "id": 19, "console_name": "Nintendo SNES" }
```

| Field          | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| `id`           | int    | Unique numeric identifier for the platform |
| `console_name` | string | Human-readable platform name               |

***

## GET /api/v1/consoles

Returns a paginated list of all supported consoles, ordered alphabetically by name. Use this endpoint to populate a platform picker or to build a local ID-to-name mapping.

### Query parameters

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

<ParamField query="page" type="int">
  Page number for 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` returned in the previous response.
</ParamField>

<ParamField query="paginate" type="string">
  Pagination mode. Defaults to `page`. Set to `cursor` for more efficient traversal of large result sets.
</ParamField>

### Request

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

### Response 200

```json theme={null}
{
  "data": [
    { "id": 3, "console_name": "Nintendo 64" },
    { "id": 7, "console_name": "Nintendo SNES" }
  ],
  "meta": {
    "pagination": {
      "mode": "page",
      "page": 1,
      "per_page": 25,
      "total": 30,
      "last_page": 2
    }
  },
  "links": {
    "next": null,
    "prev": null
  }
}
```

***

## GET /api/v1/consoles/\{id}

Retrieves a single console by its numeric ID. This is the fastest way to resolve a console name from an ID you already have — for example, to display a platform label alongside a game record.

### Path parameters

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

### Request

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

### Response 200

```json theme={null}
{
  "data": { "id": 19, "console_name": "Nintendo SNES" }
}
```

### Error responses

| Status | `error.code` | When it occurs                  |
| ------ | ------------ | ------------------------------- |
| `404`  | `not_found`  | No console with that ID exists. |

***

## Using console IDs

Console IDs are the connective tissue between the Consoles API and the rest of the 8bitedge platform. You'll encounter them in two places:

* **Games API** — as the `console_id` path parameter in `GET /api/v1/games/console/{console_id}` to retrieve all games for a platform.
* **Demand API** — as the `?console_id=` query parameter on demand endpoints such as `GET /api/v1/demand-intent/games` to narrow the leaderboard to a single platform.

**Example workflow — filter the demand leaderboard by console:**

**Step 1.** List all consoles to find the ID for the platform you care about.

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

```json theme={null}
{
  "data": [
    { "id": 3,  "console_name": "Nintendo 64" },
    { "id": 19, "console_name": "Nintendo SNES" }
  ],
  "meta": {
    "pagination": { "mode": "page", "page": 1, "per_page": 25, "total": 30, "last_page": 2 }
  },
  "links": { "next": null, "prev": null }
}
```

**Step 2.** Pick the ID for your target platform — `19` for Nintendo SNES in this example.

**Step 3.** Pass that ID as a filter to the demand leaderboard.

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

<Tip>
  If you're building a product that needs to display platform names alongside game records, fetch and cache the full console list at startup — the catalog changes infrequently and the total number of platforms easily fits in memory. Refresh your cache periodically to pick up any newly enabled platforms.
</Tip>