API v1Lecture seule (engagement)JSON

L'API Botillon

Catalogue public en lecture seule, et compteurs de votre bot protégés par clé API. Les endpoints publics ne demandent aucune clé ; votre clé projet donne accès aux statistiques de votre bot et à la mise à jour de sa fiche. Aucune action d'engagement (vote, like, avis) n'est possible via l'API.

Obtenir ma clé API Premier appel en 30 secondes

Démarrage rapide

Trois étapes : générez votre clé, copiez la commande, lisez la réponse.

1Rendez-vous sur botillon.fr/profil/api, sélectionnez votre bot, générez la clé.
2Chaque clé est liée à un seul bot et ne donne accès qu'à ses données.
3Appelez les endpoints /api/v1/me/* avec le header Authorization: Bearer. Les endpoints publics de lecture n'en ont pas besoin.

curl -H "Authorization: Bearer blp_00000000…" https://botillon.fr/api/v1/me

Authentification

Les routes /api/v1/me/* exigent votre clé (sans elle, ou si elle est révoquée : 401). Les endpoints publics de lecture (/api/v1/bots/*, /api/v1/users/*) n'en demandent aucune.

Format de clé

blp_ + 48 caractères hexadécimaux (52 caractères au total)

Les clés montrées dans cette page sont des exemples fictifs : la vôtre est affichée une seule fois à sa création. Régénérer une clé révoque immédiatement la précédente. Ne la commitez jamais : utilisez des variables d'environnement.

blp_000000000000…0000

Quota : 120 rafale · 240/min

Dépassement → 429 + header Retry-After

Endpoints publics

Lecture seule, sans clé d'API, limitée en débit par IP. Aucune action d'engagement (vote, like, avis) n'est possible via l'API, ni sans clé ni avec une clé projet. Toute méthode autre que GET sur ces chemins renvoie 405.

GET/api/v1/botsCatalogue des bots

Liste paginée des bots approuvés. Recherche plein texte, filtre par tag (tous les tags fournis doivent être présents), tri. Le champ serverCount vaut null quand le nombre de serveurs est inconnu : ne rien afficher dans ce cas.

Paramètre	Type	Description
limit	integer	Taille de page (défaut 24, max 50).
offset	integer	Décalage pour la pagination.
search	string	Recherche sur le nom et la tagline.
tag	string	Tag à filtrer (répétable, ou séparé par des virgules).
sort	"votes" \| "recent" \| "likes" \| "name" \| "random" \| "evaluated" \| "servers"	Tri (défaut "votes").
verified	"1"	Restreint aux bots évalués au seuil de vérification.

Requête

curl "https://botillon.fr/api/v1/bots?limit=24&sort=votes&tag=Mod%C3%A9ration"

Réponse 200

{
  "total": 75,
  "limit": 24,
  "offset": 0,
  "sort": "votes",
  "filters": { "search": null, "tags": ["Modération"], "verified": false },
  "bots": [
    {
      "discordId": "1383154920231796736",
      "slug": "chell",
      "name": "Chell",
      "tagline": "Le bot qu'il te faut !",
      "tags": ["Modération"],
      "votes": 219,
      "votesThisMonth": 35,
      "votes30d": 133,
      "likes": 20,
      "serverCount": 1990,
      "evaluationScore": 82,
      "evaluationCertified": true,
      "verified": true,
      "partner": false,
      "avatarUrl": "https://botillon.fr/api/img/…",
      "bannerUrl": null,
      "publicUrl": "https://botillon.fr/bots/1338"
    }
  ]
}

GET/api/v1/bots/{discordId}Fiche publique d'un bot

Fiche complète d'un bot, résolue par identifiant Discord OU slug. Mêmes données que la fiche publique et l'outil MCP get_bot (aucune donnée privée).

Paramètre	Type	Description
discordId*	string	Identifiant Discord (17–20 chiffres) ou slug public du bot.

Requête

curl https://botillon.fr/api/v1/bots/1383154920231796736

Réponse 200

{
  "bot": {
    "discordId": "1383154920231796736",
    "slug": "chell",
    "name": "Chell",
    "tagline": "Le bot qu'il te faut !",
    "description": "…",
    "descriptionFormat": "markdown",
    "tags": ["Modération"],
    "votes": 219,
    "votesThisMonth": 35,
    "votes30d": 133,
    "likes": 20,
    "serverCount": 1990,
    "prefix": "!",
    "verified": true,
    "partner": false,
    "inviteUrl": "https://discord.com/oauth2/authorize?…",
    "avatarUrl": "https://botillon.fr/api/img/…",
    "publicUrl": "https://botillon.fr/bots/1338",
    "evaluation": { "score": 82, "certified": true, "verified": true },
    "badges": []
  }
}

GET/api/v1/bots/{discordId}/statsStatistiques live d'un bot

Votes (total / mois / 30 j), likes (total / mois / 30 j), avis visibles, note des avis et nombre de serveurs. serverCount vaut null si l'application n'est pas répertoriée dans l'annuaire Discord : aucune valeur 0 n'est renvoyée.

Paramètre	Type	Description
discordId*	string	Identifiant Discord (17–20 chiffres) ou slug public du bot.

Requête

curl https://botillon.fr/api/v1/bots/1383154920231796736/stats

Réponse 200

{
  "discordId": "1383154920231796736",
  "slug": "chell",
  "name": "Chell",
  "votesTotal": 219,
  "votesMonth": 35,
  "votes30d": 133,
  "likesTotal": 20,
  "likesMonth": 8,
  "likes30d": 12,
  "commentsTotal": 11,
  "ratingAverage": 4.5,
  "ratingCount": 4,
  "serverCount": 1990,
  "serverCountUpdatedAt": "2026-10-08T00:51:25.407Z"
}

GET/api/v1/bots/{discordId}/communityCommunauté d'un bot

Communauté d'un bot : propriétaires, avis (note + 20 derniers avec auteur), likes total/mois/30 j, 20 derniers votants avec nom et avatar. Sans clé, rate-limitée par IP. Les profils privés sont anonymisés : identités masquées (pseudo, avatar, identifiant Discord) et, s'il s'agit d'un auteur d'avis, avis conservé de façon anonyme.

Paramètre	Type	Description
discordId*	string	Identifiant Discord (17–20 chiffres) ou slug public du bot.

Requête

curl https://botillon.fr/api/v1/bots/1383154920231796736/community

Réponse 200

{
  "discordId": "1383154920231796736",
  "slug": "chell",
  "name": "Chell",
  "owners": [
    { "discordId": "1365989943012229221", "name": "Joynix", "avatarUrl": "https://botillon.fr/api/img/…" }
  ],
  "likes": { "total": 20, "month": 8, "last30d": 12 },
  "reviews": {
    "count": 11,
    "average": 4.5,
    "recent": [
      {
        "rating": 5,
        "content": "Excellent bot !",
        "createdAt": "2026-10-12T09:14:02.000Z",
        "author": { "discordId": "1250128123337641989", "name": "Lya", "avatarUrl": "https://botillon.fr/api/img/…" }
      }
    ]
  },
  "recentVotes": [
    {
      "createdAt": "2026-10-14T18:03:41.000Z",
      "weight": 1,
      "voter": { "discordId": "1250128123337641989", "name": "Lya", "avatarUrl": "https://botillon.fr/api/img/…" }
    }
  ],
  "generatedAt": "2026-10-15T16:20:00.000Z"
}

GET/api/v1/users/{discordId}Profil public d'un utilisateur

Profil public d'un utilisateur : nom, avatar, bio, badges, bots possédés et statistiques d'engagement. Jamais d'email, de token ni de donnée privée. Un profil privé (public_profile_enabled=false) renvoie 404, comme sur le site.

Paramètre	Type	Description
discordId*	string	Identifiant Discord de l'utilisateur (17–20 chiffres).

Requête

curl https://botillon.fr/api/v1/users/1365989943012229221

Réponse 200

{
  "user": {
    "discordId": "1365989943012229221",
    "username": "joynix28",
    "displayName": "Joynix",
    "globalName": "Joynix",
    "avatarUrl": "https://botillon.fr/api/img/…",
    "bannerUrl": null,
    "bio": null,
    "websiteUrl": null,
    "role": "user",
    "badges": [],
    "createdAt": "2026-08-22T00:38:44.273Z",
    "bots": [],
    "stats": { "botsOwned": 0, "votesCast": 5, "commentsPosted": 1 }
  }
}

Lecture seule. Aucune action d'engagement (vote, like, avis) n'est possible via l'API, quelle que soit l'authentification. Un POST, PUT, PATCH ou DELETE sur ces chemins renvoie 405 method_not_allowed. Le vote, le like et l'avis passent uniquement par le site ou le bot Discord.

Votre bot

Identité du projet lié à la clé et compteurs temps réel.

GET/api/v1/meInfos & compteurs

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me

Réponse 200

{
  "bot": {
    "id": "1383154920231796736",
    "name": "Chell",
    "avatar_url": "https://cdn.discordapp.com/avatars/…",
    "tagline": "Le bot qu'il te faut !",
    "status": "approved"
  },
  "counts": {
    "votes_total": 8,
    "votes_active_12h": 2,
    "likes": 3,
    "comments": 3
  },
  "vote_window_hours": 12
}

Mettre à jour votre fiche

Modifiez partiellement les métadonnées de votre bot (description, tagline, URLs…). Les champs non fournis ne sont pas touchés. Si la description change, la fiche est soumise à revue staff.

PATCH/api/v1/meUpdate partiel

Paramètre	Type	Description
tagline	string	Sous-titre (10 à 200 car.).
description	string	Description complète (max 4000 car.). Soumise à revue si modifiée.
invite_url	string	Lien d'invitation Discord.
support_url	string	Lien du serveur support.
website_url	string	Site web du bot.
github_url	string	Dépôt GitHub.
tiktok_url	string	Profil TikTok.
youtube_url	string	Chaîne YouTube.
prefix	string	Préfixe de commandes (max 20 car.).
prefix_multi	boolean	Préfixes multiples.
user_installable	boolean	Installable par l'utilisateur.
has_premium	boolean	Propose un premium.
web_dashboard	boolean	Dashboard web disponible.
tags	string[]	Tags du bot (max 20 parmi les 23 tags valides). Tags invalides ignorés.
discord_banner_url	string	URL de la bannière du bot.

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  -X PATCH
  -H "Content-Type: application/json"
  -d '{"description": "Nouvelle description.", "tags": ["Utilitaires", "IA"], "has_premium": true}'
  https://botillon.fr/api/v1/me

Réponse 200

{
  "ok": true,
  "updated": ["description", "tags", "has_premium"],
  "note": "Description modifiée — soumise à revue staff."
}

Seuls les champs listés sont acceptés. Un champ absent n'est pas modifié ; une chaîne vide efface le champ texte correspondant (NULL). La tagline ne peut jamais être vide. Chaque PATCH crée un log d'audit dans bot_audit_logs avec l'action api.patch.

Commandes slash

Gérez la liste des commandes slash affichée sur la fiche de votre bot. Corps accepté : application/json (tableau direct) ou multipart/form-data (champ file avec un commands.json, ou champ commands en texte).

GET/api/v1/me/commandsLire la liste

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/commands

Réponse 200

{
  "commands": [
    { "name": "ping", "description": "Teste la latence" },
    { "name": "help", "description": "Aide", "options": [ /* … */ ] }
  ]
}

