API des outils et serveur MCP
Tous les outils de Bluesky.bot s’utilisent aussi gratuitement depuis du code et depuis des agents IA : comme API REST, et comme outils de notre serveur MCP. Sans inscription ni clé : appelez-les. Chaque réponse renvoie vers la page de l’outil.
Endpoints
| Outil | API | Outil MCP |
|---|---|---|
| Trouver un DID | GET /api/v1/tools/did-finder?handle=… | find_did |
| Trouver un handle | GET /api/v1/tools/handle-finder?did=… | find_handle |
| Whois | GET /api/v1/tools/whois?actor=… | whois_lookup |
| Âge d’un compte | GET /api/v1/tools/account-age?actor=… | check_account_age |
| Convertisseur d’AT URI | GET /api/v1/tools/at-uri-converter?uri=… | convert_at_uri |
| Décodeur de TID | GET /api/v1/tools/tid-decoder?tid=… | decode_tid |
| Compteur de caractères | GET /api/v1/tools/character-counter?text=…&numbered=true | count_post_characters |
| Générateur de facettes de texte enrichi | GET /api/v1/tools/facet-builder?text=…&langs=en | build_post_facets |
| Vérificateur de handle de domaine | GET /api/v1/tools/custom-handle-checker?domain=…&expected=… | check_custom_handle |
| Vérificateur de disponibilité de handle | GET /api/v1/tools/handle-availability?name=… | check_handle_availability |
| Historique PLC | GET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=false | plc_history |
| Analyseur de starter packs | GET /api/v1/tools/starter-pack-analyser?q=… | analyse_starter_pack |
| Lecteur de posts et de fils | GET /api/v1/tools/post-viewer?post=…&embed=false | view_bluesky_post |
| Inspecteur de flux | GET /api/v1/tools/feed-inspector?feed=…&check=false | inspect_bluesky_feed |
L’URL de base est https://bluesky.bot/api/v1. Les paramètres et la
réponse de chaque outil figurent dans la référence de l’API et
dans le document OpenAPI, /api/v1/openapi.json.
Une réponse a toujours la même forme : le slug de l’outil, l’URL de sa page,
et son result.
{
"tool": "character-counter",
"url": "https://bluesky.bot/tools/character-counter",
"result": { "graphemes": 16, "bytes": 19, "over": false, "parts": [] }
}Limites
- Gratuit et anonyme : 60 appels par minute et 2 000 par jour par adresse IP. Un outil qui envoie plusieurs requêtes en coulisses compte pour plus d’un appel ; la référence de l’API le précise.
- Avec un jeton d’API : 10 fois plus, compté par compte. Les créateurs
qui ont au moins un bot sur Bluesky.bot en créent un dans le tableau de
bord, sous Paramètres → Accès API et CLI ; un jeton de
l’outil en ligne de commande fonctionne aussi. Envoyez-le
dans
Authorization: Bearer <token>. Un jeton dure 30 jours ; gardez-le hors du code public. - Ce que peut faire un jeton du tableau de bord : appeler les outils,
rien d’autre. Il a la portée
tools: il ne peut ni gérer vos bots, ni réserver ou libérer un handle, ni utiliser les routes/api/v1/me/*de la CLI, qui lui répondent401. - Au-delà d’une limite, la réponse est
429avec un en-têteRetry-After, en secondes. - Un jeton inconnu, expiré ou révoqué reçoit
401: retirez l’en-tête pour appeler de façon anonyme.
Les erreurs gardent la forme habituelle de l’API,
{ "error": { "code", "message" } }, avec bad_request (et le
parameter), unauthorized, not_found, rate_limited et
upstream_error (le service qu’interroge un outil n’a pas répondu). Les
réponses portent des en-têtes CORS, pour qu’une page web puisse les
appeler, et un en-tête de cache : un calcul pur, comme le compteur, est mis
en cache pour de bon.
Exemples
Avec curl, qui encode le texte pour vous :
curl -G "https://bluesky.bot/api/v1/tools/character-counter" \
--data-urlencode "text=Hello Bluesky! 👋"En JavaScript ou TypeScript (Node.js 18 ou plus, Deno, Bun ou un navigateur) :
// tools-api.ts : compte un post avec l’API gratuite des outils.
// Sans clé.
const url = new URL("https://bluesky.bot/api/v1/tools/character-counter");
url.searchParams.set("text", "Hello Bluesky! 👋");
// Un jeton d’API créé dans les paramètres du tableau de bord
// multiplie les limites par dix.
const token = process.env.BSBOT_TOKEN;
const response = await fetch(url, {
headers: token ? { Authorization: `Bearer ${token}` } : {},
});
if (response.status === 429) {
const wait = response.headers.get("Retry-After");
throw new Error(`Rate limited: retry in ${wait} s.`);
}
const answer = (await response.json()) as {
url: string;
result: { graphemes: number; graphemesLeft: number; over: boolean };
};
const { graphemes, graphemesLeft } = answer.result;
console.log(`${graphemes} graphemes, ${graphemesLeft} left. ${answer.url}`);
// Fait de ce fichier un module ES, ce qu’exige le await de premier niveau.
export {};En Python, avec requests :
# tools_api.py : compte un post avec l’API gratuite des outils.
# Sans clé.
import os
import requests
# Un jeton d’API créé dans les paramètres du tableau de bord
# multiplie les limites par dix.
token = os.environ.get("BSBOT_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}
response = requests.get(
"https://bluesky.bot/api/v1/tools/character-counter",
params={"text": "Hello Bluesky! 👋"},
headers=headers,
timeout=10,
)
if response.status_code == 429:
wait = response.headers["Retry-After"]
raise SystemExit(f"Rate limited: retry in {wait} s.")
response.raise_for_status()
answer = response.json()
result = answer["result"]
print(f"{result['graphemes']} graphemes, {result['graphemesLeft']} left. {answer['url']}")Le texte voyage dans l’adresse d’une requête GET, que les serveurs coupent
vers 8 Ko. Pour un texte long, utilisez le serveur MCP : il envoie l’entrée
dans le corps de la requête.
Serveur MCP
Le serveur MCP liste les mêmes outils, avec leurs schémas d’entrée et de
sortie, pour les agents IA et les éditeurs : https://bluesky.bot/api/mcp
(Streamable HTTP, sans session). Tous les outils sont en lecture seule. Les
mêmes limites s’appliquent ; un jeton dans l’en-tête Authorization les
relève.
Connexion en un clic
Plutôt vous connecter que coller un jeton ? Ajoutez
https://bluesky.bot/api/mcp/connect à la place. Votre app d’IA ouvre une
page de Bluesky.bot : connectez-vous avec votre compte Bluesky (nous ne
demandons jamais votre mot de passe), vérifiez le nom de l’app et l’adresse
vers laquelle elle vous renvoie, et autorisez. L’app reçoit alors son propre
jeton, et le renouvelle seule.
Dans Claude Code :
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connectDans Claude Desktop ou sur claude.ai, ajoutez un connecteur personnalisé
avec cette URL et choisissez Connecter. Dans Cursor ou VS Code,
mettez-la comme url de la configuration ci-dessous, puis connectez-vous
quand l’éditeur le demande.
- L’app reçoit la portée
tools: les outils, avec les limites plus hautes de votre compte si vous avez un bot sur Bluesky.bot. Elle ne peut ni publier, ni gérer vos bots, ni réserver un handle. - Une app autorisée est mémorisée. Révoquez-la quand vous voulez dans Paramètres → Apps connectées ; Se déconnecter partout et la suppression de votre compte révoquent toutes les apps.
- Seules quelques apps bien connues sont marquées Vérifiée. Pour les autres, vérifiez l’adresse vers laquelle elles vous renvoient avant d’autoriser.
https://bluesky.bot/api/mcpfonctionne toujours sans connexion.
Dans Claude Code :
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcpDans Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json, avec
"servers" au lieu de "mcpServers") et la plupart des autres clients :
{
"mcpServers": {
"bluesky-bot": { "url": "https://bluesky.bot/api/mcp" }
}
}Dans Claude Desktop ou sur claude.ai, ajoutez-le comme connecteur
personnalisé avec la même URL. Avec un jeton, ajoutez un en-tête :
--header "Authorization: Bearer $BSBOT_TOKEN" dans Claude Code, ou
"headers": { "Authorization": "Bearer …" } à côté de url dans une
configuration JSON. Ne versionnez jamais un fichier de configuration qui
contient un jeton : gardez-le dans une variable d’environnement, ou dans
les réglages privés de votre client.
Ce qui est envoyé, ce qui est gardé
Ce que vous envoyez à un outil sert uniquement à répondre : ce n’est jamais stocké, et c’est retiré de nos rapports d’erreur. Un appel à l’API le porte dans son adresse : les journaux de requêtes de notre serveur ignorent ces adresses, mais elles passent par le réseau de Cloudflare qui achemine le trafic du site. MCP l’envoie dans le corps de la requête, qu’aucun journal de requêtes ne garde : vous pouvez le préférer pour un texte sensible. Les statistiques comptent seulement quel outil a été appelé, depuis où (une page, l’API ou MCP) et comment cela s’est terminé. Un outil qui recherche quelque chose envoie l’entrée aux services publics dont il a besoin, comme sa page. Voir la politique de confidentialité.