API développeurs

Accédez aux données Lorcanahunter (tournois, résultats, decklists, joueurs) depuis votre application via une API OAuth2.

Créer une application

Comment ça marche

Créez une application depuis votre espace développeur en décrivant votre projet et les données dont vous avez besoin.
Notre équipe examine la demande et accepte ou refuse, avec les scopes accordés.
Une fois l'application approuvée, générez votre client secret (affiché une seule fois).
Échangez client_id + client_secret contre un access token (valable 24 h) et un refresh token (valable 90 jours).

1. Obtenir un token

curl -X POST https://lorcanahunter.com/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

{
  "access_token": "lh_at_…",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "lh_rt_…",
  "refresh_token_expires_in": 7776000,
  "scope": "tournaments:read decks:read"
}

2. Appeler l'API

curl https://lorcanahunter.com/api/v1/tournaments?eventType=ccq&limit=10 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Renouveler le token

curl -X POST https://lorcanahunter.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

Chaque refresh renvoie une nouvelle paire et invalide l'ancienne. Réutiliser un refresh token déjà consommé révoque tous les tokens de l'application.

Endpoints

Endpoint	Scope	Description
GET /api/v1/tournaments	tournaments:read	Liste paginée des tournois (filtres : search, eventType, country, format, dateFrom, dateTo, page, limit ≤ 100).
GET /api/v1/tournaments/{id}	tournaments:read	Détail d'un tournoi et classement complet.
GET /api/v1/tournaments/{id}/decklists	decks:read	Decklists complètes d'un tournoi, par classement (si elles sont publiques ; page, limit ≤ 100).
GET /api/v1/decks/{id}	decks:read	Une decklist par son id, avec son tournoi (404 si elle est privée).
GET /api/v1/archetypes	decks:read	Répartition du méta par archétype (days : 15, 30, 60, 90 ; format : core, infinity).
GET /api/v1/players/{id}	players:read	Profil d'un joueur, bilan et historique des participations.

Les erreurs sont renvoyées en JSON au format { error, error_description } : 401 invalid_token, 403 insufficient_scope, 404 not_found.

Limites d'utilisation

60 requêtes par minute et 10 000 par jour et par application ; 20 requêtes par minute et par IP sur /api/oauth/token. Chaque réponse contient les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Au-delà : 429 rate_limited avec Retry-After.

Les joueurs ayant demandé le masquage de leur profil sont anonymisés (id et nom à null, hidden: true) et leur profil renvoie 404.

Référence complète de l'API OpenAPI (YAML)