PUT/api/v1/me/commandsRemplacer toute la liste

Paramètre	Type	Description
commands[]*	Array<object>	Tableau complet des commandes (max 300, 2 Mo). Un PUT avec une liste vide retire les commandes.

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  -X PUT
  -H "Content-Type: application/json"
  -d '[{"name": "ping", "description": "Teste la latence"}]'
  https://botillon.fr/api/v1/me/commands

Réponse 200

{
  "ok": true,
  "count": 1
}

Variante

Multipart (fichier exporté) : curl -H "Authorization: Bearer blp_00000000…" \
  -X PUT
  -F "[email protected]"
  https://botillon.fr/api/v1/me/commands

PATCH/api/v1/me/commandsFusion partielle (par name)

Paramètre	Type	Description
commands[]*	Array<object>	Commandes à insérer ou remplacer. Le match se fait sur le champ name : une commande existante de même nom est remplacée, une nouvelle est ajoutée, les autres restent intactes.

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  -X PATCH
  -H "Content-Type: application/json"
  -d '[{"name": "ping", "description": "Nouvelle description"}]'
  https://botillon.fr/api/v1/me/commands

Réponse 200

{
  "ok": true,
  "updated": 1,
  "added": 0,
  "total": 24
}

DELETE/api/v1/me/commandsRetirer la liste

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  -X DELETE
  https://botillon.fr/api/v1/me/commands

