L’API

Tutto quello che fa il sito lo fa da questa API — non ce n’è una privata. Cinque strumenti, una sola forma: crei un lavoro, lo segui, ti prendi il risultato. Senza chiave vai sul piano gratuito; con la chiave, sui limiti alti.

Non c’è ancora registrazione, quindi non ci sono chiavi da dare: tutto qui sotto va sul piano gratuito, che non richiede account. Le intestazioni della chiave sono documentate perché l’API le accetta già.

Dove sta

https://bigitools.com

La tua chiave

Vanno bene entrambe le intestazioni, quella che è più comoda per il tuo client:

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

Una chiave che non riconosce prende un 401, di proposito: NON ricade in silenzio sul piano gratuito. Se la copi male te ne accorgi alla prima chiamata e non quando ti sbatte contro un limite che non ti spettava.

Un lavoro, dall’inizio alla fine

1. Crealo
```
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…" }
```
Conserva la chiave: si consegna UNA volta e non possiamo rimandarla. Leggere il lavoro, i suoi file e annullarlo la richiedono tutti — mandala come X-Job-Key, o come ?key= dove non si può mettere un’intestazione. Ne conserviamo solo l’impronta, quindi una chiave persa è un lavoro che non puoi più raggiungere; comunque scade con il report. Se il lavoro è stato creato con la chiave API di un account, apre anche quella e questa puoi dimenticarla.
Gli strumenti che richiedono credenziali le ricevono in un oggetto secret a parte, mai dentro input: l’input resta col lavoro e il segreto viene cifrato e cancellato appena il lavoro finisce.
2. Seguilo
Interroga GET /api/jobs/:id, oppure apri lo stream e ricevi i passi mentre accadono:
```
curl -N "$API/api/jobs/cm…/stream?key=n7Qk…"
```
Lo stream sono Server-Sent Events e ogni evento porta un id. Se cade, riconnettiti con ?desde=<ultimo id> e ricevi quello che ti sei perso invece di ricominciare. Qui la chiave va nell’URL e non in un’intestazione, perché un client SSE non può mandarne — motivo in più per sapere che una URL con la chiave dentro finisce nei registri di accesso.

3. Prenditi il risultato

Arriva in result quando il lavoro è done. Gli strumenti che producono file aggiungono:

GET /api/jobs/:id/export/:format  il rapporto — /api/tools elenca i formati
GET /api/jobs/:id/files           ciò che è stato prodotto, in elenco
GET /api/jobs/:id/files/<path>    uno di essi
GET /api/jobs/:id/download.zip    tutti insieme

Tutti e quattro vogliono la chiave, come tutto il resto di quel lavoro.

Il resto

GET  /api/health            il servizio è in piedi, e la coda si muove
GET  /api/tools             il catalogo: limiti del piano gratuito e formati
GET  /api/me                il tuo piano e quanto hai consumato
POST /api/jobs/:id/cancel   fermarne uno ancora in corso
POST /api/mailtest          un indirizzo usa e getta a cui mandare un messaggio (restituisce anche una chiave)
GET  /api/mailtest/:id      se è arrivato, e quale lavoro lo ha valutato (serve quella chiave)
POST /api/monitors          sorvegliare un IP, un certificato, un dominio o il suo DNS
GET  /api/monitors          che cosa stai sorvegliando, e che cosa è cambiato
DELETE /api/monitors/:id    smettere di sorvegliare
GET  /api/ip                l’indirizzo da cui questo server ti vede, con il suo DNS inverso
GET  /api/ip/plain          lo stesso, una riga, senza JSON da interpretare — per il terminale
GET  /api/is-it-down?url=…  quel sito è giù, o sei tu — controllato da qui
GET  /api/speed             quanto può spendere il test di velocità e quanto ne resta
GET  /api/speed/down        byte con cui misurare; POST /api/speed/up per l’altro verso

Com’è fatto un errore

Ogni errore risponde in JSON con error: una frase in inglese, scritta per essere letta da un terminale. Alcuni portano anche code, un identificatore stabile pensato per i programmi, così un client può decidere senza analizzare prosa. Ramifica su code quando c’è, e mostra error quando non c’è.

I codici che esistono oggi:

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

Cosa significano i codici

400	La richiesta è sbagliata, e il messaggio dice cosa cambiare — non il nome di una nostra variabile.
401	La chiave non è riconosciuta, o non ha il formato atteso.
402	Funzione a pagamento. È il monitoraggio a rispondere così.
403	Quel lavoro non è tuo: lo apre la chiave consegnata alla creazione.
404	Non esiste quel lavoro, o è scaduto. I risultati non restano per sempre.
409	Lo stai già monitorando, e allo stesso modo.
413	Il corpo supera il limite.
429	Un limite — e il messaggio dice QUALE, così sai se aspettare un minuto o un giorno.
503	Qualcosa da cui dipende lo strumento non sta rispondendo adesso.

Il referto, nella lingua del tuo utente

Aggiungi ?lang= e quello che scrive il motore torna tradotto: cosa dice ogni controllo, l’avanzamento, il registro e il motivo per cui un lavoro è fallito. Nove lingue; inglese se non lo metti.

GET /api/jobs/:id?lang=de                 il rapporto, tradotto
GET /api/jobs/:id/stream?lang=de          avanzamento e registro, mentre accadono
GET /api/jobs/:id/export/:format?lang=de  il file che scarichi, tradotto

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

Cambia solo il testo. Il codice di un errore è lo stesso in tutte e nove — su quello si decide, e il messaggio è quello che si può mostrare così com’è. Accept-Language viene ignorato di proposito: è la lingua del browser, non quella della pagina che il tuo utente sta leggendo, e mescolarle mette frasi in spagnolo dentro un referto in inglese.

Gli strumenti, e cosa ti dà il piano gratuito

I limiti si leggono dal vivo da /api/tools, non sono scritti qui: un catalogo scritto a mano invecchia alla prima herramienta aggiunta.

Sto chiedendo all’API…

Due cose da sapere

· La credenziale è la chiave del lavoro, non l’id. Si consegna una volta alla creazione e di essa conserviamo solo un’impronta. Chi ce l’ha legge quel report finché non scade: trattala come il report stesso.
· I risultati scadono. Scarica quello che ti serve; dopo se ne va anche l’input, non solo l’output.