API-ul

Tot ce face site-ul, face prin acest API — unul privat nu există. Cinci instrumente, o singură formă: creezi o sarcină, o urmărești, iei rezultatul. Fără cheie mergi pe nivelul gratuit; cu ea, pe limitele mari.

Unde stă

https://bigitools.com

Cheia ta

Merge oricare dintre cele două anteturi, cel care îi vine mai ușor clientului tău:

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

O cheie pe care nu o recunoaște primește un 401, intenționat: NU cade în tăcere pe nivelul gratuit. Dacă o copiezi greșit, afli la primul apel și nu când te lovește o limită care nu ți se cuvenea.

O sarcină, de la cap la coadă

1. 1. Creeaz-o

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

   Păstrează cheia: se dă O singură dată și nu o putem retrimite. Citirea sarcinii, fișierele ei și anularea o cer toate — trimite-o ca X-Job-Key, sau ca ?key= acolo unde un antet nu e posibil. Păstrăm doar amprenta ei, așa că o cheie pierdută înseamnă o sarcină la care nu mai ajungi; oricum expiră odată cu raportul. Dacă sarcina a fost creată cu cheia API a unui cont, o deschide și aceea și de asta poți uita.

   Instrumentele care au nevoie de date de acces le primesc într-un obiect secret separat, niciodată în input: intrarea rămâne cu sarcina, iar secretul se criptează și se șterge în clipa în care sarcina se termină.

2. 2. Urmărește-o

   Interoghează GET /api/jobs/:id, sau deschide fluxul și primești pașii pe măsură ce se întâmplă:

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

   Fluxul e Server-Sent Events, iar fiecare eveniment poartă un id. Dacă pică, reconectează-te cu ?desde=<ultimul id> și primești ce ai pierdut în loc să o iei de la capăt. Cheia merge aici în URL și nu într-un antet, fiindcă un client SSE nu poate trimite anteturi — cu atât mai util de știut că un URL cu cheia în el ajunge în jurnalele de acces.

3. 3. Ia rezultatul

   Vine în result când sarcina e done. Instrumentele care produc fișiere adaugă:

   GET /api/jobs/:id/export/:format  raportul — /api/tools listează formatele
   GET /api/jobs/:id/files           ce s-a produs, ca listă
   GET /api/jobs/:id/files/<path>    unul dintre ele
   GET /api/jobs/:id/download.zip    toate la un loc

   Toate patru vor cheia, la fel ca tot restul legat de sarcina aceea.

Restul

GET  /api/health            merge serviciul și se mișcă coada
GET  /api/tools             catalogul: limitele nivelului gratuit și formatele
GET  /api/me                planul tău și cât ai consumat
POST /api/jobs/:id/cancel   oprește unul care încă rulează
POST /api/mailtest          o adresă de unică folosință către care trimiți un mesaj (întoarce și o cheie)
GET  /api/mailtest/:id      dacă a ajuns, și ce sarcină a evaluat-o (cere acea cheie)
POST /api/monitors          urmărește un IP, un certificat, un domeniu sau DNS-ul lui
GET  /api/monitors          ce urmărești și ce s-a schimbat
DELETE /api/monitors/:id    oprește urmărirea
GET  /api/ip                adresa de la care te vede acest server, cu DNS-ul ei invers
GET  /api/ip/plain          la fel, o singură linie, fără JSON de interpretat — pentru terminal
GET  /api/is-it-down?url=…  e căzut site-ul acela, sau ești tu — verificat de aici
GET  /api/speed             cât poate cheltui testul de viteză și cât a mai rămas
GET  /api/speed/down        octeți cu care să măsori; POST /api/speed/up pentru celălalt sens

Cum arată o eroare

Orice eroare răspunde în JSON cu error: o frază în engleză, scrisă ca să fie citită dintr-un terminal. Unele poartă și code, un identificator stabil gândit pentru programe, ca un client să poată decide fără să analizeze proză. Ramifică după code când există, și arată error când nu.

Codurile care există azi:

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 înseamnă codurile

Raportul, în limba utilizatorului tău

Adaugă ?lang= și ce scrie unealta se întoarce tradus: ce spune fiecare verificare, progresul, jurnalul și motivul pentru care o sarcină a eșuat. Nouă limbi; engleză dacă nu pui nimic.

GET /api/jobs/:id?lang=de                 raportul, tradus
GET /api/jobs/:id/stream?lang=de          progresul și jurnalul, pe măsură ce se întâmplă
GET /api/jobs/:id/export/:format?lang=de  fișierul pe care îl descarci, tradus

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

Se schimbă doar textul. Codul unei erori este același în toate nouă — după el se decide, iar mesajul este cel care se poate arăta așa cum vine. Accept-Language este ignorat intenționat: este limba browserului, nu a paginii pe care o citește utilizatorul tău, iar amestecul lor pune fraze în spaniolă într-un raport în engleză.

Instrumentele și ce îți dă nivelul gratuit

Limitele se citesc live din /api/tools, nu sunt scrise aici: un catalog scris de mână se învechește la primul instrument adăugat.

Două lucruri de știut

• · Credențialul e cheia sarcinii, nu identificatorul. Se dă o dată, la creare, iar noi păstrăm doar o amprentă. Cine o are citește raportul acela până expiră: tratează cheia ca pe raportul însuși.
• · Rezultatele expiră. Descarcă ce îți trebuie; după aceea dispare și intrarea, nu doar ieșirea.