♔ API Overview

Welcome to the ChessMaster Forum API. Our RESTful API allows you to integrate chess games, forum discussions, tournament data, and user profiles directly into your applications. All endpoints return JSON responses and require authentication.

🔐 Authentication

Access to the API is secured using Bearer tokens. Include your API key in the Authorization header of every request.

Authorization: Bearer YOUR_API_KEY_HERE

Generate your key from the Developer Dashboard. Keys are scoped to either read or read+write permissions.

🌐 Base URL & Headers

All requests should be made to:

https://api.chessmasterforum.com/v1

Standard headers required:

Get Current User

Returns the authenticated user's profile, rating, and subscription tier.

{
  "id": "usr_8x9k2m4p",
  "username": "grandmaster_alex",
  "email": "alex@example.com",
  "rating": {
    "blitz": 2450,
    "rapid": 2380,
    "classical": 2510
  },
  "tier": "premium",
  "joined_at": "2022-03-15T08:30:00Z",
  "is_verified": true
}

Create New Game

Initiates a new chess match. Requires a target user ID or open lobby configuration.

{
  "opponent_id": "usr_7h3j9n1q",
  "time_control": "10+5",
  "variant": "standard",
  "color_preference": "random"
}

Submit Move

Records a move for an active game. Uses standard algebraic notation (SAN).

{
  "success": true,
  "move_index": 14,
  "fen": "r1bqkb1r/pppp1ppp/2n2n2/4p2Q/2B1P3/8/PPPP1PPP/RNB1K1NR w KQkq - 4 4",
  "is_check": true,
  "time_remaining": 342
}

List Forum Threads

Retrieves paginated forum discussions. Supports filtering by category, tag, and sort order.

Upcoming Tournaments

Returns active and upcoming tournament brackets, schedules, and registration status.

{
  "data": [
    {
      "id": "trn_9m2x4k8p",
      "name": "Weekly Blitz Championship",
      "format": "Swiss 9-round",
      "time_control": "3+2",
      "starts_at": "2025-06-15T18:00:00Z",
      "status": "registration_open",
      "participants": 842,
      "prize_pool": 2500
    }
  ]
}

⚠️ Error Handling

The API uses standard HTTP status codes. All errors return a structured JSON response.

{
  "error": {
    "code": "INVALID_MOVE",
    "message": "Move 'Qh7#' is illegal in current position",
    "details": {
      "game_id": "gm_3x8k2m9p",
      "move_index": 12
    }
  }
}