La API

Todo lo que hace la web lo hace por esta API — no hay otra privada. Cinco herramientas, una sola forma: creas un trabajo, lo sigues y te llevas el resultado. Sin clave vas por el carril gratuito; con ella, con los topes altos.

Dónde vive

https://bigitools.com

Tu clave

Vale cualquiera de las dos cabeceras, la que le venga mejor a tu cliente:

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

Una clave que no reconoce da un 401 a propósito: NO cae en silencio al carril gratuito. Si te equivocas al copiarla, te enteras en la primera llamada y no cuando te choca un tope que no te tocaba.

Un trabajo, de principio a fin

1. 1. Créalo

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

   Guarda la clave: se entrega UNA vez y no la podemos reenviar. Leer el trabajo, sus ficheros y cancelarlo la necesitan — mándala como X-Job-Key, o como ?key= donde no se pueda poner una cabecera. Solo guardamos su huella, así que una clave perdida es un trabajo al que ya no puedes llegar; de todas formas caduca con el informe. Si el trabajo se creó con la clave de API de una cuenta, esa también lo abre y puedes olvidarte de ésta.

   Las herramientas que necesitan credenciales las reciben en un objeto secret aparte, nunca dentro de input: la entrada se guarda con el trabajo y el secreto se cifra y se borra en cuanto el trabajo termina.

2. 2. Síguelo

   Pregunta por GET /api/jobs/:id, o abre el flujo y recibe los pasos según pasan:

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

   El flujo son Server-Sent Events y cada evento lleva su id. Si se te corta, reconecta con ?desde=<último id> y recibes lo que te perdiste en vez de empezar de cero. Aquí la clave va en la URL y no en una cabecera, porque un cliente de SSE no puede mandar cabeceras — que es también por lo que conviene saber que una URL con clave dentro acaba en los registros de acceso.

3. 3. Llévate el resultado

   Llega en result cuando el trabajo está done. Las herramientas que producen ficheros añaden:

   GET /api/jobs/:id/export/:format  el informe — /api/tools lista los formatos
   GET /api/jobs/:id/files           lo que se ha generado, en lista
   GET /api/jobs/:id/files/<path>    uno de ellos
   GET /api/jobs/:id/download.zip    todos a la vez

   Las cuatro quieren la clave, igual que todo lo demás de ese trabajo.

Lo demás

GET  /api/health            ¿está el servicio en pie y se mueve la cola?
GET  /api/tools             el catálogo: límites del carril gratuito y formatos
GET  /api/me                tu plan y lo que llevas gastado
POST /api/jobs/:id/cancel   parar uno que siga en marcha
POST /api/mailtest          una dirección de un solo uso a la que mandar un mensaje (devuelve clave)
GET  /api/mailtest/:id      si ha llegado, y qué trabajo la ha puntuado (hace falta esa clave)
POST /api/monitors          vigilar una IP, un certificado, un dominio o su DNS
GET  /api/monitors          qué estás vigilando y qué ha cambiado
DELETE /api/monitors/:id    dejar de vigilar
GET  /api/ip                la dirección desde la que te ve este servidor, con su DNS inverso
GET  /api/ip/plain          lo mismo, en una línea, sin JSON que interpretar — para la terminal
GET  /api/is-it-down?url=…  ¿está caída esa web, o eres tú? — mirado desde aquí
GET  /api/speed             lo que puede gastar el test de velocidad y lo que queda
GET  /api/speed/down        bytes con los que medir; POST /api/speed/up para el otro sentido

Cómo es un error

Todo error contesta JSON con error: una frase en inglés, escrita para leerse desde una terminal. Algunos llevan además code, un identificador estable pensado para programas, para que un cliente pueda decidir sin analizar prosa. Ramifica por code cuando esté, y enseña error cuando no.

Los códigos que existen hoy:

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

Qué significa cada código

El informe, en el idioma de tu usuario

Añade ?lang= y lo que escribe el motor vuelve traducido: lo que dice cada comprobación, el progreso, el registro y el motivo por el que un trabajo ha fallado. Nueve idiomas; inglés si no lo pones.

GET /api/jobs/:id?lang=de                 el informe, traducido
GET /api/jobs/:id/stream?lang=de          progreso y registro, según pasan
GET /api/jobs/:id/export/:format?lang=de  el fichero que te bajas, traducido

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

Solo cambia el texto. El código de un error es el mismo en los nueve —ese es el que se mira para decidir, y el mensaje el que se puede enseñar tal cual—. Accept-Language se ignora a propósito: ese es el idioma del navegador, no el de la página que está leyendo tu usuario, y mezclarlos mete frases en castellano dentro de un informe en inglés.

Las herramientas, y lo que te da el carril gratuito

Los topes se leen en vivo de /api/tools, no están escritos aquí: un catálogo escrito a mano se desfasa la primera vez que alguien añade una herramienta.

Dos cosas que conviene saber

• · La credencial es la clave del trabajo, no el identificador. Se entrega una vez al crearlo y de ella solo guardamos una huella. Quien la tenga lee ese informe hasta que caduque, así que trata la clave como al informe mismo.
• · Los resultados caducan. Descarga lo que necesites; después se va también la entrada, no solo la salida.