Réponse 200

{
  "ok": true,
  "count": 0
}

Validation stricte : max 300 commandes, options bornées, aucun code exécuté. Les modifications sont journalisées dans bot_audit_logs(actions api.put_commands, api.patch_commands,api.delete_commands) et revalident immédiatement la fiche publique.

Vérifier un utilisateur

L'endpoint phare pour vos récompenses : un seul appel pour savoir si un utilisateur a voté ces 12 dernières heures, s'il a laissé un avis ou liké votre bot.

GET/api/v1/me/check/{user_id}Tout-en-un par utilisateur

Paramètre	Type	Description
user_id*	string	Identifiant Discord de l'utilisateur (17 à 20 chiffres).

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/check/1365989943012229221

Réponse 200

{
  "user_id": "1365989943012229221",
  "registered_on_site": true,
  "voted_last_12h": true,
  "last_vote_at": "2026-08-22T16:12:12.376Z",
  "next_vote_available_at": "2026-08-23T04:12:12.376Z",
  "has_reviewed": true,
  "review": {
    "rating": 5,
    "content": "test",
    "hidden_by_staff": false,
    "created_at": "2026-08-22T00:38:44.273Z",
    "updated_at": "2026-08-22T00:38:44.273Z"
  },
  "has_liked": true,
  "liked_at": "2026-08-22T16:13:59.342Z"
}

