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

# Tournament Management

> Create, update, cancel, and monitor tournaments using the external Casino Integration APIs

# Tournament Management

The Tournament Management APIs enable casino operators to create, manage, and monitor tournaments across both scheduled and hop-on/off formats using external APIs.

## Overview

Tournament Management provides complete lifecycle control over tournaments:

* **Create** scheduled tournaments with specific start times
* **Monitor** real-time tournament status and player counts
* **Update** tournament configurations and settings
* **Cancel** tournaments when necessary
* **List** and filter tournaments across your operator account

<Info>
  **Permission Required**: `tournaments.write` for create/update/delete operations, `tournaments.read` for viewing tournaments.
</Info>

## Tournament Creation

### Scheduled Tournament Creation

Create tournaments that start at a specific scheduled time:

```http theme={null}
POST /api/tournaments
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "name": "Test Tournament",
  "external_id": "EXT_001",
  "game": "crash-classic",
  "scheduled_start": "2024-01-15T20:00:00Z",
  "max_players": 50,
  "min_players": 5,
  "entry_fee": 10.50,
  "prize_pool": {
    "total": 500,
    "distribution": {
      "1": 50,
      "2": 30,
      "3": 20
    }
  },
  "config": {
    "tournament_type": "points_based"
  }
}
```

**Response:**

```json theme={null}
{
  "tournament_id": "12345",
  "status": "scheduled",
  "estimated_prize_pool": 500,
  "tournament": {
    "id": "12345",
    "name": "Test Tournament",
    "operator_id": "op_123",
    "status": "scheduled",
    "games": [
      {
        "slug": "crash-classic",
        "config": {},
        "status": "active"
      }
    ]
  }
}
```

### Tournament Configuration Options

<Tabs>
  <Tab title="Basic Settings">
    ```json theme={null}
    {
      "name": "Tournament Name",
      "game": "crash-classic",
      "max_players": 100,
      "min_players": 5,
      "entry_fee": 10.00
    }
    ```

    * **name**: Display name for the tournament
    * **game**: Game type identifier
    * **max\_players**: Maximum participant limit (optional - null for unlimited)
    * **min\_players**: Minimum players to start
    * **entry\_fee**: Cost to join tournament

    <Info>
      **Unlimited Capacity**: Set `max_players` to `null` for tournaments with no participant limit. This is useful for hop-on/off style tournaments.
    </Info>
  </Tab>

  <Tab title="Timing">
    ```json theme={null}
    {
      "scheduled_start": "2024-01-15T20:00:00Z"
    }
    ```

    * **scheduled\_start**: When tournament is scheduled to begin

    <Info>
      The tournament platform handles registration timing automatically based on the tournament status and configuration.
    </Info>
  </Tab>

  <Tab title="Prize Pool">
    ```json theme={null}
    {
      "prize_pool": {
        "total": 500,
        "distribution": {
          "1": 50,
          "2": 30,
          "3": 20
        }
      }
    }
    ```

    * **total**: Total prize pool amount
    * **distribution**: Prize distribution by position (percentages)

    **Example**: With 100 entry fee and above distribution:

    * 1st place: 50% of total = \$250
    * 2nd place: 30% of total = \$150
    * 3rd place: 20% of total = \$100
  </Tab>

  <Tab title="Multi-Entry Configuration">
    These fields are set at the tournament level and control the rebuy system:

    ```json theme={null}
    {
      "max_entries_per_player": 3,
      "rebuy_enabled": true,
      "rebuy_fee": 20.00
    }
    ```

    * **max\_entries\_per\_player**: Maximum total entries per player (includes initial entry)
    * **rebuy\_enabled**: Enable multi-entry functionality
    * **rebuy\_fee**: Cost per additional entry beyond the first

    <Warning>
      Rebuy settings are validated when tournaments are created. Players can only rebuy during active tournament phases.
    </Warning>
  </Tab>
</Tabs>

## Tournament Monitoring

### Get Tournament Status

Monitor tournament progress and current state:

```http theme={null}
GET /api/tournaments/12345/status
Authorization: Bearer {your-api-key}
```

**Response:**

```json theme={null}
{
  "tournamentId": "12345",
  "status": "in_progress",
  "currentPlayers": 87,
  "maxPlayers": 100,
  "startTime": "2024-01-15T20:00:00Z",
  "actualStartTime": "2024-01-15T20:02:15Z",
  "estimatedEndTime": "2024-01-15T21:15:00Z",
  "currentRound": 3,
  "totalRounds": 5,
  "registrationStatus": "closed",
  "prizePool": {
    "totalAmount": 870.00,
    "currency": "USD"
  },
  "gameRoom": {
    "roomId": "room_abc123",
    "activeConnections": 87
  }
}
```

### Tournament Status Values

| Status        | Description                                | Available Actions                   |
| ------------- | ------------------------------------------ | ----------------------------------- |
| `scheduled`   | Tournament created, waiting for start time | Update, Cancel, View                |
| `open`        | Registration open, tournament not started  | Update, Cancel, Register Players    |
| `in_progress` | Tournament actively running                | View, Register Players (if allowed) |
| `completed`   | Tournament finished, results available     | View Results                        |
| `cancelled`   | Tournament cancelled before completion     | View                                |

### List Tournaments

Retrieve tournaments with filtering and pagination:

```http theme={null}
GET /api/tournaments?status=in_progress&limit=20&offset=0
Authorization: Bearer {your-api-key}
```

**Query Parameters:**

