De API

Alles wat de site doet, doet hij via deze API — een privé-API is er niet. Vijf tools, één vorm: je maakt een opdracht, je volgt hem, je neemt het resultaat mee. Zonder sleutel geldt de gratis laag; met sleutel de hogere limieten.

Waar hij staat

https://bigitools.com

Je sleutel

Beide headers werken, welke jouw client het makkelijkst maakt:

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

Een sleutel die hij niet kent krijgt met opzet een 401: hij valt NIET stilletjes terug op de gratis laag. Tik je hem verkeerd, dan merk je dat bij de eerste aanroep en niet wanneer een limiet je raakt die niet voor jou bedoeld was.

Een opdracht, van begin tot eind

1. 1. Maak hem aan

   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…" }

   Bewaar de sleutel: hij wordt ÉÉN keer gegeven en we kunnen hem niet opnieuw sturen. De opdracht lezen, zijn bestanden ophalen en hem annuleren hebben hem allemaal nodig — stuur hem als X-Job-Key, of als ?key= waar een header niet kan. We bewaren alleen een vingerafdruk, dus een verloren sleutel is een opdracht die je niet meer kunt bereiken; hij vervalt sowieso met het rapport. Is de opdracht gemaakt met de API-sleutel van een account, dan opent die hem ook en kun je deze vergeten.

   Tools die inloggegevens nodig hebben, krijgen ze in een apart secret-object, nooit in input: de invoer blijft bij de opdracht en het geheim wordt versleuteld en gewist zodra de opdracht klaar is.

2. 2. Volg hem

   Vraag GET /api/jobs/:id op, of open de stream en krijg de stappen terwijl ze gebeuren:

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

   De stream is Server-Sent Events en elk event draagt een id. Valt het weg, verbind dan opnieuw met ?desde=<laatste id> en je krijgt wat je miste in plaats van opnieuw te beginnen. De sleutel gaat hier in de URL en niet in een header, omdat een SSE-client er geen kan sturen — reden te meer om te weten dat een URL met sleutel in de toegangslogs belandt.

3. 3. Neem het resultaat mee

   Het komt in result zodra de opdracht done is. Tools die bestanden maken voegen toe:

   GET /api/jobs/:id/export/:format  het rapport — /api/tools somt de formaten op
   GET /api/jobs/:id/files           wat er gemaakt is, als lijst
   GET /api/jobs/:id/files/<path>    een ervan
   GET /api/jobs/:id/download.zip    alles bij elkaar

   Alle vier willen de sleutel, net als al het andere rond die opdracht.

De rest

GET  /api/health            draait de dienst, en beweegt de wachtrij
GET  /api/tools             de catalogus: grenzen van de gratis laag en formaten
GET  /api/me                je abonnement en wat je hebt verbruikt
POST /api/jobs/:id/cancel   er een stoppen die nog loopt
POST /api/mailtest          een eenmalig adres om iets heen te sturen (geeft ook een sleutel terug)
GET  /api/mailtest/:id      of hij aangekomen is, en welke opdracht hem beoordeeld heeft (vraagt die sleutel)
POST /api/monitors          een IP, een certificaat, een domein of zijn DNS bewaken
GET  /api/monitors          wat je bewaakt, en wat er veranderd is
DELETE /api/monitors/:id    stoppen met bewaken
GET  /api/ip                het adres waarvandaan deze server je ziet, met zijn reverse DNS
GET  /api/ip/plain          hetzelfde, één regel, geen JSON om te ontleden — voor een terminal
GET  /api/is-it-down?url=…  ligt die site eruit, of ligt het aan jou — vanaf hier gecontroleerd
GET  /api/speed             wat de snelheidstest mag uitgeven en wat ervan over is
GET  /api/speed/down        bytes om mee te meten; POST /api/speed/up voor de andere kant

Hoe een fout eruitziet

Elke fout antwoordt met JSON en error: een zin in het Engels, geschreven om vanuit een terminal gelezen te worden. Sommige dragen ook code, een stabiele aanduiding bedoeld voor programma’s, zodat een client kan beslissen zonder proza te ontleden. Vertak op code als die er is, en toon error als die er niet is.

De codes die vandaag bestaan:

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

Wat de codes betekenen

Het rapport, in de taal van je gebruiker

Zet er ?lang= achter en wat de tool schrijft komt vertaald terug: wat elke controle zegt, de voortgang, het logboek en de reden waarom een taak is mislukt. Negen talen; Engels als je niets meegeeft.

GET /api/jobs/:id?lang=de                 het rapport, vertaald
GET /api/jobs/:id/stream?lang=de          voortgang en logboek, terwijl het gebeurt
GET /api/jobs/:id/export/:format?lang=de  het bestand dat je downloadt, vertaald

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

Alleen de tekst verandert. De code van een fout is in alle negen dezelfde — daarop vertak je, en het bericht is wat je zo kunt tonen. Accept-Language wordt met opzet genegeerd: dat is de taal van de browser, niet die van de pagina die je gebruiker aan het lezen is, en die twee door elkaar zet Spaanse zinnen in een Engels rapport.

De tools, en wat de gratis laag je geeft

De limieten komen live uit /api/tools en staan hier niet opgeschreven: een met de hand getypte catalogus is verouderd zodra iemand een tool toevoegt.

Twee dingen die het weten waard zijn

• · De sleutel van de opdracht is de credential, niet het id. Hij wordt bij het aanmaken één keer gegeven en wij houden alleen een vingerafdruk. Wie hem heeft leest dat rapport tot het vervalt: behandel de sleutel als het rapport zelf.
• · Resultaten vervallen. Download wat je nodig hebt; daarna gaat ook de invoer weg, niet alleen de uitvoer.