Portail développeurs Pilotariak

Démarrage rapide

L’API GraphQL ne demande ni inscription ni clé d’API. Choisissez une ligue et envoyez une requête :

curl -s -X POST https://frontis-gateway.pilotariak.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Pilotariak-League: lcapb" \
  -d '{"query":"{ clubs { id name } }"}'

API GraphQL Frontis

• Endpoint : https://frontis-gateway.pilotariak.com/graphql (HTTP POST, corps JSON)
• Authentification : aucune — l’API est publique et en lecture seule
• En-tête obligatoire : X-Pilotariak-League = lcapb (Côte d’Argent), lidfpb (Île-de-France) ou ctpb (Comité Territorial)
• Requêtes : clubs, club(id), competitions, competition(id), categories, category(id), specialties, specialty(id), results(competitionId, specialtyId, categoryId, phase), result(id), version
• Schéma : l’introspection GraphQL est activée, tout client ou générateur de code GraphQL peut le charger
• Référence complète : skill graphql-api · code source sur GitHub

Serveur MCP Azkena

Azkena expose les mêmes données sous forme d’outils Model Context Protocol afin que des assistants comme Claude, Cursor ou Codex puissent les interroger en langage naturel. Endpoint : https://mcp.pilotariak.com/mcp (Streamable HTTP, protocole 2026-07-28).

Outils : list_competitions, list_clubs, list_categories, list_specialties, list_results. Chaque outil prend un argument league.

{
  "mcpServers": {
    "pilotariak": {
      "type": "http",
      "url": "https://mcp.pilotariak.com/mcp"
    }
  }
}

Authentification

L’API GraphQL et tous les documents de découverte de pilotariak.com sont publics. Le serveur MCP exige un jeton d’accès OAuth 2.1 : le client s’enregistre dynamiquement, une personne autorise l’accès sur l’écran de consentement, puis le client échange le code avec PKCE (S256). Une requête non authentifiée reçoit un 401 avec un en-tête WWW-Authenticate pointant vers les métadonnées de la ressource protégée.

Le guide pas à pas pour les agents se trouve dans auth.md. Métadonnées : ressource protégée (RFC 9728) · serveur d’autorisation (RFC 8414).

Erreurs

Les erreurs GraphQL suivent la spécification GraphQL : la réponse contient un tableau errors, chaque entrée avec un message lisible et un code machine extensions.code (BAD_REQUEST, GRAPHQL_VALIDATION_FAILED, …). Le serveur MCP renvoie des erreurs JSON comme {"error":"invalid_token"} avec les codes d’erreur OAuth standard.

{
  "errors": [{
    "message": "Missing X-Pilotariak-League header",
    "path": ["clubs"],
    "extensions": { "code": "BAD_REQUEST", "serviceName": "clubs" }
  }],
  "data": null
}

Limites, versions et environnements

• Azkena autorise 60 requêtes par minute et par adresse IP ; au-delà il répond 429.
• Frontis n’a pas de quota publié — mettez les réponses en cache et évitez les sondages trop fréquents.
• Vérifiez la version déployée de la passerelle avec la requête { version } ; les changements sont listés dans les releases GitHub de chaque projet.
• Il n’y a pas de bac à sable séparé : toutes les interfaces sont en lecture seule, aucun appel ne peut modifier les données.

Découverte automatisée

• llms.txt — présentation du site pour les modèles de langage (index développeurs : /developers/llms.txt)
• Catalogue d’API (RFC 9727) · description OpenAPI des documents de découverte
• Catalogue Agentic Resource Discovery · carte du serveur MCP · carte d’agent A2A
• Index des skills d’agent — fichiers SKILL.md pour l’API GraphQL, le serveur MCP, les projets et le contexte sportif
• Chaque page existe en markdown : ajoutez .md (par exemple /fr/developers.md) ou envoyez Accept: text/markdown

Code source et SDK

Tout est sous licence Apache-2.0 sur github.com/Pilotariak, y compris ce site (Pilotariak/website, avec un AGENTS.md pour les agents de code). Il n’existe pas de SDK dédié : n’importe quelle bibliothèque cliente GraphQL ou MCP fonctionne. Issues et pull requests bienvenues.