API Reference

Integrate with ChessMaster Forum programmatically. Access user data, game histories, puzzles, forum threads, and tournament results with our RESTful JSON API.

https://api.chessmasterforum.com/v1

ℹ️

All API requests require authentication. Responses are returned in JSON format. Default pagination is 25 items per page.

Authentication

Authenticate your requests using API Keys or OAuth 2.0. Include your key in the request header.

# Replace with your API key
curl -X GET https://api.chessmasterforum.com/v1/users/me \
  -H "X-API-Key: cm_live_sk_9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json"
                        

import requests

headers = {
    "X-API-Key": "cm_live_sk_9f8e7d6c5b4a3210",
    "Content-Type": "application/json"
}

response = requests.get("https://api.chessmasterforum.com/v1/users/me", headers=headers)
print(response.json())
                        

const response = await fetch('https://api.chessmasterforum.com/v1/users/me', {
  headers: {
    'X-API-Key': 'cm_live_sk_9f8e7d6c5b4a3210',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
                        

Users

GET /users List all users

Retrieve a paginated list of registered users. Supports filtering by rating, country, and join date.

Parameter	Type	Description
pageoptional	integer	Page number (default: 1)
limitoptional	integer	Items per page (max: 100)
min_ratingoptional	integer	Filter by minimum Elo

GET /users/:id Get user profile

Fetch detailed profile data for a specific user including rating history, badges, and stats.

Games

GET /games/:id Get game details

Retrieve full game data including PGN, move timestamps, engine evaluations, and player ratings at time of play.

Response Example

{
  "id": "game_8x92k1",
  "white": { "id": "usr_123", "rating": 2150 },
  "black": { "id": "usr_456", "rating": 2180 },
  "result": "1-0",
  "time_control": "10+5",
  "moves": ["e4", "e5", "Nf3", "Nc6"],
  "pgn": "[Event \"Casual Online\"]...",
  "created_at": "2025-03-15T14:22:00Z"
}
                                

Forum & Threads

GET /forum/threads List forum threads

Access community discussions. Filter by category, sort by activity or creation date.

POST /forum/threads Create new thread

Requires forum:write scope. Body must include title, content, and category_id.

Rate Limits

API requests are limited based on your subscription tier. Exceeding limits returns 429 Too Many Requests.

Tier	Requests / Min	Requests / Day
Free	60	5,000
Pro	300	50,000
Enterprise	Unlimited	Unlimited

Error Handling

ChessMaster API uses standard HTTP status codes. Errors return a JSON body with a machine-readable code.

Error Response

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is malformed or expired.",
    "status": 401,
    "request_id": "req_7x892k1"
  }
}
                        