ChessMaster Forum API

Integrate seamlessly with ChessMaster Forum to build chess applications, analyze games, manage tournaments, and interact with our community programmatically.

Base URL: https://api.chessmasterforum.com/v1

🔑 How to get an API key

Sign in to your ChessMaster account, navigate to Settings → API Access, and generate a new token. Keep it secure and never expose it in client-side code.

Authentication

All API requests require authentication via Bearer token in the Authorization header.

HTTP Header

Authorization: Bearer YOUR_API_KEY

Rate Limits

Plan	Requests / min	Burst Limit
Free	100	20
Pro	1,000	100
Enterprise	Custom	Custom

Exceeding limits returns 429 Too Many Requests. Headers X-RateLimit-Remaining and X-RateLimit-Reset are included in every response.

Endpoints

GET /players/{player_id} Retrieve player profile & statistics

Fetch detailed information about a player, including ratings, win rates, and recent activity.

Parameters

Name	In	Type	Description
player_id	Path	string	Required • UUID or username

Response Example

JSON

{
  "id": "player_9f8a7b6c",
  "username": "GM_Strategist",
  "title": "FIDE Master",
  "ratings": {
    "blitz": 2150,
    "rapid": 2280,
    "classical": 2340
  },
  "stats": {
    "games_played": 4821,
    "win_rate": 0.62,
    "peak_rating": 2410
  },
  "joined_at": "2021-03-15T08:42:00Z"
}

POST /games Create a new chess game/match

Initialize a new game session. Supports classical, rapid, and blitz time controls.

Request Body

Field	Type	Description
opponent_id	string	Required • Target player UUID
time_control	string	Optional • `5+3`, `10+5`, `15+10`
opening_variation	string	Optional • ECO code or null

Response Example

JSON

{
  "game_id": "game_x7y9z2w4",
  "status": "created",
  "board_url": "https://chessmasterforum.com/play/game_x7y9z2w4",
  "expires_at": "2025-08-20T14:00:00Z"
}

GET /tournaments List active & upcoming tournaments

Retrieve tournaments filtered by status, format, or rating range.

Query Parameters

Name	Type	Description
status	string	Optional • `live`, `upcoming`, `finished`
format	string	Optional • `swiss`, `knockout`, `round_robin`
min_rating	integer	Optional • Minimum ELO filter

POST /forum/posts Create a new forum discussion

Post a new thread in any community category. Supports markdown formatting.

Request Body

Field	Type	Description
category_id	string	Required • Forum category slug
title	string	Required • Max 120 chars
body	string	Required • Markdown content
tags	array	Optional • Max 5 tags

Pagination

All list endpoints support cursor-based pagination. Use ?cursor=xyz to fetch the next page. Response includes next_cursor when more results are available.

Error Handling

The API uses standard HTTP status codes and returns detailed error payloads in JSON format.

Code	Message	Meaning
400	Bad Request	Invalid parameters or malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded. Retry after X-RateLimit-Reset
500	Internal Server Error	Something went wrong on our end

Error Response Format

{
  "error": {
    "code": 401,
    "message": "Invalid or expired API key",
    "details": "Ensure you are using a v1.2 compatible token."
  }
}