# Game Stats Snapshots

Versioned snapshots of game-balance stats. Pin your game to a specific dataset version (e.g., "2026.1") so stat rebalancing doesn't break your build mid-development. When you're ready to pick up new values, switch to a newer version on your own schedule.

Source: https://docs.gunspec.io/en/api/game-stats

## Get Game Stats (Live)

`GET /v1/firearms/{id}/game-stats`

Auth: API key required  
Tier: Builder+

Returns **live** game-balance stats (0-100 scale) for a single firearm. These track the current dataset and change when the catalog is rebalanced. Pin a snapshot version instead if you need stability across a development cycle.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Resource slug ID |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | FirearmGameStats | The response payload |
| `data.id` | string | URL-safe slug identifying the firearm, e.g. `glock-g17-gen5`. |
| `data.name` | string | Display name, as the maker writes it. |
| `data.gameDamage` | integer \| null | Editorial game statistic, 0-100. **Not a measured figure.** These are balance numbers for game use and are not derived from the ballistics above. |
| `data.gameAccuracy` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |
| `data.gameRange` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |
| `data.gameFireRate` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |
| `data.gameMobility` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |
| `data.gameRecoilControl` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |
| `data.gameReloadSpeed` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |
| `data.gameConcealment` | integer \| null | Editorial game statistic, 0-100. Not a measured figure. |

```json
{
  "success": true,
  "data": {
    "id": "glock-g17-gen5",
    "name": "Glock 17 Gen5",
    "gameDamage": 45,
    "gameAccuracy": 72,
    "gameRange": 35,
    "gameFireRate": 68,
    "gameMobility": 85,
    "gameRecoilControl": 70,
    "gameReloadSpeed": 75,
    "gameConcealment": 80
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 404 | `NOT_FOUND` | Resource not found |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Requires **Builder** tier or higher.
- All 8 stats are normalized 0-100, derived from real-world specs using weighted formulas.
- This returns **live** data. For frozen/stable stats, use the **versioned snapshots** at `/v1/game-stats/versions`.
- Perfect for FPS games, RPGs, tactical sims, and card games.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/firearms/glock-g17-gen5/game-stats' \
  --header 'X-API-Key: your_key'
```

## List Snapshot Versions

`GET /v1/game-stats/versions`

Auth: API key required  
Tier: Builder+

Returns every available game stats snapshot version, newest first. Pin your build to a version so a rebalance of the live catalog cannot change your numbers mid-development.

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | GameStatsVersion[] | The response payload. |
| `data[].id` | integer | Autoincrementing version id. |
| `data[].version` | string | Version label, e.g. `2025.1`. |
| `data[].description` | string \| null | Prose summary of the record, where one has been written. |
| `data[].firearmCount` | integer | How many firearms carried game statistics in this version. |
| `data[].createdAt` | string | When the record was first added, `YYYY-MM-DD HH:MM:SS` in UTC. |

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "version": "2025.1",
      "description": "Initial game stats snapshot",
      "firearmCount": 450,
      "createdAt": "2025-06-01 12:00:00"
    }
  ]
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Requires **Builder** tier or higher.
- Versions are sorted newest first.
- **Workflow:** 1) List versions, 2) Pick one to pin your game to, 3) Fetch stats via `/v1/game-stats/versions/{version}/firearms`, 4) When ready, switch to a newer version.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/game-stats/versions' \
  --header 'X-API-Key: your_key'
```

## List Firearms in Version

`GET /v1/game-stats/versions/{version}/firearms`

Auth: API key required  
Tier: Builder+

Returns paginated game stats for every firearm frozen into one snapshot version.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | string | yes | Snapshot version |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | Page number, from 1 to 10,000 |
| `per_page` | integer | no | Items per page (max 100) |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | GameStatsSnapshotEntry[] | One page of results |
| `data[].firearm_id` | string | Slug of the firearm this row is about. |
| `data[].firearm_name` | string | Display name at the time the snapshot was taken. |
| `data[].game_damage` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_accuracy` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_range` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_fire_rate` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_mobility` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_recoil_control` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_reload_speed` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data[].game_concealment` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `pagination.page` | number | Current page number |
| `pagination.per_page` | number | Items per page |
| `pagination.total` | number | Total matching records (Builder and above) |

```json
{
  "success": true,
  "data": [
    {
      "firearm_id": "glock-g17-gen5",
      "firearm_name": "Glock 17 Gen5",
      "game_damage": 42,
      "game_accuracy": 68,
      "game_range": 35,
      "game_fire_rate": 55,
      "game_mobility": 78,
      "game_recoil_control": 62,
      "game_reload_speed": 72,
      "game_concealment": 70
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "per_page": 20,
    "total": 42,
    "totalPages": 3
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 404 | `NOT_FOUND` | Resource not found |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Requires **Builder** tier or higher.
- Stats are **frozen**: they never change for a given version.
- Results are sorted alphabetically by firearm name.
- Use `per_page=100` to fetch in larger batches for bulk loading.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/game-stats/versions/2025.1/firearms' \
  --header 'X-API-Key: your_key'
```

## Get Firearm in Version

`GET /v1/game-stats/versions/{version}/firearms/{id}`

Auth: API key required  
Tier: Builder+

Returns the game stats for a single firearm as frozen in one snapshot version.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | string | yes | Snapshot version |
| `id` | string | yes | Firearm slug |

### Response 200 (application/json)

| Field | Type | Description |
| --- | --- | --- |
| `data` | GameStatsSnapshotEntry | The response payload |
| `data.firearm_id` | string | Slug of the firearm this row is about. |
| `data.firearm_name` | string | Display name at the time the snapshot was taken. |
| `data.game_damage` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_accuracy` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_range` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_fire_rate` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_mobility` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_recoil_control` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_reload_speed` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |
| `data.game_concealment` | integer \| null | Editorial game statistic as it stood in this snapshot, 0-100. |

```json
{
  "success": true,
  "data": {
    "firearm_id": "glock-g17-gen5",
    "firearm_name": "Glock 17 Gen5",
    "game_damage": 42,
    "game_accuracy": 68,
    "game_range": 35,
    "game_fire_rate": 55,
    "game_mobility": 78,
    "game_recoil_control": 62,
    "game_reload_speed": 72,
    "game_concealment": 70
  }
}
```

### Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Validation error |
| 401 | `UNAUTHORIZED` | API key required |
| 403 | `FORBIDDEN` | Valid key, not permitted |
| 404 | `NOT_FOUND` | Resource not found |
| 429 | `RATE_LIMITED` | Rate limit exceeded |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

### Notes

- Requires **Builder** tier or higher.
- Returns 404 if the firearm had no game stats when the snapshot was created.
- Stats are **frozen**: identical every time you call this for the same version.

### Example

```bash
curl --request GET \
  --url 'https://api.gunspec.io/v1/game-stats/versions/2025.1/firearms/glock-g17-gen5' \
  --header 'X-API-Key: your_key'
```