> ## Documentation Index
> Fetch the complete documentation index at: https://playwave.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> PlayWave Game Server API authentication, base URL, and response format

## Base URL

| Environment | URL                                   | Status                                    |
| ----------- | ------------------------------------- | ----------------------------------------- |
| **Dev**     | `https://wave-api.playwave.dev/v1`    | <Badge color="green">Available</Badge>    |
| **QA**      | `https://wave-api-qa.playwave.dev/v1` | <Badge color="yellow">Coming soon</Badge> |
| **Live**    | `https://wave-api.playwave.io/v1`     | <Badge color="yellow">Coming soon</Badge> |

## Authentication

All requests require the `X-Api-Key` header.

<ParamField header="X-Api-Key" type="string" required>
  Per-game API Key. The server matches the <Tooltip tip="Cryptographic hash function that converts the API Key into a fixed-length digest for secure comparison">SHA-256 hash</Tooltip> of the key to the game configuration.
</ParamField>

<Info>
  API Keys are currently issued by the PlayWave operations team. Contact your PlayWave representative to request a key for your game.
</Info>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<Warning>
  API Key must only be used server-side. If exposed to clients, regenerate it immediately from the console.
</Warning>

## Response format

### Success response

```json theme={null}
{
  "success": true,
  "request_id": "req_abc123",
  "data": {
    // Endpoint-specific response data
  }
}
```

### Error response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key is invalid or inactive",
    "timestamp": "2026-03-06T12:00:00.000Z"
  }
}
```

## Endpoints

The game server calls 3 APIs.

| Method                            | Path                                                     | Description                                                                                                                                                   |
| --------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Badge color="green">POST</Badge> | [`/v1/game/session/verify`](/api-reference/verify)       | <Tooltip tip="One-Time Token — a single-use token that transfers the session from launcher to game server">OTT</Tooltip> verification + game session creation |
| <Badge color="blue">PATCH</Badge> | [`/v1/game/session/heartbeat`](/api-reference/heartbeat) | Game session heartbeat (every 2 min)                                                                                                                          |
| <Badge color="red">DELETE</Badge> | [`/v1/game/session/end`](/api-reference/end)             | Game session termination                                                                                                                                      |

## Common error codes

| Code              | HTTP                              | Description                    |
| ----------------- | --------------------------------- | ------------------------------ |
| `BAD_REQUEST`     | <Badge color="yellow">400</Badge> | Request body validation failed |
| `INVALID_API_KEY` | <Badge color="yellow">401</Badge> | Invalid API Key                |
| `RATE_LIMITED`    | <Badge color="orange">429</Badge> | Request rate limit exceeded    |
| `INTERNAL_ERROR`  | <Badge color="red">500</Badge>    | Internal server error          |