Die API

Alles, was die Website tut, tut sie über diese API — eine private gibt es nicht. Fünf Werkzeuge, eine Form: du legst einen Auftrag an, du verfolgst ihn, du nimmst das Ergebnis mit. Ohne Schlüssel gilt die kostenlose Stufe, mit Schlüssel die höheren Grenzen.

Es gibt noch keine Anmeldung, also auch keine Schlüssel zu verteilen: alles hier unten läuft auf der kostenlosen Stufe, die kein Konto braucht. Die Schlüssel-Header stehen hier, weil die API sie bereits akzeptiert.

Wo sie liegt

https://bigitools.com

Dein Schlüssel

Beide Header gehen — nimm den, der deinem Client leichter fällt:

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

Ein Schlüssel, den sie nicht kennt, bekommt absichtlich ein 401: sie fällt NICHT stillschweigend auf die kostenlose Stufe zurück. Vertippst du dich, merkst du es beim ersten Aufruf und nicht, wenn dich eine Grenze trifft, die für dich gar nicht gelten sollte.

Ein Auftrag, von Anfang bis Ende

1. Anlegen
```
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…" }
```
Heb den Schlüssel auf: er wird EINMAL ausgegeben und wir können ihn nicht erneut schicken. Den Auftrag lesen, seine Dateien holen und ihn abbrechen brauchen ihn alle — schick ihn als X-Job-Key, oder als ?key=, wo kein Header möglich ist. Wir speichern nur seinen Fingerabdruck, ein verlorener Schlüssel ist also ein Auftrag, an den du nicht mehr kommst; er verfällt ohnehin mit dem Bericht. Wurde der Auftrag mit dem API-Schlüssel eines Kontos angelegt, öffnet auch dieser ihn und du kannst diesen hier vergessen.
Werkzeuge, die Zugangsdaten brauchen, bekommen sie in einem eigenen secret-Objekt, nie innerhalb von input: die Eingabe wird mit dem Auftrag aufbewahrt, das Geheimnis wird verschlüsselt und gelöscht, sobald der Auftrag endet.
2. Verfolgen
Frag GET /api/jobs/:id ab, oder öffne den Stream und bekomm die Schritte, während sie passieren:
```
curl -N "$API/api/jobs/cm…/stream?key=n7Qk…"
```
Der Stream sind Server-Sent Events, und jedes Ereignis trägt eine id. Reißt die Verbindung ab, verbinde dich mit ?desde=<letzte id> neu und bekommst das Verpasste, statt von vorn anzufangen. Der Schlüssel steht hier im Query-String und nicht in einem Header, weil ein SSE-Client keinen senden kann — weshalb es auch gut zu wissen ist, dass eine URL mit Schlüssel darin in Zugriffsprotokollen landet.

3. Ergebnis mitnehmen

Es kommt in result, sobald der Auftrag done ist. Werkzeuge, die Dateien erzeugen, ergänzen:

GET /api/jobs/:id/export/:format  der Bericht — /api/tools listet die Formate
GET /api/jobs/:id/files           was erzeugt wurde, als Liste
GET /api/jobs/:id/files/<path>    eine davon
GET /api/jobs/:id/download.zip    alle zusammen

Alle vier wollen den Schlüssel, wie alles andere zu diesem Auftrag auch.

Der Rest

GET  /api/health            läuft der Dienst, und bewegt sich die Warteschlange
GET  /api/tools             der Katalog: Grenzen der kostenlosen Stufe und Formate
GET  /api/me                dein Tarif und was du verbraucht hast
POST /api/jobs/:id/cancel   einen abbrechen, der noch läuft
POST /api/mailtest          eine Einweg-Adresse zum Hinschicken (gibt auch einen Schlüssel zurück)
GET  /api/mailtest/:id      ist sie angekommen, und welcher Auftrag hat sie bewertet (braucht den Schlüssel)
POST /api/monitors          eine IP, ein Zertifikat, eine Domain oder ihr DNS überwachen
GET  /api/monitors          was du überwachst, und was sich geändert hat
DELETE /api/monitors/:id    nicht mehr überwachen
GET  /api/ip                die Adresse, von der dieser Server dich sieht, mit ihrem Reverse DNS
GET  /api/ip/plain          dasselbe, eine Zeile, kein JSON zum Auswerten — fürs Terminal
GET  /api/is-it-down?url=…  ist die Seite unten, oder liegt es an dir — von hier aus geprüft
GET  /api/speed             was der Geschwindigkeitstest ausgeben darf und was davon übrig ist
GET  /api/speed/down        Bytes zum Messen; POST /api/speed/up für die andere Richtung

Wie ein Fehler aussieht

Jeder Fehler antwortet mit JSON und error: ein Satz auf Englisch, zum Lesen im Terminal geschrieben. Manche tragen zusätzlich code, eine stabile Kennung für Programme, damit ein Client entscheiden kann, ohne Prosa zu zerlegen. Verzweige über code, wenn er da ist, und zeige error, wenn nicht.

Die Codes, die es heute gibt:

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

Was die Codes bedeuten

400	Die Anfrage ist falsch, und die Meldung sagt, was zu ändern ist — nicht den Namen einer unserer Variablen.
401	Der Schlüssel ist unbekannt oder nicht im erwarteten Format.
402	Kostenpflichtige Funktion. Die Überwachung ist die, die das antwortet.
403	Dieser Auftrag gehört dir nicht: ihn öffnet der Schlüssel, der beim Anlegen ausgegeben wurde.
404	Kein solcher Auftrag, oder er ist abgelaufen. Ergebnisse bleiben nicht ewig.
409	Das überwachst du schon, und zwar genauso.
413	Der Rumpf ist über der Grenze.
429	Eine Grenze — und die Meldung sagt WELCHE, damit du weißt, ob du eine Minute oder einen Tag warten musst.
503	Etwas, worauf das Werkzeug angewiesen ist, antwortet gerade nicht.

Der Bericht, in der Sprache deiner Nutzer

Häng ?lang= an, und was das Werkzeug schreibt kommt übersetzt zurück: die Befunde, der Fortschritt, das Protokoll und der Grund, warum ein Auftrag gescheitert ist. Neun Sprachen; ohne Angabe Englisch.

GET /api/jobs/:id?lang=de                 der Bericht, übersetzt
GET /api/jobs/:id/stream?lang=de          Fortschritt und Protokoll, während es passiert
GET /api/jobs/:id/export/:format?lang=de  die Datei, die du herunterlädst, übersetzt

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

Nur der Text ändert sich. Der Code eines Fehlers ist in allen neun derselbe — nach dem verzweigst du, und die Meldung ist die, die du so anzeigen kannst. Accept-Language wird bewusst ignoriert: das ist die Sprache des Browsers, nicht die der Seite, die deine Nutzer gerade lesen, und beides zu mischen setzt spanische Sätze in einen englischen Bericht.

Die Werkzeuge, und was die kostenlose Stufe hergibt

Die Grenzen werden live aus /api/tools gelesen und nicht hier hingeschrieben: ein von Hand getippter Katalog ist veraltet, sobald jemand ein Werkzeug hinzufügt.

Die API wird gefragt…

Zwei Dinge, die man wissen sollte

· Die Zugangsberechtigung ist der Auftragsschlüssel, nicht die id. Er wird beim Anlegen einmal ausgegeben, und wir behalten nur einen Fingerabdruck. Wer ihn hat, liest diesen Bericht bis er verfällt — behandle den Schlüssel also wie den Bericht selbst.
· Ergebnisse verfallen. Lad herunter, was du brauchst; danach geht auch die Eingabe, nicht nur die Ausgabe.