# GameHub Arena Public API — LLM & AI Agent Context > Official API specification for GameHub Arena (https://gamehub-arena.com), the premier competitive gaming and e-sport tournament platform in Africa and internationally (Cameroon, Ivory Coast, Senegal, Gabon, France, etc.). > This document follows the standard https://llmstxt.org specification for Large Language Models (LLMs), AI assistants (ChatGPT, Claude, Gemini, Antigravity, Copilot), and automated agents. ## Overview GameHub Arena provides a high-performance, read-only REST API v1 allowing developers, Discord bots, companion mobile apps, streaming overlays, and AI agents to query live tournament registrations, participant rosters, game leaderboards, Looking For Team (LFT) announcements, and community news in real time. - **Base URL (Subdomain, Recommended)**: `https://api.gamehub-arena.com/v1` - **Base URL (Main Domain Alternative)**: `https://gamehub-arena.com/api/v1` - **Web Documentation**: `https://api.gamehub-arena.com/docs` - **Developer Portal & Key Management**: `https://gamehub-arena.com/developpeurs` - **Supported Output Format**: `application/json` (UTF-8) - **Currency**: Central African CFA Franc (`XAF`), 1 EUR ≈ 655.957 XAF --- ## Authentication & Security Every request to `/v1/*` must include a valid API key issued to an active developer account. ### Header Pass the API key in the standard HTTP `Authorization` header: ```http Authorization: Bearer ghk_live_YOUR_API_KEY ``` Alternative supported header: ```http X-API-Key: ghk_live_YOUR_API_KEY ``` ### Key Anatomy - Prefix: `ghk_live_` (for production/live keys) or `ghk_test_` (for sandbox) - Suffix: 32 hexadecimal characters (cryptographically secure) - Example: `ghk_live_a1b2c3d4e5f60718293a4b5c6d7e8f90` --- ## Rate Limits & Quotas Quotas depend on the developer plan (Gratuit, Pro, Entreprise) and are communicated in the HTTP response headers on every call: - `X-RateLimit-Limit`: Maximum requests allowed for the current 1-minute window. - `X-RateLimit-Remaining`: Requests remaining in the current window. - `X-RateLimit-Reset`: Number of seconds until the current minute quota resets. - `X-API-Plan`: Code of the active plan (`gratuit`, `pro`, `entreprise`). When a quota is exceeded, the server returns `HTTP 429 Too Many Requests` with a `Retry-After` header. --- ## API Endpoints Reference (v1) ### 1. Test Connectivity / Ping - **Method & Path**: `GET /v1/ping` - **Description**: Lightweight health and credential validation probe. - **Headers**: `Authorization: Bearer ` - **Response `200 OK`**: ```json { "data": { "statut": "ok", "version": "v1" } } ``` ### 2. Service Status & Account Usage - **Method & Path**: `GET /v1/status` - **Description**: Inspect developer account name, active subscription tier, current quotas, and server ISO-8601 timestamp. - **Response `200 OK`**: ```json { "data": { "version": "v1", "devise": "XAF", "plan": { "code": "pro", "nom": "Pro", "quota_minute": 120, "quota_jour": 5000, "quota_mois": 60000 }, "developpeur": { "nom": "John Doe" }, "horodatage": "2026-11-14T20:30:00+01:00" } } ``` ### 3. List Tournaments - **Method & Path**: `GET /v1/tournois` - **Description**: Paginated list of public e-sport tournaments with dynamic slot count and cashprize calculation. - **Query Parameters**: - `disponible` (integer, `0` or `1`): If `1`, returns only tournaments that still have open participant slots. - `statut` (string, optional): Filter by status: `ouvert`, `en_cours`, `termine`, `annule`. - `jeu_id` (integer, optional): Filter by game ID (e.g. Free Fire). - `per_page` (integer, optional): Items per page (default: `15`, maximum: `50`). - `page` (integer, optional): Page number for pagination. - **Sample Item**: ```json { "id": 42, "slug": "tournoi-free-fire-battle-royale-squad-42", "titre": "Tournoi Free Fire BR Squad", "jeu": { "id": 1, "nom": "Free Fire", "slug": "free-fire" }, "statut": "ouvert", "disponible": true, "places_totales": 48, "places_restantes": 14, "frais_inscription_xaf": 1000, "cashprize_estime_xaf": 33600, "date_debut": "2026-11-20T18:00:00+01:00", "organisateur": "Team Kamer E-sport", "url": "https://gamehub-arena.com/tournois/tournoi-free-fire-battle-royale-squad-42" } ``` ### 4. Tournament Statuses Catalog - **Method & Path**: `GET /v1/tournois/statuts` - **Description**: Returns all valid tournament statuses, machine keys, and human-readable French labels (`ouvert`, `en_cours`, `termine`, `annule`). ### 5. Tournament Details - **Method & Path**: `GET /v1/tournois/{id_ou_slug}` - **Description**: Full tournament information including format (Battle Royale, Bracket, Championnat), rules, cashprize distribution breakdown (70% top players / 20% platform / 10% organizer), check-in window, and schedule. ### 6. Tournament Participants - **Method & Path**: `GET /v1/tournois/{id_ou_slug}/participants` - **Description**: Public roster of confirmed participants (player pseudo, team name, registration timestamp). - **Security Invariant**: Secret game room IDs and passwords are NEVER exposed via this public API. ### 7. Games Catalog - **Method & Path**: `GET /v1/jeux` - **Description**: Supported competitive video games (Free Fire, Call of Duty Mobile, PUBG Mobile, Blood Strike, EA Sports FC) and associated rank divisions (Bronze, Argent, Or, Platine, Diamant, Héroïque, Grand Maître). ### 8. General Leaderboard - **Method & Path**: `GET /v1/classement` - **Description**: Official rankings of top competitive players sorted by accumulated tournament points, tournament victories, and win ratios. ### 9. Looking For Team (LFT) - **Method & Path**: `GET /v1/lft` - **Description**: Active public recruitments of players looking for teams or competitive squads looking for players (filtered by game, rank, and preferred role). ### 10. Community Announcements - **Method & Path**: `GET /v1/annonces` - **Description**: Official announcements, verified organizer notices, and community tournaments posted on GameHub Arena. --- ## Standard Error Codes All errors return JSON with the following structure: ```json { "message": "Description claire de l'erreur.", "code": "machine_readable_code", "request_id": "uuid-v4" } ``` Common error codes: - `missing_api_key` (`HTTP 401`): Header `Authorization: Bearer ` is missing. - `invalid_api_key` (`HTTP 401`): The provided API key does not exist or has been revoked. - `expired_api_key` (`HTTP 401`): The API key has expired. - `developer_inactive` (`HTTP 403`): The developer account is suspended or pending validation. - `no_api_plan` (`HTTP 403`): No active subscription plan is linked to this account. - `resource_not_found` (`HTTP 404`): The requested tournament, game, or entity does not exist. - `quota_exceeded` (`HTTP 429`): Rate limit exceeded. Check `Retry-After` header. --- ## Code Examples ### cURL ```bash curl -X GET "https://api.gamehub-arena.com/v1/tournois?disponible=1" \ -H "Authorization: Bearer ghk_live_votre_cle_ici" \ -H "Accept: application/json" ``` ### Python (requests) ```python import requests API_KEY = "ghk_live_votre_cle_ici" BASE_URL = "https://api.gamehub-arena.com/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Accept": "application/json", } response = requests.get(f"{BASE_URL}/tournois", headers=headers, params={"disponible": 1}) data = response.json() print("Tournois ouverts:", data) ``` ### JavaScript / TypeScript (fetch) ```javascript const API_KEY = "ghk_live_votre_cle_ici"; const response = await fetch("https://api.gamehub-arena.com/v1/tournois?disponible=1", { headers: { "Authorization": `Bearer ${API_KEY}`, "Accept": "application/json", }, }); const json = await response.json(); console.log(json.data); ``` ### PHP (cURL / Guzzle) ```php $client = new \GuzzleHttp\Client(); $response = $client->get('https://api.gamehub-arena.com/v1/tournois?disponible=1', [ 'headers' => [ 'Authorization' => 'Bearer ghk_live_votre_cle_ici', 'Accept' => 'application/json', ], ]); $data = json_decode($response->getBody(), true); ```