* `status` - Filter by tournament status
* `gameSlug` - Filter by game type
* `startDate` - Filter tournaments starting after date
* `endDate` - Filter tournaments starting before date
* `limit` - Number of results per page (default: 50, max: 100)
* `offset` - Pagination offset

**Response:**

```json theme={null}
{
  "tournaments": [
    {
      "tournamentId": "12345",
      "name": "Daily Championship",
      "status": "in_progress", 
      "startTime": "2024-01-15T20:00:00Z",
      "currentPlayers": 87,
      "maxPlayers": 100,
      "prizePool": 870.00
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}
```

## Tournament Updates

### Update Tournament Configuration

Modify tournament settings before or during play:

```http theme={null}
PUT /api/tournaments/12345
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "name": "Updated Championship Name",
  "maxPlayers": 120,
  "registrationCloses": "2024-01-15T19:45:00Z"
}
```

<Warning>
  **Update Restrictions**: Some fields cannot be modified once the tournament has started. Check the response for any validation errors.
</Warning>

### Updateable Fields by Status

<Tabs>
  <Tab title="Scheduled Status">
    **Full Control** - All fields can be updated:

    * Tournament name and description
    * Start/end times
    * Player limits and entry fees
    * Prize pool configuration
    * Registration windows
  </Tab>

  <Tab title="Open Status">
    **Limited Updates** - Registration active:

    * Tournament name and description
    * Maximum players (can only increase)
    * Registration close time (can extend)
    * Prize pool (can only increase)
  </Tab>

  <Tab title="In Progress">
    **Minimal Updates** - Tournament running:

    * Tournament name and description only
    * No timing or configuration changes
  </Tab>
</Tabs>

## Tournament Cancellation

### Cancel Tournament

Cancel a tournament before or during play:

```http theme={null}
DELETE /api/tournaments/12345
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "reason": "Insufficient players",
  "refundPlayers": true,
  "notifyPlayers": true
}
```

**Parameters:**

* `reason` - Reason for cancellation (for audit logs)
* `refundPlayers` - Whether to process player refunds
* `notifyPlayers` - Send cancellation notifications

**Response:**

```json theme={null}
{
  "tournamentId": "12345",
  "status": "cancelled",
  "cancelledAt": "2024-01-15T19:45:00Z",
  "reason": "Insufficient players",
  "playersRefunded": 15,
  "refundAmount": 150.00
}
```

### Cancellation Policies

<Info>
  Tournament cancellation triggers automatic refund processing for all registered players and sends webhook notifications to your system.
</Info>

**Cancellation Rules:**

* **Scheduled Tournaments**: Can be cancelled before start time
* **In-Progress Tournaments**: Can be cancelled during active play (NEW)
* **Completed Tournaments**: Cannot be cancelled (results are final)

**Refund Processing:**

* **Before Start**: Full refunds for all entry fees and rebuys
* **During Play**: Partial refunds based on tournament progress
* **After Completion**: No refunds (tournament results stand)

## Advanced Tournament Management

### Tournament Templates

Create reusable tournament templates for common configurations:

```http theme={null}
POST /api/tournament-templates
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "name": "Daily Championship Template",
  "gameSlug": "crash-classic",
  "maxPlayers": 100,
  "entryFee": 10.00,
  "prizePool": {
    "type": "percentage", 
    "distribution": [50, 30, 20]
  },
  "rebuyEnabled": true
}
```

### Bulk Operations

Create multiple tournaments from templates:

```http theme={null}
POST /api/tournaments/bulk
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "templateId": "template_123",
  "schedule": [
    {
      "startTime": "2024-01-15T20:00:00Z",
      "name": "Monday Championship"
    },
    {
      "startTime": "2024-01-16T20:00:00Z", 
      "name": "Tuesday Championship"
    }
  ]
}
```

## Error Handling

### Common Error Responses

#### Invalid Tournament Configuration

```json theme={null}
{
  "error": "validation_failed",
  "message": "Tournament configuration is invalid",
  "details": {
    "startTime": "Start time must be in the future",
    "maxPlayers": "Maximum players must be greater than minimum players"
  }
}
```

#### Tournament Not Found

```json theme={null}
{
  "error": "tournament_not_found",
  "message": "Tournament with ID 12345 not found",
  "tournamentId": "12345"
}
```

#### Insufficient Permissions

```json theme={null}
{
  "error": "insufficient_permissions",
  "message": "API key lacks required permissions",
  "required": "tournaments.write",
  "provided": ["tournaments.read"]
}
```

### Best Practices

<CardGroup cols={2}>
  <Card title="Validation" icon="check">
    * Validate all input parameters before API calls
    * Check tournament status before attempting updates
    * Verify player limits and timing constraints
  </Card>

  <Card title="Error Handling" icon="alert-triangle">
    * Implement proper error handling for all status codes
    * Use exponential backoff for retries
    * Log errors for debugging and monitoring
  </Card>

  <Card title="Monitoring" icon="chart-line">
    * Monitor tournament status regularly
    * Set up alerts for tournament failures
    * Track player registration patterns
  </Card>

  <Card title="Testing" icon="flask">
    * Test tournament creation in sandbox environment
    * Verify cancellation and refund workflows
    * Load test player registration flows
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Player Management" icon="users" href="/casino-integration/player-management">
    Learn how to register and manage players in your tournaments.
  </Card>

  <Card title="Results & Leaderboards" icon="trophy" href="/casino-integration/results-leaderboards">
    Access real-time rankings and final tournament results.
  </Card>
</CardGroup>