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

# API Reference

> Complete Tournament Platform API documentation with interactive examples

# Tournament Platform API

The Tournament Platform provides comprehensive REST APIs for integrating real-time multiplayer tournaments into casino systems and game platforms. Our APIs are designed for reliability, scalability, and ease of integration.

## API Overview

The Tournament Platform offers two distinct API sets:

<CardGroup cols={2}>
  <Card title="Casino Integration APIs" icon="building" href="/casino-integration/introduction">
    External APIs for casino systems to manage tournaments, players, and results
  </Card>

  <Card title="Game Platform APIs" icon="gamepad" href="/game-platform-integration/introduction">
    Internal APIs for game platforms to handle authentication, rooms, and events
  </Card>
</CardGroup>

## Base URL

### Production Environment

```
https://ts.playservices.tech/api
```

<Note>
  This is the production Tournament Platform API. Use appropriate testing strategies and start with small-scale tournaments during initial integration.
</Note>

## Authentication

The Tournament Platform uses **Bearer Token authentication** with different API keys for different integration types:

### Casino Integration (External APIs)

* **API Key Format**: `sk_live_...` (production)
* **Usage**: Tournament management, player registration, results retrieval
* **Permissions**: Operator-specific access to tournaments and players

```bash theme={null}
curl -H "Authorization: Bearer sk_live_your_casino_api_key_here" \
  https://ts.playservices.tech/api/tournaments
```

### Game Platform (Internal APIs)

* **API Key Format**: `internal_...`
* **Usage**: JWT validation, room management, tournament configuration
* **Permissions**: Access to internal game-specific endpoints

```bash theme={null}
curl -H "Authorization: Bearer internal_your_game_platform_key" \
  https://ts.playservices.tech/api/internal/auth/validate-token
```

<Warning>
  Keep your API keys secure and never expose them in client-side code. API keys provide access to sensitive tournament and player data.
</Warning>

## Rate Limiting

The Tournament Platform enforces rate limits to ensure service reliability:

| API Type           | Rate Limit           | Burst Limit      |
| ------------------ | -------------------- | ---------------- |
| Casino Integration | 1000 requests/minute | 100 requests/10s |
| Game Platform      | 5000 requests/minute | 500 requests/10s |
| Webhooks           | No limit             | -                |

When you exceed rate limits, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating when to retry.

## Request/Response Format

### Content Type

All API endpoints accept and return `application/json`. Always include the `Content-Type` header in POST/PUT requests:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily Championship"}' \
  https://ts.playservices.tech/api/tournaments
