API et jetons
L'API de VoxelBench permet à un script ou à un agent de lire vos rapports, serveurs, monitoring et runs d'auto-bench, et de faire les modifications courantes d'un propriétaire. Voici comment créer un jeton, ce que permet chaque offre, ce qui peut s'écrire ou non, et ce que signifient les erreurs.
À quoi sert l'API
L'API répond en JSON à l'adresse https://voxelbench.com/api/v1/…. Quelques usages typiques :
- suivre les rapports et le monitoring de vos serveurs depuis un script ou votre propre tableau de bord ;
- lancer un run d'auto-bench depuis une chaîne de déploiement, puis en lire le résultat ;
- donner à un agent d'IA l'accès à votre compte (pour Claude, voir Brancher Claude sur votre compte).
Les rapports publics et le catalogue des offres d'hébergement se lisent sans jeton. Tout le reste en demande un :
curl -H "Authorization: Bearer vb_…" "https://voxelbench.com/api/v1/reports?mine=true&limit=10"
Un jeton ne voit jamais plus que votre compte. Ce qu'il peut faire est recalculé à chaque requête : les portées qu'il porte, limitées à ce que votre compte a le droit de faire aujourd'hui. Si votre offre prend fin, l'accès suit dans la seconde, sans rien à révoquer.
Créer un jeton
Ouvrez Paramètres (Profil et paramètres dans le menu du tableau de bord), onglet Sécurité, carte Jetons d'API :
- Donnez au jeton un Nom (80 caractères au plus), pour savoir plus tard ce qui s'en sert.
- Réglez Expire dans (jours) : de 1 à 365, 90 par défaut.
- Cochez au moins une portée, puis cliquez sur Créer.
- Copiez le jeton tout de suite. Il commence par
vb_et ne s'affiche qu'une fois : VoxelBench n'en garde que l'empreinte. Un jeton perdu ne se retrouve pas ; révoquez-le et créez-en un autre.
Un jeton ne se crée que depuis un navigateur connecté : un jeton ne peut jamais en créer un autre. La même carte liste vos jetons avec leurs portées et leur dernier usage, indique combien d'appels à l'API vous avez faits aujourd'hui, et propose un bouton Révoquer sur chaque ligne.
Portées
Ne cochez que les portées (scopes) dont vous avez besoin : un jeton rangé dans un fichier de configuration ne doit rien pouvoir faire que vous n'ayez voulu.
| Portée | Ce qu'elle ouvre |
|---|---|
reports:read | Les rapports de benchmark, leur diagnostic, les comparaisons, les conseils de réglage et les verdicts avant/après |
unit-tests:read | Les résultats de tests unitaires |
servers:read | Vos serveurs liés, vos groupes de serveurs, et la baisse éventuelle des performances d'un serveur |
auto-bench:read | Vos cibles d'auto-bench et leurs runs |
monitoring:read | Tout ce que le monitoring de vos serveurs enregistre : l'état en direct, les séries de métriques, les événements, la vue d'ensemble de tous vos serveurs, les profils de performance et les rapports mémoire avec leurs comparaisons, les maintenances, les règles d'alerte et les alertes |
offers:read | Le catalogue des offres d'hébergement |
servers:write | Renommer un serveur, changer sa visibilité, gérer les groupes et y ranger les serveurs |
servers:link | Lier un nouveau serveur avec le code de 8 caractères qu'affiche le plugin |
reports:write | Changer la visibilité, la description et les notes privées d'un rapport |
monitoring:write | Créer, modifier et suspendre des règles d'alerte, envoyer une notification de test, acquitter des alertes, ouvrir et clore une maintenance |
auto-bench:write | Lancer, annuler et replanifier des runs sur des cibles que vous avez déjà |
auto-bench:write et monitoring:write peuvent se cocher sur toutes les offres. L'écran les marque pro quand votre offre n'inclut pas l'auto-bench ou le monitoring : le jeton est bien créé, mais ces appels répondent plan_required tant que l'offre ne change pas.
Combien de jetons
| Offre | Jetons actifs |
|---|---|
| Gratuit | 1 |
| Pro | 5 |
| Hébergeur | 10 |
| Enterprise | 20 |
Un connecteur que vous avez autorisé pour Claude ou un autre client MCP compte pour un jeton. La limite est contrôlée à la création d'un jeton, puis à chaque appel : si votre offre prend fin, seuls vos jetons les plus récents, dans la nouvelle limite, continuent de fonctionner, et les autres répondent token_quota_exceeded. Lister et révoquer ses jetons reste toujours possible, sur toutes les offres.
Quotas
Chaque réponse indique ce qui reste, avec X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; X-RateLimit-Window précise laquelle des deux limites ci-dessous est la plus proche (day ou hour).
Appels quotidiens
| Offre | Appels à l'API par jour |
|---|---|
| Gratuit, et appels sans jeton | 10 |
| Pro | 50 |
| Hébergeur | 150 |
| Enterprise | 500 |
- Le quota appartient au compte : tous ses jetons et connecteurs le partagent. Cinq jetons n'achètent pas cinq quotas.
- Lectures et écritures comptent pareil.
- Sans jeton, le quota s'applique par adresse IP.
- Naviguer sur voxelbench.com en étant connecté ne compte pas : seuls les appels faits avec un jeton comptent.
- La journée est une fenêtre de 24 heures qui commence à votre premier appel compté ; le refus indique quand elle se termine.
GET /api/v1/token, qui dit ce que le jeton appelant peut faire, ne compte pas.
Limite horaire
Chaque jeton peut en outre faire jusqu'à 600 appels par heure. Au-delà, l'API répond rate_limited avec un en-tête Retry-After.
Runs d'auto-bench
Le lancement de runs a son propre quota, compté sur les 24 dernières heures :
| Offre | Runs par 24 heures |
|---|---|
| Gratuit | 0 |
| Pro | 10 |
| Hébergeur | 30 |
| Enterprise | 100 |
Chaque run d'une cible compte (une cible à 3 runs par job en compte 3), runs planifiés compris. Voir L'auto-bench sur le site.
Ce que vous pouvez lire
Les listes répondent { data, page: { cursor, has_more } }. Renvoyez page.cursor tel quel dans ?cursor= pour obtenir la page suivante ; limit règle la taille de la page, 25 par défaut et 100 au plus.
| Portée | Points d'accès |
|---|---|
reports:read | GET /api/v1/reports, /reports/{id}, /reports/{id}/diagnosis, /reports/{id}/tuning, /reports/compare, /reports/before-after |
unit-tests:read | GET /api/v1/unit-tests, /unit-tests/{id} |
servers:read | GET /api/v1/servers, /server-groups, /servers/{id}/regression |
auto-bench:read | GET /api/v1/auto-bench/targets, /auto-bench/jobs |
monitoring:read | GET /api/v1/monitoring/overview, /servers/{id}/status, /servers/{id}/metrics, /servers/{id}/events, /servers/{id}/alert-rules, /servers/{id}/event-alert-rules, /alert-events, /servers/{id}/maintenance, ainsi que les profils et rapports mémoire de vos serveurs |
offers:read | GET /api/v1/offers |
Les points d'accès des rapports, des tests unitaires et des offres répondent aussi sans jeton, avec le seul contenu public : une liste donne les rapports publics et certifiés, et un rapport non répertorié ne s'ouvre que si vous le nommez par son identifiant. Avec un jeton, une liste ajoute vos propres rapports et ceux de vos serveurs liés et vérifiés, quelle que soit leur visibilité, et ?mine=true ne garde que les vôtres ; les rapports non répertoriés d'un autre compte n'apparaissent dans aucune liste. Un rapport privé ou un test unitaire s'ouvre pour son auteur, pour le détenteur de son serveur une fois ce serveur vérifié, et pour les administrateurs ; pour tout autre, c'est not_found.
Les métriques et les événements d'un serveur demandent une offre qui inclut le monitoring, et la période demandée doit tenir dans ce que votre offre permet de consulter (sinon retention_exceeded).
Ce que vous pouvez écrire
Chaque écriture a sa portée, et chaque route accepte une liste fixe de champs.
| Action | Point d'accès | Portée | Champs |
|---|---|---|---|
| Renommer un serveur, changer sa visibilité | PATCH /api/v1/servers/{id} | servers:write | name, is_public, show_address_on_report, notify_on_report |
| Créer un groupe | POST /api/v1/server-groups | servers:write | name, color |
| Renommer, recolorer ou réordonner un groupe | PATCH /api/v1/server-groups/{id} | servers:write | name, color, sort_order |
| Ranger un serveur dans un groupe | PUT /api/v1/servers/{id}/group | servers:write | group_id |
| Lier un nouveau serveur | POST /api/v1/servers/link | servers:link | code, name |
| Modifier un rapport | PATCH /api/v1/reports/{id} | reports:write | visibility, description, private_notes |
| Créer une règle d'alerte | POST /api/v1/servers/{id}/alert-rules | monitoring:write | name, metric, condition, threshold, duration_minutes, cooldown_minutes, notify_email, notify_discord, notify_in_app |
| Modifier, suspendre ou mettre en sourdine une règle | PATCH /api/v1/alert-rules/{id} | monitoring:write | Les mêmes, plus enabled et mute_minutes |
| Envoyer une notification de test | POST /api/v1/alert-rules/{id}/test | monitoring:write | — |
| Acquitter une alerte | POST /api/v1/alert-events/{id}/acknowledge | monitoring:write | — |
| Ouvrir ou prolonger une maintenance | POST /api/v1/servers/{id}/maintenance | monitoring:write | duration_minutes, reason |
| Clore une maintenance | POST /api/v1/servers/{id}/maintenance/end | monitoring:write | — |
| Lancer un run | POST /api/v1/auto-bench/targets/{id}/run-now | auto-bench:write | — |
| Demander l'arrêt d'un run | POST /api/v1/auto-bench/jobs/{id}/cancel | auto-bench:write | — |
| Replanifier une cible | PATCH /api/v1/auto-bench/targets/{id} | auto-bench:write | enabled, schedule_cron, name, notes |
Un champ qu'une route n'accepte pas est refusé avec field_not_allowed, qui nomme le champ et liste ceux qui sont acceptés : il n'est jamais ignoré en silence. Les règles sont celles du tableau de bord : l'API ne peut rien faire que le tableau de bord refuserait. Par exemple, seul l'auteur d'un rapport peut changer sa visibility ou ses private_notes (pas le détenteur de son serveur vérifié), et rendre un rapport public ou non répertorié demande une adresse email vérifiée.
Lier un serveur demande le code qu'affiche le plugin avec /bench link : ce code prouve que vous avez accès au serveur, si bien qu'un jeton ne peut lier que le serveur dont on lui a donné le code. Un serveur déjà lié à votre compte répond already_linked : le lier de nouveau se fait depuis le tableau de bord, et lui retire sa vérification. Un seul run peut être en cours par cible : relancer répond already_running avec l'identifiant du run en cours, si bien que rejouer un lancement est sans risque. Un arrêt est une demande : la réponse signifie « demandé », et le run s'arrête peu après.
Ce qui reste entre vos mains
Certaines actions sont fermées aux jetons à dessein, et restent dans le tableau de bord :
- toute suppression (rapport, groupe, règle d'alerte, cible d'auto-bench) ;
- délier un serveur, ou lier de nouveau un serveur déjà lié ;
- créer une cible d'auto-bench, parce qu'elle engage un compte Microsoft que vous prêtez ;
- les adresses email de notification, les webhooks Discord et les webhooks, parce qu'ils décident où partent vos données ;
- les jetons, la facturation et le compte lui-même.
Erreurs
Les erreurs répondent { error, message }, parfois avec des détails.
| Statut | error | Signification, et que faire |
|---|---|---|
| 400 | field_not_allowed | Le corps contient un champ que cette route n'accepte pas ; allowed_fields liste ceux qu'elle accepte |
| 400 | invalid_json, invalid_body, validation_error, invalid_cursor | La requête elle-même est mal formée ; renvoyez le curseur exactement tel que reçu |
| 401 | unauthorized | Ce point d'accès demande un jeton |
| 401 | invalid_token, token_revoked, token_expired | Le jeton est inconnu, révoqué ou expiré : créez-en un nouveau |
| 403 | missing_scope | Il manque au jeton la portée nommée dans required_scope : créez un jeton qui la porte |
| 403 | plan_required | Votre offre n'inclut pas la fonctionnalité (auto-bench, monitoring) : c'est l'offre qu'il faut changer, pas le jeton |
| 403 | token_quota_exceeded | Votre offre ne couvre plus ce jeton : révoquez-en un plus ancien ou servez-vous d'un plus récent |
| 403 | retention_exceeded | La période demandée dépasse ce que votre offre permet de consulter |
| 404 | not_found | La ressource n'existe pas, ou vous n'avez pas le droit de la voir : l'API ne dit jamais lequel des deux |
| 409 | already_running, already_linked, internal_target | Un run est déjà en cours (job_id le désigne) ; le serveur est déjà lié à votre compte ; la cible est conduite par VoxelBench lui-même |
| 429 | daily_quota_exceeded | Le quota quotidien du compte est épuisé ; le message dit quand il repart |
| 429 | rate_limited | La limite horaire du jeton est atteinte ; attendez le délai de Retry-After |
| 429 | daily_run_quota_exceeded, cooldown | Plus aucun run d'auto-bench disponible sur les 24 dernières heures ; ou attendez 60 secondes entre deux lancements de la même cible |
404 plutôt que 403. Une ressource que vous n'avez pas le droit de lire répond exactement comme si elle n'existait pas : un 403 confirmerait son existence, et n'importe qui pourrait sonder les rapports ou les serveurs des autres. Un 404 veut donc dire « introuvable, ou pas à vous », jamais simplement « mauvais identifiant ».
missing_scope ou plan_required ? La portée dit ce qu'un jeton a le droit de tenter ; l'offre, ce que le compte a le droit de faire. Les deux sont contrôlées séparément, pour que le refus désigne la vraie cause.
Référence
- Référence de l'API : chaque point d'accès, groupé par portée, avec ses paramètres et l'indication d'un jeton requis ou non. Elle est générée à partir de la liste que le serveur applique : elle ne peut pas décrire un point d'accès qui n'existe pas.
- Document OpenAPI : la même liste au format OpenAPI 3.1, pour générer un client.
- Brancher un agent : le connecteur MCP pour Claude et d'autres agents, sur la même API.