API

Wszystko, co robi strona, robi przez to API — prywatnego nie ma. Pięć narzędzi, jeden kształt: tworzysz zadanie, śledzisz je, zabierasz wynik. Bez klucza idziesz darmowym torem; z kluczem — po wyższych limitach.

Gdzie mieszka

https://bigitools.com

Twój klucz

Działa każdy z dwóch nagłówków — ten, który twojemu klientowi łatwiej wysłać:

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

Klucz, którego nie rozpozna, dostaje 401 i to celowo: NIE zjeżdża po cichu na darmowy tor. Jeśli się pomylisz przy przepisywaniu, dowiesz się przy pierwszym wywołaniu, a nie wtedy, gdy uderzy w ciebie limit, który cię nie dotyczy.

Zadanie, od początku do końca

1. 1. Utwórz je

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

   Zachowaj klucz: wydajemy go RAZ i nie możemy przesłać ponownie. Odczyt zadania, jego plików i anulowanie — wszystko go wymaga. Wyślij go jako X-Job-Key albo jako ?key= tam, gdzie nagłówek jest niemożliwy. Trzymamy tylko odcisk, więc zgubiony klucz to zadanie, do którego już nie dotrzesz; i tak wygasa razem z raportem. Jeśli zadanie powstało z kluczem API konta, ten też je otwiera i o tym możesz zapomnieć.

   Narzędzia, które potrzebują danych logowania, dostają je w osobnym obiekcie secret, nigdy w input: wejście zostaje przy zadaniu, a sekret jest szyfrowany i kasowany, gdy tylko zadanie się skończy.

2. 2. Śledź je

   Odpytuj GET /api/jobs/:id albo otwórz strumień i odbieraj kroki, gdy się dzieją:

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

   Strumień to Server-Sent Events, a każde zdarzenie niesie id. Jeśli połączenie padnie, podłącz się z ?desde=<ostatnie id> i dostaniesz to, co ominęło, zamiast zaczynać od zera. Klucz idzie tutaj w URL-u, a nie w nagłówku, bo klient SSE nie może go wysłać — tym bardziej warto wiedzieć, że URL z kluczem ląduje w logach dostępu.

3. 3. Zabierz wynik

   Przychodzi w result, gdy zadanie jest done. Narzędzia, które produkują pliki, dokładają:

   GET /api/jobs/:id/export/:format  raport — /api/tools wypisuje formaty
   GET /api/jobs/:id/files           co powstało, w postaci listy
   GET /api/jobs/:id/files/<path>    jeden z nich
   GET /api/jobs/:id/download.zip    wszystkie razem

   Wszystkie cztery chcą klucza, tak jak reszta rzeczy związanych z tym zadaniem.

Reszta

GET  /api/health            czy usługa działa i czy kolejka się rusza
GET  /api/tools             katalog: limity darmowego progu i formaty
GET  /api/me                twój plan i to, co już zużyłeś
POST /api/jobs/:id/cancel   zatrzymać takie, które jeszcze trwa
POST /api/mailtest          jednorazowy adres, na który wysyłasz wiadomość (zwraca też klucz)
GET  /api/mailtest/:id      czy dotarła i które zadanie ją oceniło (wymaga tego klucza)
POST /api/monitors          obserwować IP, certyfikat, domenę albo jej DNS
GET  /api/monitors          co obserwujesz i co się zmieniło
DELETE /api/monitors/:id    przestać obserwować
GET  /api/ip                adres, z którego widzi cię ten serwer, wraz z jego odwrotnym DNS
GET  /api/ip/plain          to samo, jedna linia, bez JSON-a do rozbierania — do terminala
GET  /api/is-it-down?url=…  czy ta strona nie działa, czy to ty — sprawdzone stąd
GET  /api/speed             ile może wydać test prędkości i ile z tego zostało
GET  /api/speed/down        bajty do pomiaru; POST /api/speed/up w drugą stronę

Jak wygląda błąd

Każdy błąd odpowiada JSON-em z error: zdaniem po angielsku, napisanym do czytania z terminala. Niektóre niosą też code — stabilny identyfikator przeznaczony dla programów, żeby klient mógł decydować bez analizowania prozy. Rozgałęziaj po code, gdy jest, a pokazuj error, gdy go nie ma.

Kody, które istnieją dzisiaj:

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

Co znaczą kody

Raport w języku twojego użytkownika

Dodaj ?lang=, a to, co pisze narzędzie, wróci przetłumaczone: wynik każdej kontroli, postęp, dziennik i powód, dla którego zadanie się nie powiodło. Dziewięć języków; bez tego angielski.

GET /api/jobs/:id?lang=de                 raport, przetłumaczony
GET /api/jobs/:id/stream?lang=de          postęp i dziennik, na bieżąco
GET /api/jobs/:id/export/:format?lang=de  plik, który pobierasz, przetłumaczony

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

Zmienia się tylko tekst. Kod błędu jest ten sam we wszystkich dziewięciu — to po nim rozgałęziasz kod, a komunikat to ten, który można pokazać bez zmian. Accept-Language jest pomijany celowo: to język przeglądarki, a nie strony, którą czyta twój użytkownik, i mieszanie ich wstawia hiszpańskie zdania do angielskiego raportu.

Narzędzia i to, co daje darmowy tor

Limity czytane są na żywo z /api/tools, nie są tu wpisane: katalog przepisany ręcznie dezaktualizuje się przy pierwszym dodanym narzędziu.

Dwie rzeczy warte wiedzy

• · Poświadczeniem jest klucz zadania, nie identyfikator. Wydaje się raz, przy tworzeniu, a my trzymamy tylko odcisk. Kto go ma, czyta ten raport aż wygaśnie — traktuj klucz jak sam raport.
• · Wyniki wygasają. Pobierz, czego potrzebujesz; potem znika też wejście, nie tylko wyjście.