Utilisateur jamais inscrit sur le site ? La réponse reste 200 avecregistered_on_site: false et tous les flags àfalse — pas besoin de gérer un cas d'erreur.

GET/api/v1/me/rankClassement du bot sur la plateforme

Rang en votes, likes, serveurs et avis parmi les bots approuvés, percentile (top X %), moyennes de la plateforme et rang par tag.

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/rank

Réponse 200

{
  "total_approved": 75,
  "ranks": { "votes": 3, "likes": 5, "servers": 2, "comments": 7 },
  "percentiles": { "votes": 96, "likes": 93.3, "servers": 97.3, "comments": 90.7 },
  "platform_averages": { "votes": 12.4, "likes": 4.1 },
  "tags": [ { "tag": "Modération", "rank": 2, "bots_with_tag": 14 } ]
}

GET/api/v1/me/statsStatistiques temporelles du bot

Séries quotidiennes (votes, likes, avis, visites de la fiche) sur N jours + totaux 24 h / 7 j / 30 j et votes actifs (12 h).

Paramètre	Type	Description
days	integer	Nombre de jours de séries (défaut 30, max 90).

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/stats?days=7

Réponse 200

{
  "days": 7,
  "daily": {
    "votes": [ { "day": "2026-08-26", "count": 3 } ],
    "likes": [ { "day": "2026-08-26", "count": 1 } ],
    "comments": [],
    "visits": [ { "day": "2026-08-26", "count": 42 } ]
  },
  "totals": { "votes_24h": 2, "votes_7d": 5, "votes_30d": 9, "active_votes": 1,
              "likes_24h": 0, "likes_7d": 1, "likes_30d": 2,
              "comments_24h": 0, "comments_7d": 1, "comments_30d": 1,
              "visits_24h": 15, "visits_7d": 120, "visits_30d": 340 }
}

