Passer au contenu

API, CLI et MCP

Trois façons d'accéder au même compte, avec les mêmes limites de forfait et les mêmes permissions que ton rôle te donne déjà. Tout ce qui suit est l'une de ces trois, donc ça vaut le coup de savoir laquelle tu utilises.

API

REST, depuis un pipeline, un script ou tes propres outils. Un token que tu crées et révoques toi-même, et du JSON dans les deux sens.

L'API

CLI

Un fichier Python, rien à installer. La même API, pour quelqu'un au terminal plutôt qu'un programme : liste ce qui est down, ajoute un monitor.

Le client en ligne de commande

MCP

Une adresse, collée dans Claude ou tout autre outil qui parle le protocole. Elle lit le compte et le modifie, comme toi, dans une conversation.

Pour un assistant

Ton token API

Crée-en un dans la section API tokens de ton compte. Il est affiché une seule fois, on ne garde qu'une empreinte, et il t'appartient plutôt qu'à l'organisation : il ne peut pas faire plus que toi, et il cesse de fonctionner si tu pars ou si ton rôle change. Choisis lecture, ou lecture et écriture.

Envoie-le comme Authorization: Bearer n404_... à chaque appel. Le premier appel utile est /api/v1/me, qui répond pour quelle organisation le token agit, quel rôle il porte et lequel des deux scopes il a : une personne avec deux comptes a deux tokens et aucun autre moyen de savoir lequel est dans une variable d'environnement.

Ce qu'il y a dans la version 1

Appel Ce qu'il fait
GET /api/v1/me Ce qu'est ce token, et pour quelle organisation il agit
GET /api/v1/monitors Tous les monitors, du plus ancien au plus récent
POST /api/v1/monitors Crée-en un, selon les mêmes règles que le formulaire respecte
GET /api/v1/monitors/{id} Un monitor
PATCH /api/v1/monitors/{id} Change son nom, son adresse, son intervalle ou sa config, ou mets-le en pause
DELETE /api/v1/monitors/{id} Supprime-le, ainsi que son historique
GET /api/v1/monitors/{id}/status Ce qu'il fait maintenant, et son uptime sur une période
GET /api/v1/groups Chaque groupe, avec combien de monitors il contient
POST /api/v1/groups Crée-en un ; un nom existant renvoie le groupe qui l'a
GET /api/v1/groups/{id} Un groupe
PATCH /api/v1/groups/{id} Renomme-le ou change sa description
DELETE /api/v1/groups/{id} Supprime-le. Ses monitors restent, sans groupe
GET /api/v1/incidents Pannes, les plus récentes d'abord, filtrées par état, monitor ou période
GET /api/v1/incidents/{id} Un incident, avec les probes qui l'ont vu et confirmé
GET /api/v1/maintenance Fenêtres de maintenance et ce qu'elles couvrent
GET /api/v1/maintenance/{id} Une fenêtre, avec les monitors et groupes qu'elle couvre
POST /api/v1/maintenance Planifie-en une, selon l'horloge de ton organisation, pour qu'un déploiement puisse ouvrir une fenêtre avant de commencer
DELETE /api/v1/maintenance/{id} Supprime-la. Ce qu'elle couvrait reste couvert
GET /api/v1/status-pages Chaque status page, et si elle est activée
GET /api/v1/status-pages/{id} Une page, et ce qui y est publié
POST /api/v1/status-pages/{id}/monitors Ajoute un monitor à la page, sous le nom que son audience doit lire
DELETE /api/v1/status-pages/{id}/monitors/{id} Retire-le de cette page. Les autres pages le gardent
POST /api/v1/status-pages/{id}/groups Ajoute un groupe à la page ; les monitors qu'il contient viennent aussi
DELETE /api/v1/status-pages/{id}/groups/{id} Retire l'en-tête. Ses monitors restent publiés

Chaque id dans un chemin ou un corps est l'UUID, jamais un nombre. Écrire nécessite un token de lecture et d'écriture et un rôle qui peut écrire : le scope est ce que tu as donné à un programme, le rôle est ce que tu étais autorisé à transmettre.

openapi.json

Le document est OpenAPI 3.1. Il décrit chaque appel, la structure de chaque corps, et le bearer token, pour qu'un client puisse être généré à partir de lui plutôt qu'écrit : openapi-generator, oapi-codegen et les autres le lisent tel quel. Les opérations portent des noms pour une personne, donc les méthodes générées sont listMonitors et createMonitor.

La version 1 ne fait que grandir : un champ peut être ajouté, aucun n'est supprimé ou retypé, et une deuxième version serait un deuxième chemin. Ainsi, un client généré continue de fonctionner, et le régénérer permet de récupérer les nouveautés.

Un client, si tu en veux un

