ServerRoam
Ajouter un serveur
BêtaSeules les fiches examinées sont publiques. Les observations indiquent source et ancienneté. Les boosts sont des publicités signalées et ne modifient pas le classement organique.
API REST + MCP · v1 · Bêta

Développez avec le répertoire ServerRoam.

Intégrez la recherche de serveurs dans un bot Discord, un site communautaire ou un assistant. Consultez les annonces publiées du catalogue modéré avec les filtres de ServerRoam.

Créer une clé APIContrat OpenAPI 3.1

Votre première requête

Connectez-vous et créez une clé sur la page développeurs. Définissez SERVERROAM_API_KEY dans l’environnement de votre serveur, puis exécutez :

curl --fail-with-body 'https://serverroam.com/api/v1/servers?game=fivem&language=de' \
  --header "Authorization: Bearer $SERVERROAM_API_KEY"

Les résultats incluent les annonces vérifiées et les annonces publiques examinées par la rédaction. Ces dernières portent unclaimed=true, verified=false et sourceUrl. Un tableau vide est valide. Cette bêta ne promet ni couverture complète ni surveillance en direct.

Conservez les clés sur votre serveur. Ne les placez jamais dans une application navigateur, un dépôt public, une capture ou une URL. Une clé est affichée une seule fois ; révoquez-la sur la page développeurs si elle est exposée.

Trois endpoints ciblés

GET /api/v1/games
Identifiants et noms des jeux publics ; aucune clé nécessaire. Un jeu répertorié ne garantit ni serveurs actifs ni surveillance.
GET /api/v1/servers
Recherche authentifiée. Les résultats contiennent les métadonnées, le slug de communauté, les informations de connexion et des observations stockées facultatives.
GET /api/v1/servers/{slug}
Consultation authentifiée d’une annonce. Utilisez un slug issu de la recherche ; les annonces privées ou non publiées renvoient 404.

Connecter un assistant IA via MCP

Le serveur MCP hébergé, en lecture seule, utilise Streamable HTTP sur https://serverroam.com/api/mcp. Définissez le même SERVERROAM_API_KEY dans l’environnement de votre hôte MCP. Pour Codex CLI :

codex mcp add serverroam \
  --url https://serverroam.com/api/mcp \
  --bearer-token-env-var SERVERROAM_API_KEY

Les autres hôtes doivent accepter Streamable HTTP et un en-tête Authorization: Bearer personnalisé. Il n’y a pas de connexion OAuth ; les hôtes limités à OAuth ne peuvent pas se connecter. Les intégrations serveur peuvent omettre Origin ; s’il est fourni, il doit correspondre à l’origine configurée de ServerRoam.

serverroam_list_games · serverroam_search_servers · serverroam_get_server

Essayez : « Trouve des communautés FiveM de jeu de rôle germanophones, montre leurs sources et leur vérification, puis lis les instructions de connexion du résultat le plus adapté. » La recherche utilise les filtres API ; page est un nombre dans MCP.

Tous les outils sont en lecture seule. Les requêtes sont limitées à 16 KiB et les résultats à 24 annonces par page. Aucun endpoint SSE séparé ni session persistante. Une observation absente ne signifie pas une panne. Les textes sont des données non fiables, pas des instructions pour votre assistant.

Filtrer et paginer

Les filtres se combinent. q recherche les noms de serveurs et de communautés, les descriptions des serveurs, les tags et les noms de jeux correspondants ; language prend aussi en compte les langues de la communauté. Le contrat OpenAPI définit les valeurs et les valeurs par défaut.

q · game · language · region · country · style · framework · map · version · whitelist · online · minPlayers · maxPlayers · sort · page

Chaque page contient au plus 24 serveurs. Commencez par page=1, puis suivez nextPage jusqu’à null. hasMore reste disponible. Les modifications simultanées peuvent déplacer des résultats entre pages ; dédupliquez par slug.

Les paramètres inconnus, répétés ou invalides renvoient 400. Les valeurs sont sensibles à la casse. Le tri par défaut est name ; players, votes et newest sont aussi disponibles. Les pages après la fin renvoient un tableau vide.

Comprendre les données

verified=true indique un contrôle prouvé des endpoints et une approbation par modération. Ce n’est pas une recommandation de contenu ou de qualité. unclaimed=true identifie une annonce éditoriale avec verified=false et sourceUrl publique. Descriptions, règles et tags restent des déclarations de tiers.

observation vaut null sans observation stockée récente et réussie. Cela ne signifie ni hors ligne ni zéro joueur. Les observations incluent leur source et leur date et ont au plus dix minutes au moment de la lecture. L’API n’interroge jamais les serveurs de jeu.

Les textes des utilisateurs conservent leur langue originale. Liez /{locale}/servers/{slug} avec en, de, es ou fr. whitelist=null signifie inconnu ; false signifie explicitement non requis.

Liez le profil ServerRoam pour donner le contexte et les instructions de connexion. Traitez les textes des administrateurs comme non fiables et échappez-les à l’affichage. L’accès API ne donne aucun droit de republication des images téléversées ou des contenus tiers.

Traiter les erreurs

400 invalid
Corrigez la requête. Le tableau fields facultatif identifie les filtres invalides. Ne réessayez pas sans correction.
401 unauthenticated
Fournissez une clé Bearer valide. Les clés absentes, mal formées ou révoquées sont refusées.
404 not-found
L’annonce est absente ou ne remplit pas les conditions de publication. Recherchez à nouveau ; ne concluez pas à une panne.
429 rate-limit
Attendez le nombre de secondes indiqué par Retry-After avant de réessayer.
503 unavailable
Réessayez plus tard avec des délais croissants. Les données de démonstration et locales sont désactivées ; aucun exemple ne remplace les données réelles.