Historiques complets

Listes paginées du plus récent au plus ancien. Passé ET présent : un vote expiré reste visible avec active: false.

GET/api/v1/me/votesHistorique des votes

Paramètre	Type	Description
limit	integer	Taille de page (défaut 50, max 100).
offset	integer	Décalage pour la pagination.
active	"1"	Limite aux votes des 12 dernières heures (?active=1).

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/votes?limit=2&active=1

Réponse 200

{
  "total": 8,
  "limit": 2,
  "offset": 0,
  "items": [
    { "user_id": "1365989943012229221", "voted_at": "2026-08-22T16:12:12.376Z",
      "expires_at": "2026-08-23T04:12:12.376Z", "active": true }
  ]
}

GET/api/v1/me/likesHistorique des likes

Paramètre	Type	Description
limit	integer	Taille de page (défaut 50, max 100).
offset	integer	Décalage pour la pagination.

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/likes?limit=2

Réponse 200

{
  "total": 3,
  "items": [
    { "user_id": "1365989943012229221", "username": "joynix28",
      "liked_at": "2026-08-22T16:13:59.342Z" }
  ]
}

GET/api/v1/me/commentsHistorique des avis

Paramètre	Type	Description
limit	integer	Taille de page (défaut 50, max 100).
offset	integer	Décalage pour la pagination.
hidden	"1" \| "0"	Filtre les avis masqués par la modération (1) ou visibles (0).

Requête

curl -H "Authorization: Bearer blp_00000000…" \
  https://botillon.fr/api/v1/me/comments?limit=2&hidden=0

Réponse 200

{
  "total": 3,
  "items": [
    { "user_id": "1250128123337641989", "username": "user12501",
      "rating": 5, "content": "Excellent bot !", "hidden_by_staff": false,
      "created_at": "2026-08-22T01:01:19.427Z",
      "updated_at": "2026-08-22T01:01:19.427Z" }
  ]
}

Serveur MCP (assistants IA)

Botillon expose ses données publiques via un serveur MCP (Model Context Protocol) distant : lecture seule, gratuit, sans clé d'API. Idéal pour brancher Claude, Cursor, ChatGPT ou tout agent compatible MCP sur le catalogue.

URL

https://botillon.fr/api/mcp

Transport

Streamable HTTP · JSON-RPC (SSE sur ?transport=sse)

Accès

Public, sans authentification · rate-limit par IP

Le serveur est stateless : aucune session à gérer, chaque requête POST contient son message JSON-RPC. Les méthodes initialize, tools/list, tools/call, resources/list, resources/read et prompts/list sont prises en charge. Aucune écriture, aucun vote, aucun like : uniquement de la consultation.

Pour la prise en main pas à pas (configuration Cursor, Claude Desktop, curl) et la liste complète des outils, consultez la page dédiée Serveur MCP →

Outils exposés

