{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d095997f-866b-41ee-91f4-a38e92f51650","name":"Chess Match Analytics API","description":"# ♟️ Chess Match Analytics API\n\nWelcome to the **Chess Match Analytics API** — a complete backend API for storing, managing, and deeply analyzing chess matches. Whether you're building a chess platform, studying game patterns, or exploring chess statistics, this API covers everything from basic match CRUD to advanced analytics, player profiles, opening theory, and admin controls.\n\n---\n\n## 🌐 Base URL\n\n```\n{{baseUrl}}/api/v1\n```\n\n> Set the `baseUrl` variable in your Postman environment to your server address, for example: `http://localhost:3000`\n\n---\n\n## 🔐 Authentication\n\nThis API uses **JWT (JSON Web Token)** Bearer authentication.\n\n**How it works:**\n1. Register a new account or log in with existing credentials.\n2. You'll receive a `token` in the response.\n3. This token must be sent with every protected request in the `Authorization` header:\n\n```\nAuthorization: Bearer <your_token_here>\n```\n\nThe collection is already configured to use `{{json_web_token_0tq4}}` as the Bearer token. Just set this variable in your environment after logging in and all protected requests will work automatically.\n\n---\n\n## 🚀 Getting Started\n\nFollow these steps to start using the API:\n\n**Step 1 — Register** → Send a `POST` request to `/api/v1/auth/register` with your username, email, and password.\n\n**Step 2 — Login** → Send a `POST` request to `/api/v1/auth/login` with your credentials. Copy the `token` from the response.\n\n**Step 3 — Save your token** → Set the `json_web_token_0tq4` variable in your Postman environment to the token value.\n\n**Step 4 — Explore** → You're ready! Start with `GET /api/v1/matches` to browse chess matches.\n\n---\n\n## 📁 Folder Overview\n\n| Folder | Description |\n|---|---|\n| **Auth** | Register, login, and view your profile |\n| **Matches** | Full CRUD for chess matches — create, read, update, delete, filter, sort, bulk operations |\n| **Search** | Search matches, players, openings, ECO codes, moves, and more |\n| **Analytics** | Deep analytics — victory distribution, rating upsets, time control usage, hourly activity |\n| **Stats** | Quick stats — total matches, win rates, draw rates, top openings |\n| **System** | Server health, uptime, logs, config, performance metrics |\n| **Players** | Player profiles, stats, win/loss/draw rates, rating history, comparisons |\n| **Openings Theory** | Browse chess openings — popular, aggressive, defensive, gambits, by ECO code |\n| **Admin & Middleware** | Admin-only routes — manage users, clear cache, view logs, middleware inspection |\n| **Pagination** | Examples of standard, cursor-based, and infinite scroll pagination |\n| **Sorting** | Examples of sorting matches by date, rating, move count, duration, and more |\n| **HEAD & OPTIONS** | HTTP HEAD and OPTIONS requests for checking headers and CORS preflight |\n\n---\n\n## 📦 Match Object Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `id` | string | Unique match identifier |\n| `white` | string | Username of the white player |\n| `black` | string | Username of the black player |\n| `winner` | string | `\"white\"`, `\"black\"`, or `\"draw\"` |\n| `termination` | string | How the game ended: `\"checkmate\"`, `\"resignation\"`, `\"timeout\"`, `\"draw\"` |\n| `opening` | string | Name of the opening played |\n| `eco` | string | ECO code of the opening (e.g., `B20`) |\n| `moves` | number | Total number of moves in the game |\n| `rated` | boolean | Whether the game was rated |\n| `timeControl` | string | Time control: `\"bullet\"`, `\"blitz\"`, `\"rapid\"`, `\"classical\"` |\n| `whiteRating` | number | Elo rating of the white player |\n| `blackRating` | number | Elo rating of the black player |\n| `pgn` | string | Full PGN notation of the game |\n| `fen` | string | Final FEN position of the game |\n| `createdAt` | string | ISO timestamp of when the match was recorded |\n\n---\n\n## 💡 Tips\n\n- All list endpoints support `?page=1&limit=10` for pagination.\n- Filter endpoints use dedicated routes like `/matches/filter/blitz`.\n- Sorting endpoints use query params like `?sort=moves&order=desc`.\n- Admin routes require a valid JWT token with admin privileges.\n- Use the **HEAD** method to check if a resource exists without downloading the full response body.\n- Use the **OPTIONS** method to check which HTTP methods are allowed on an endpoint (useful for CORS).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"50839854","team":12207201,"collectionId":"d095997f-866b-41ee-91f4-a38e92f51650","publishedId":"2sBXwtqpxw","public":true,"publicUrl":"https://documenter-api.postman.tech/view/50839854/2sBXwtqpxw","privateUrl":"https://go.postman.co/documentation/50839854-d095997f-866b-41ee-91f4-a38e92f51650","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"Welcome to the Chess Match Analytics API, a backend service for managing and analyzing chess matches. It supports match CRUD operations, player statistics, opening analysis, game insights, profile management, and administrative controls, making it ideal for chess platforms, analytics tools, and research applications."},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.12.5","publishDate":"2026-06-17T18:06:28.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":"Welcome to the Chess Match Analytics API, a backend service for managing and analyzing chess matches. It supports match CRUD operations, player statistics, opening analysis, game insights, profile management, and administrative controls, making it ideal for chess platforms, analytics tools, and research applications."},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/f677d0958f8c6b981fed68d3971e657d844ebf9c411bc07a7c905e952d65f53f","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sBXwtqpxw"}