Un fichier, Python 3.9 ou plus récent, sans dépendances. Télécharge-le, rends-le exécutable, et mets ton token dans l'environnement. Il fait tout ce que l'API fait, car chaque commande est un appel aux routes ci-dessus.

nomore404.py nomore404_mcp.py 

curl -O https://nomore404.com/api/nomore404.py
curl -s https://nomore404.com/api/nomore404.py.sha256 | sha256sum -c
chmod +x nomore404.py
export N404_TOKEN=n404_...

./nomore404.py monitors list
./nomore404.py monitors add --type https --target shop.example.com
./nomore404.py incidents --state open

La deuxième ligne vaut la peine d'être exécutée. Elle vérifie le fichier par rapport au digest que nous publions à côté, qui est le digest de ce que ce serveur envoie exactement, donc un téléchargement altéré en chemin ne correspond pas. ./nomore404.py --version indique de quelle version il provient, et chaque requête qu'il fait indique la même chose dans son User-Agent.

Le token vient de N404_TOKEN ou d'un fichier nomore404.env à côté du script, jamais d'un argument en ligne de commande : un argument est visible dans ps pour tous les utilisateurs de la machine et reste dans l'historique de ton shell.

Pour un assistant

Un assistant peut lire ce compte et le modifier, via le Model Context Protocol. Il y a deux moyens d'accès et ils ne sont pas identiques.

Une adresse, rien à installer

Colle ceci là où ton assistant demande un connecteur personnalisé. Il t'enverra ici pour te connecter et indiquer pour quelle organisation est la connexion, et c'est toute la configuration.

Il agit en ton nom : ton rôle est lu à chaque appel, donc un assistant connecté par quelqu'un qui ne peut que lire ne pourra que lire. Il lit les monitors, les pannes, l'uptime, les fenêtres de maintenance et les groupes, et il peut les ajouter et les modifier, ce qui inclut la suppression d'un monitor et de son historique. Déconnecte-le quand tu veux depuis Tokens API, où il est listé à côté d'eux.

Ou exécute-le toi-même, et laisse-le lire

nomore404_mcp.py sert la même API que les outils depuis ta propre machine. Garde-le à côté de nomore404.py, qu'il utilise pour le token et pour la pagination. Il lit et n'écrit jamais, ce qui est la raison de le choisir : un assistant est un appelant qu'on peut manipuler, et un outil qui supprime un monitor et son historique est à un prompt d'être utilisé.

Deux fichiers, un token à côté, et une ligne pour enregistrer le serveur. Claude Code : 

curl -O https://nomore404.com/api/nomore404.py
curl -O https://nomore404.com/api/nomore404_mcp.py
echo 'N404_TOKEN=n404_...' > nomore404.env

claude mcp add nomore404 -- python3 "$PWD/nomore404_mcp.py"

Tout autre chose qui parle le protocole est la même commande écrite en JSON, où que ce client garde ses serveurs : 

{
  "mcpServers": {
    "nomore404": {
      "command": "python3",
      "args": ["/path/to/nomore404_mcp.py"]
    }
  }
}

Aucun ne nomme le token, car aucun ne devrait : il est lu depuis nomore404.env à côté des scripts, ou depuis N404_TOKEN dans l'environnement avec lequel l'assistant le lance. Ensuite, demande-lui ce qui est down, pourquoi un incident s'est ouvert, ou comment un monitor s'est comporté ce mois-ci.

Les deux font quelques centaines de lignes et valent la peine d'être lus avant de les exécuter. Aucun n'est packagé ou signé, et rien ne t'empêche de générer ton propre client à partir du document à la place.

Échecs, et longues listes

Une forme d'erreur

Le status indique la catégorie. Le corps indique quelle erreur c'était, avec un code pour bifurquer et une phrase à lire. La phrase peut être reformulée dans n'importe quelle version, donc rien ne devrait l'analyser. 

{
  "error": {
    "code": "monitor_not_found",
    "message": "Nothing here with that id."
  }
}

Cursors, pas offsets

Une liste répond avec items et next_cursor. Renvoie le cursor pour obtenir la page suivante, et arrête-toi quand il est null. Les incidents arrivent pendant que tu les lis, et un offset te montrerait discrètement une ligne deux fois et ne montrerait jamais la suivante. 

GET /api/v1/incidents?limit=50
GET /api/v1/incidents?limit=50&cursor=...

Combien tu peux demander

Un token peut faire cent vingt appels par minute. Chaque réponse inclut RateLimit-Remaining et RateLimit-Reset, donc un client bien élevé peut s'autoréguler au lieu de découvrir la limite en la dépassant. Au-delà de la limite, c'est un 429 avec Retry-After.

Crée un compte gratuit