```

### Response Structure

All API responses follow a consistent format:

**Success Response (200-299):**

```json theme={null}
{
  "tournamentId": "12345",
  "name": "Daily Championship",
  "status": "scheduled",
  ...
}
```

**Error Response (400-599):**

```json theme={null}
{
  "error": "tournament_not_found",
  "message": "Tournament with ID 12345 does not exist",
  "details": {
    "tournamentId": "12345",
    "timestamp": "2024-01-15T20:30:00Z"
  }
}
```

## Error Handling

### HTTP Status Codes

| Code  | Description           | Common Causes                              |
| ----- | --------------------- | ------------------------------------------ |
| `200` | Success               | Request completed successfully             |
| `201` | Created               | Resource created (tournaments, players)    |
| `400` | Bad Request           | Invalid request parameters or format       |
| `401` | Unauthorized          | Invalid or missing API key                 |
| `403` | Forbidden             | API key lacks required permissions         |
| `404` | Not Found             | Tournament, player, or resource not found  |
| `409` | Conflict              | Resource conflict (duplicate registration) |
| `429` | Too Many Requests     | Rate limit exceeded                        |
| `500` | Internal Server Error | Temporary server issue                     |

### Error Codes

Common error codes and their meanings:

| Error Code                  | Description                     | Resolution                         |
| --------------------------- | ------------------------------- | ---------------------------------- |
| `invalid_api_key`           | API key format invalid          | Check key format and environment   |
| `tournament_not_found`      | Tournament doesn't exist        | Verify tournament ID               |
| `player_already_registered` | Player already in tournament    | Check existing registrations       |
| `tournament_full`           | Max players reached             | Increase limit or use waiting list |
| `insufficient_balance`      | Player lacks funds              | Verify account balance             |
| `tournament_started`        | Cannot modify active tournament | Only modify before start           |

## Pagination

List endpoints support pagination using `limit` and `offset` parameters:

```http theme={null}
GET /api/tournaments?limit=50&offset=100
```

**Response includes pagination metadata:**

```json theme={null}
{
  "tournaments": [...],
  "pagination": {
    "total": 1247,
    "limit": 50,
    "offset": 100,
    "hasMore": true
  }
}
```

## Filtering & Sorting

Most list endpoints support filtering and sorting:

```http theme={null}
GET /api/tournaments?status=in_progress&gameSlug=crash-classic&sort=createdAt:desc
```

**Common filter parameters:**

* `status` - Filter by tournament status
* `gameSlug` - Filter by game type
* `startDate` / `endDate` - Filter by date range
* `minPlayers` / `maxPlayers` - Filter by player count

## Event Notifications

The Tournament Platform sends real-time tournament event notifications via SQS transport. Webhook endpoints are configured at the transport level, not via API.

<Card title="Event Documentation" icon="bell" href="/casino-integration/webhooks-events">
  Complete guide to tournament event handling and SQS integration
</Card>

## SDKs & Libraries

Official SDKs are available for popular programming languages:

<CardGroup cols={3}>
  <Card title="JavaScript/Node.js" icon="js">
    ```bash theme={null}
    npm install @tournament-platform/js-sdk
    ```
  </Card>

  <Card title="PHP" icon="php">
    ```bash theme={null}
    composer require tournament-platform/php-sdk
    ```
  </Card>

  <Card title="Python" icon="python">
    ```bash theme={null}
    pip install tournament-platform-sdk
    ```
  </Card>
</CardGroup>

## Interactive API Explorer

Use the interactive API explorer below to test endpoints with your API keys:

<Note>
  The API explorer uses the OpenAPI specification to provide real-time API testing. Use appropriate testing strategies when working with the production API.
</Note>

## Common Workflows

### 1. Tournament Creation & Management

1. [Create Tournament](/api-reference/endpoint/create-tournament) - Set up new tournament
2. [Update Tournament](/api-reference/endpoint/update-tournament) - Modify before start
3. [List Tournaments](/api-reference/endpoint/list-tournaments) - View all tournaments
4. [Get Tournament](/api-reference/endpoint/get-tournament) - Retrieve details

### 2. Player Registration & Management

1. [Register Player](/api-reference/endpoint/register-player) - Add player to tournament
2. [Process Rebuy](/api-reference/endpoint/process-rebuy) - Handle additional entries
3. [List Players](/api-reference/endpoint/list-players) - View tournament participants

### 3. Results & Leaderboards

1. [Get Leaderboard](/api-reference/endpoint/get-leaderboard) - Real-time rankings
2. [Get Results](/api-reference/endpoint/get-results) - Final tournament results
3. [Player History](/api-reference/endpoint/player-history) - Historical performance

### 4. Game Platform Integration

1. [Validate JWT](/api-reference/endpoint/validate-jwt) - Authenticate player access
2. [Get Config](/api-reference/endpoint/get-config) - Retrieve tournament settings
3. [Report Events](/api-reference/endpoint/report-events) - Send game events

## Support & Resources

<CardGroup cols={2}>
  <Card title="API Status" icon="chart-line" href="https://ts.playservices.tech/">
    Check real-time API availability and performance
  </Card>

  <Card title="Developer Support" icon="help-circle" href="mailto:support@playservices.tech">
    Get help with integration questions
  </Card>

  <Card title="Testing Guide" icon="flask" href="/casino-integration/testing-debugging">
    Testing strategies and debugging tools
  </Card>

  <Card title="Best Practices" icon="star" href="/casino-integration/authentication">
    Security and integration best practices
  </Card>
</CardGroup>

## API Changelog

Stay updated on API changes and new features:

* **v1.0.0** (Current) - Initial release with full tournament management
* All breaking changes will be announced 30 days in advance
* Deprecated endpoints will be supported for 6 months minimum

<Note>
  Subscribe to our [developer newsletter](mailto:support@playservices.tech) for API updates and new feature announcements.
</Note>