L’API

Tout ce que fait le site, il le fait par cette API — il n’y en a pas de privée. Cinq outils, une seule forme : vous créez une tâche, vous la suivez, vous récupérez le résultat. Sans clé, la formule gratuite ; avec, les limites hautes.

Où elle se trouve

https://bigitools.com

Votre clé

Les deux en-têtes marchent, prenez celui qui arrange votre client :

Authorization: Bearer ok_…
X-API-Key: ok_…

Une clé qu’elle ne reconnaît pas reçoit un 401, exprès : elle ne retombe PAS discrètement sur la formule gratuite. Si vous vous trompez en la recopiant, vous le voyez au premier appel et pas quand une limite qui ne devrait pas vous concerner vous tombe dessus.

Une tâche, du début à la fin

1. 1. La créer

   curl -X POST $API/api/jobs \
     -H 'Authorization: Bearer ok_…' \
     -H 'Content-Type: application/json' \
     -d '{"tool":"mail-doctor","input":{"domain":"example.com"}}'
   
   { "id": "cm…", "status": "queued", "stream": "/api/jobs/cm…/stream", "key": "n7Qk…" }

   Gardez la clé : elle est donnée UNE fois et nous ne pouvons pas la renvoyer. Lire la tâche, ses fichiers et l’annuler en ont tous besoin — envoyez-la en X-Job-Key, ou en ?key= là où un en-tête est impossible. Nous n’en stockons qu’une empreinte : une clé perdue, c’est une tâche que vous ne pouvez plus atteindre ; de toute façon elle expire avec le rapport. Si la tâche a été créée avec la clé d’API d’un compte, celle-là l’ouvre aussi et vous pouvez oublier celle-ci.

   Les outils qui ont besoin d’identifiants les reçoivent dans un objet secret à part, jamais dans input : l’entrée est conservée avec la tâche, le secret est chiffré et effacé dès que la tâche se termine.

2. 2. La suivre

   Interrogez GET /api/jobs/:id, ou ouvrez le flux et recevez les étapes au fur et à mesure :

   curl -N "$API/api/jobs/cm…/stream?key=n7Qk…"

   Le flux est en Server-Sent Events, et chaque événement porte un id. Si ça coupe, reconnectez-vous avec ?desde=<dernier id> et vous récupérez ce qui manque au lieu de tout reprendre. La clé passe ici dans l’URL et non dans un en-tête, parce qu’un client SSE ne peut pas en envoyer — raison de plus pour savoir qu’une URL contenant une clé finit dans les journaux d’accès.

3. 3. Récupérer le résultat

   Il arrive dans result quand la tâche est done. Les outils qui produisent des fichiers ajoutent :

   GET /api/jobs/:id/export/:format  le rapport — /api/tools liste les formats
   GET /api/jobs/:id/files           ce qui a été produit, en liste
   GET /api/jobs/:id/files/<path>    l’un d’eux
   GET /api/jobs/:id/download.zip    tous ensemble

   Les quatre veulent la clé, comme tout le reste concernant cette tâche.

Le reste

GET  /api/health            le service répond-il, et la file avance-t-elle
GET  /api/tools             le catalogue : limites de l’offre gratuite et formats
GET  /api/me                votre offre et ce que vous avez consommé
POST /api/jobs/:id/cancel   en arrêter un qui tourne encore
POST /api/mailtest          une adresse à usage unique où envoyer un message (renvoie aussi une clé)
GET  /api/mailtest/:id      est-il arrivé, et quel travail l’a noté (demande cette clé)
POST /api/monitors          surveiller une IP, un certificat, un domaine ou son DNS
GET  /api/monitors          ce que vous surveillez, et ce qui a changé
DELETE /api/monitors/:id    arrêter la surveillance
GET  /api/ip                l’adresse depuis laquelle ce serveur vous voit, avec son DNS inverse
GET  /api/ip/plain          la même, une ligne, sans JSON à analyser — pour un terminal
GET  /api/is-it-down?url=…  ce site est-il hors service, ou est-ce vous — vérifié d’ici
GET  /api/speed             ce que le test de vitesse peut dépenser et ce qu’il en reste
GET  /api/speed/down        des octets pour mesurer ; POST /api/speed/up dans l’autre sens

À quoi ressemble une erreur

Toute erreur répond en JSON avec error : une phrase en anglais, écrite pour être lue depuis un terminal. Certaines portent aussi code, un identifiant stable destiné aux programmes, pour qu’un client décide sans analyser de la prose. Branchez sur code quand il est là, et affichez error sinon.

Les codes qui existent aujourd’hui :

body-too-large
internal-error
invalid-credentials
invalid-input
job-already-finished
job-expired
job-expired-live
job-no-files
job-not-finished
job-not-found
job-not-yours
job-owner-unknown
key-bad-format
key-not-recognised
mailtest-not-found
monitor-dns-target
monitor-domain-date-ambiguous
monitor-domain-interval
monitor-domain-no-expiry
monitor-domain-no-whois
monitor-domain-registry-list
monitor-domain-silent
monitor-domain-target
monitor-duplicate
monitor-field
monitor-http-no-dns
monitor-http-private
monitor-http-target
monitor-interval
monitor-ip-not-ipv4
monitor-ip-private
monitor-ip-v6
monitor-limit
monitor-no-webhook
monitor-not-found
monitor-tls-is-ip
monitor-tls-target
monitor-webhook-url
monitoring-needs-account
monitoring-not-open
monitoring-paid-plan
monitoring-paid-plan-closed
rate-limited
rate-limited-checks
rate-limited-speed
result-expired
speed-budget-client
speed-budget-server
speed-no-accounting
stream-broken
stream-unavailable
zip-failed

Ce que veulent dire les codes

Le rapport, dans la langue de votre utilisateur

Ajoutez ?lang= et tout ce qu’écrit le moteur revient traduit : ce que dit chaque contrôle, la progression, le journal et la raison d’un échec. Neuf langues ; anglais si vous ne mettez rien.

GET /api/jobs/:id?lang=de                 le rapport, traduit
GET /api/jobs/:id/stream?lang=de          la progression et le journal, en direct
GET /api/jobs/:id/export/:format?lang=de  le fichier que vous téléchargez, traduit

lang: de · en · es · fr · it · nl · pl · pt · ro

Seul le texte change. Le code d’une erreur est le même dans les neuf — c’est sur lui qu’on branche, et le message est celui qu’on peut afficher tel quel. Accept-Language est ignoré à dessein : c’est la langue du navigateur, pas celle de la page que votre utilisateur est en train de lire, et mélanger les deux met des phrases espagnoles dans un rapport anglais.

Les outils, et ce que donne la formule gratuite

Les limites sont lues en direct depuis /api/tools, pas écrites ici : un catalogue tapé à la main est périmé dès qu’on ajoute un outil.

Deux choses à savoir

• · L’identifiant n’est pas la clé : c’est la clé de la tâche. Elle est remise une fois à la création et nous n’en gardons qu’une empreinte. Qui la détient lit ce rapport jusqu’à son expiration : traitez-la comme le rapport lui-même.
• · Les résultats expirent. Téléchargez ce qu’il vous faut ; ensuite l’entrée part aussi, pas seulement la sortie.