Outil	Description
search_bots	Recherche par texte, tags, tri et pagination dans le catalogue approuvé.
get_bot	Fiche complète d’un bot (identifiant Discord ou slug) : stats, tags, liens, badges, note.
top_bots	Classement par votes, serveurs, likes, nouveauté ou note d’évaluation.
compare_bots	Comparaison de deux bots (votes, serveurs, note /100, tags communs, fonctionnalités).
get_evaluation	Note d’évaluation /100 et détail des critères d’un bot.
list_similar_bots	Bots proches d’un bot donné (tags partagés).
list_evaluated_bots	Derniers bots évalués avec leur note et le badge Certifié.
list_tags	Tags officiels et nombre de bots approuvés par tag.
list_categories	Tags les plus fournis, utilisables comme catégories.
list_badges	Badges publics de Botillon et leur signification.
list_rules	Critères de listing des bots (interdits, prérequis, conséquences).
site_stats	Chiffres publics : bots, votes, utilisateurs, serveurs, top tags.
list_api_endpoints	Endpoints publics de l’API (méthode, chemin, paramètres, réponse).
list_help_topics	Sujets d’aide publics (règles, guides, bonnes pratiques).
get_help_topic	Contenu complet d’un sujet d’aide (par slug).
get_site_presentation	Présentation du site : à qui ça s’adresse, engagements, soumission, vote, évaluation.
get_why_botillon	Argumentaire /pourquoi-botillon : comparatif, fonctionnalités, FAQ.
get_discord_bot	Documentation du bot Discord Botillon : commandes, récompenses de rôle, rappels, prérequis.
get_page_markdown	N’importe quelle page publique en Markdown (frontmatter + contenu).
list_pages	Pages publiques importantes avec URL et URL Markdown.
list_partners	Services et serveurs partenaires officiels.
list_recommended_bots	Bots mis en avant (tirage au sort, Croissants, têtes d’affiche).
list_integrations	Intégrations publiques approuvées et scopes d’événements.
list_bot_posts	Articles publics d’un bot : articles natifs + flux externe (type + URL).
list_blog_posts	Flux du hub /blog : articles de bots, flux externes et actualités du site.
list_news	Actualités publiées de l’équipe (recherche, tag, pagination).
search_news	Recherche plein texte dans les actualités publiées.
get_news	Contenu complet d’une actualité publiée (par slug).
get_terms	CGU de Botillon, en sections structurées.
get_privacy	Politique de confidentialité, en sections structurées.
get_legal_notice	Mentions légales, en sections structurées.

Ressources MCP : botillon://llms.txt, botillon://regles/bots, botillon://badges, botillon://tags, botillon://stats, botillon://api-docs, botillon://aide, botillon://presentation, botillon://pourquoi-botillon, botillon://bot-discord, botillon://pages, botillon://partenaires, botillon://news, botillon://news/{slug}, botillon://blog, botillon://legal/cgu, botillon://legal/confidentialite, botillon://legal/mentions-legales.

Se connecter

Cursor / Claude Code / tout client HTTP MCP — ajoutez un serveur distant avec l'URL ci-dessus :

{
  "mcpServers": {
    "botillon": {
      "type": "streamable-http",
      "url": "https://botillon.fr/api/mcp"
    }
  }
}

Claude Desktop — passez par le pont mcp-remote :

{
  "mcpServers": {
    "botillon": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://botillon.fr/api/mcp"]
    }
  }
}

Test manuel (curl) — vérifiez l'initialisation :

curl -s https://botillon.fr/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Codes erreur

Réponses JSON uniformes : { "error": "code" }.

Statut	Code	Quand ?
400	invalid_bot_id	Identifiant de bot numérique mal formé (17–20 chiffres attendus).
400	invalid_user_id	L'identifiant Discord n'a pas 17–20 chiffres.
401	api_key_required	Header Authorization absent ou vide.
401	invalid_api_key	Clé fournie mais inconnue, révoquée ou bloquée.
403	ip_banned	Adresse IP bannie par l'équipe.
404	bot_not_found	Bot inconnu ou non approuvé (routes publiques comme clé projet).
404	user_not_found	Utilisateur inconnu, ou profil rendu privé par son titulaire.
405	method_not_allowed	Méthode autre que GET sur un endpoint public (lecture seule).
429	rate_limited	Quota dépassé — respectez Retry-After (secondes).

API en lecture seule pour l'engagement : aucun vote, like ou avis ne peut être créé via l'API, ni sans clé ni avec une clé projet. La clé ne sert qu'à lire les compteurs de son bot et à mettre à jour ses métadonnées. Tout abus entraîne la révocation de la clé.

Ma clé API