> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL. Source: https://domscan.net/es/docs/response-format # Formato de respuesta API de DomScan: Todas las respuestas son JSON. Cada resultado de dominio incluye estos campos comunes: Todas las respuestas son JSON. Cada resultado de dominio incluye estos campos comunes: - `domain` - Nombre de dominio completo - `available` - Estado booleano de disponibilidad - `source` - "rdap" o "cache" - `checked_at` - Marca temporal ISO 8601 - `error` - Presente si se produjo un error ### Metadatos de respuesta Cada respuesta de la API incluye un ID de solicitud y un valor de actualidad. Cuando están disponibles, los encabezados de respuesta también muestran los créditos solicitados, cobrados, reembolsados y restantes, además de tu plan de límite de solicitudes, límite, capacidad restante y política. Un valor de actualidad de `unknown` significa que no se pudo establecer la actualidad de esa respuesta. No significa que los datos estén actualizados. ### Selección de campos y respuestas compactas Añade `fields` o `compact` a la query string de cualquier solicitud GET o POST para recibir una respuesta JSON más pequeña. Ambos son opcionales. En las solicitudes POST van en la query string, no en el cuerpo. Ninguno modifica el coste en créditos. #### Seleccionar campos `fields` acepta rutas de puntos separadas por comas, como `fields=domain,classification.status,records.data`. Cuando una ruta atraviesa una lista, se aplica a cada elemento. Los elementos conservan su posición, y un elemento sin ningún campo seleccionado pasa a ser `{}`. Un valor nulo a lo largo de una ruta se conserva como nulo. Envía hasta 50 rutas, cada una con hasta 6 segmentos de entre 1 y 64 letras, dígitos o guiones bajos. Cualquier otro valor devuelve 400 INVALID_PARAMETER antes de ejecutar la solicitud, por lo que no se cobra nada. Las rutas que no coinciden con nada en la respuesta se omiten y se indican en la cabecera de respuesta `X-Fields-Ignored`, hasta un máximo de 20 rutas. #### Respuestas compactas `compact=true` elimina únicamente lo siguiente, y solo en el nivel superior de la respuesta: - En el objeto `meta`: `served_by` y las claves de tiempo `duration_ms`, `query_time_ms`, `total_ms`, `total_time_ms`, `latency_ms`, `generation_ms` y `check_duration_ms`. El propio objeto `meta` se elimina cuando no queda nada más en él. - `warnings`, `caveats`, `notes` y `errors` cuando son listas vacías. - `request_id` cuando repite la cabecera `X-Request-Id`. Los campos de datos, `classification`, los objetos anidados y los elementos de lista nunca se eliminan. Si se envían ambos parámetros, compact se ejecuta primero y fields después. Solo se reestructuran las respuestas JSON correctas. Las respuestas de error, las respuestas CSV, de texto y en streaming, y las estimaciones de `dry_run` se devuelven sin cambios. Las respuestas reestructuradas se envían sin sangría. Con una `Idempotency-Key`, `fields` y `compact` forman parte de la solicitud. Un reintento con los mismos valores devuelve la respuesta reestructurada almacenada. Reutilizar la clave con valores distintos devuelve 422 IDEMPOTENCY_KEY_REUSED. Las herramientas MCP aceptan los mismos argumentos opcionales `fields` y `compact`. Las rutas sin coincidencias se indican en `_meta.fields_ignored` del resultado de la herramienta. #### Ejemplo ```bash curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/dns?domain=google.com&type=TXT&fields=domain,status,records.data,records.ttl,owner&compact=true" X-Fields-Ignored: owner { "domain": "google.com", "records": [ { "data": "v=spf1 include:_spf.google.com ~all", "ttl": 300 }, { "data": "google-site-verification=abc123", "ttl": 300 } ], "status": "success" } ``` ### Claves snake_case (naming) La mayoría de las claves de respuesta ya están en snake_case, pero algunos endpoints devuelven ciertas claves en camelCase, como `registrarName` en los resultados de precios, `tldTier` en los factores de valoración y `eventDate` en los eventos RDAP. Añade `naming=snake` a la cadena de consulta, o envía la cabecera `DomScan-Naming: snake`, para recibir todas esas claves en snake_case. Sin ello, las respuestas conservan sus claves actuales. Una clave solo cambia si empieza por una letra minúscula, contiene únicamente letras y dígitos y tiene al menos una mayúscula. Cada palabra nueva recibe un guion bajo y la clave se pasa a minúsculas. Las siglas permanecen juntas, incluidas `IPv4` y plurales como `IPs`: `registrarName` pasa a ser `registrar_name`, `secureDNS` pasa a ser `secure_dns`, `ipv4Address` pasa a ser `ipv4_address` y `nameserverIPs` pasa a ser `nameserver_ips`. Las claves que son datos y no nombres de campo conservan su ortografía exacta, por ejemplo los tipos de registro DNS como `A` y `MX`, las calificaciones como `A+`, los nombres de dominio, los nombres de cabeceras y los nombres de tecnologías. Los valores nunca se modifican, y los objetos y listas anidados se convierten en todos los niveles. Si un objeto ya tiene el nombre en snake_case, por ejemplo `fooBar` y `foo_bar` a la vez, `foo_bar` conserva su valor y `fooBar` mantiene su nombre original, de modo que no se pierde nada. El orden de las claves no cambia. El parámetro de consulta prevalece sobre la cabecera, así que `naming=default` desactiva la activación por cabecera en una sola solicitud. Los valores aceptados son `snake` y `default`. Cualquier otro valor devuelve 400 INVALID_PARAMETER antes de ejecutar la solicitud, por lo que no se cobra nada. Las respuestas incluyen `Vary: DomScan-Naming`. `naming` se aplica antes que `compact` y `fields`, así que escribe las rutas de `fields` en snake_case, por ejemplo `fields=factors.tld_tier`. Las respuestas de error ya están en snake_case y nunca cambian, y el coste en créditos es el mismo. Con una `Idempotency-Key`, la elección de nomenclatura forma parte de la solicitud, tanto si procede del parámetro como de la cabecera, por lo que un reintento devuelve las mismas claves. Las herramientas MCP aceptan el mismo argumento opcional `naming`. Las llamadas MCP no leen la cabecera. ```bash curl -H "X-API-Key: $DOMSCAN_API_KEY" -H "DomScan-Naming: snake" "https://domscan.net/v1/value?domain=example.com&fields=domain,factors.tld_tier,factors.has_hyphens" { "domain": "example.com", "factors": { "tld_tier": "premium", "has_hyphens": false } } ``` ### Control de frescura (max_age) Los endpoints que pueden responder con datos comprobados recientemente aceptan `max_age`, un número entero de segundos de 0 a 2592000 (30 días). Los datos más antiguos que `max_age` se vuelven a comprobar antes de devolverse, y `max_age=0` siempre comprueba de nuevo. Sin `max_age`, cada endpoint mantiene su comportamiento habitual. Toda respuesta correcta de estos endpoints incluye un `cache_age_s` de nivel superior: la antigüedad en segundos de los datos utilizados, o 0 cuando se comprobaron de nuevo. El mismo valor se envía en la cabecera de respuesta `X-Cache-Age`. Cuando una respuesta contiene varios elementos, como una comprobación de disponibilidad de varios dominios, es la antigüedad del elemento más antiguo, y los elementos conservan su propio `cache_age_s` donde ya lo tenían. `max_age` nunca cambia cómo se clasifica un resultado. Un resultado que no pudo confirmarse sigue siendo `unknown` por reciente que sea, y los datos recientes nunca se muestran como presentes o ausentes a menos que la comprobación original lo confirmara. `max_age` no cambia el coste de una petición. Una comprobación nueva y una respuesta con datos recientes cuestan los mismos créditos. En `/v1/status` y `/v1/status/bulk`, las comprobaciones nuevas forzadas (`max_age=0`) están limitadas por cliente para proteger los registros. Superado ese límite, la petición se responde como si no se hubiera enviado `max_age`, y `cache_age_s` muestra la antigüedad de lo que recibiste. Un `max_age` que no sea un número entero de 0 a 2592000 devuelve 400 INVALID_PARAMETER antes de ejecutar la petición, por lo que no se cobra nada. Endpoints que aceptan `max_age`: `GET /v1/status`, `POST /v1/status/bulk`, `GET /v1/subdomains`, `GET /v1/certificates`, `GET /v1/tech`, `GET /v1/categorize`, `GET /v1/identity-assets`, `GET /v1/identity-resolution`, `GET /v1/url-intelligence`, `GET /v1/agent-readiness`, `GET /v1/robots`, `GET /v1/ssl/deep-scan` #### Parámetros de caché anteriores Estos parámetros siguen funcionando y ahora son alias obsoletos de `max_age`. Si envías también `max_age`, prevalece `max_age`. | Parámetro | Endpoints | Equivale a | | --- | --- | --- | | `prefer_cache` | `/v1/status`, `/v1/subdomains` | `max_age=2592000` | | `skip_cache` | `/v1/status`, `/v1/tech`, `/v1/categorize`, `/v1/identity-assets`, `/v1/identity-resolution`, `/v1/url-intelligence`, `/v1/agent-readiness`, `/v1/robots` | `max_age=0` | | `cache_skip` | `/v1/status` | `max_age=0` | | `cache-skip` | `/v1/status` | `max_age=0` | | `options.prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` | | `prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` | | `options.skip_cache (body)` | `/v1/status/bulk` | `max_age=0` | | `options.cache_skip (body)` | `/v1/status/bulk` | `max_age=0` | | `options.cache-skip (body)` | `/v1/status/bulk` | `max_age=0` | | `refresh` | `/v1/ssl/deep-scan` | `max_age=0` | En `/v1/subdomains`, `prefer_cache` también conserva su comportamiento de solo caché: cuando aún no hay nada almacenado, la petición devuelve 202 sin cobrar e inicia la consulta en segundo plano. Las herramientas MCP de estos endpoints aceptan el mismo argumento opcional `max_age`, y sus resultados incluyen `cache_age_s`. ### Paginación (limit y cursor) Los endpoints que devuelven listas largas aceptan `limit` y `cursor`, y toda respuesta incluye `has_more` y `next_cursor`. Para obtener la página siguiente, repite la petición con `cursor` igual a `next_cursor`. En la última página, `has_more` es false y `next_cursor` es null. Sin `limit`, cada endpoint devuelve el mismo número de elementos que antes, así que las peticiones existentes no cambian. Puedes cambiar `limit` de una página a otra. Los cursores son opacos y están firmados. Un cursor solo funciona para la cuenta que lo recibió y para la misma consulta, por ejemplo el mismo dominio y los mismos filtros. Un cursor modificado, de otra cuenta o enviado con filtros distintos devuelve 400 INVALID_CURSOR. Las páginas siguen un orden estable, así que los elementos añadidos o eliminados entre peticiones no se repiten ni se omiten. En los endpoints de historial, los campos de resumen describen los elementos de la página actual. Cada página es una petición normal y cuesta los créditos habituales del endpoint, igual que una petición con `limit` antes. Los endpoints gratuitos siguen siendo gratuitos. Los parámetros anteriores siguen funcionando: `offset` en `/v1/email/blacklist` y el `pagination.next_cursor` numérico en `/v1/certificates`. | Endpoint | Tamaño de página por defecto | Límite máximo | | --- | --- | --- | | `GET /v1/whois/history` | 50 | 100 | | `GET /v1/dns/history` | 100 | 1000 | | `GET /v1/subdomains` | 500 | 2000 | | `GET /v1/certificates` | 100 | 1000 | | `GET /v1/watchlist` | Lista completa | 100 | | `GET /v1/watchlist/expiring` | Lista completa | 100 | | `GET /v1/watchlist/available` | Lista completa | 100 | | `GET /v1/brand-monitor` | Lista completa | 100 | | `GET /v1/email/blacklist` | 1000 | 10000 | #### Ejemplo ```bash curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20" { "domain": "example.com", "snapshots": [ "..." ], "has_more": true, "next_cursor": "eyJvIjoi..." } curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20&cursor=eyJvIjoi..." ``` ### Estado de clasificación Los endpoints que indican si algo existe (registro de dominios, nombres de usuario en redes sociales, registros DNS y de autenticación de correo, security.txt, robots.txt, sitemaps, cabeceras de seguridad, aparcamiento, registros typosquat y certificados SSL) añaden un objeto `classification` junto a sus campos actuales. Los campos existentes conservan su nombre y significado. - `status` - `present`, `absent` o `unknown`. Present y absent solo se devuelven cuando la comprobación obtuvo evidencia exacta y fiable. - `reason` - Solo se devuelve cuando el estado es `unknown`. Explica por qué no fue posible dar una respuesta definitiva. - `evidence` - De dónde procede la respuesta: `source`, `method`, `observed_at` y un `detail` opcional, como `http_404` o `nxdomain`. - `checked_at` - Cuándo generó DomScan la clasificación. En resultados en caché, `evidence.observed_at` es anterior. #### Motivos de unknown - `blocked` - El destino denegó el acceso, por ejemplo con HTTP 401, 403 o un desafío anti-bots. - `rate_limited` - El destino o el registro nos pidió reducir el ritmo, por ejemplo con HTTP 429. - `timeout` - La comprobación no terminó dentro de su límite de tiempo. - `ambiguous` - Llegó una respuesta, pero no demostró presencia ni ausencia, por ejemplo un código de estado inesperado o un registro mal formado. - `upstream_error` - Falló la fuente de datos, por ejemplo un fallo del servidor DNS o una respuesta HTTP 5xx. - `unsupported` - Esta comprobación no está disponible para la entrada, por ejemplo un TLD no admitido o una plataforma sin un verificador fiable. ```json { "classification": { "status": "unknown", "reason": "rate_limited", "evidence": { "source": "rdap", "method": "rdap_lookup", "observed_at": "2026-10-10T09:30:00.000Z", "detail": "http_429" }, "checked_at": "2026-10-10T09:30:00.000Z" } } ``` Una comprobación bloqueada, limitada, agotada por tiempo o fallida nunca se informa como absent. Trata `unknown` como «inténtalo más tarde» y no como «no existe», y nunca interpretes la ausencia como prueba de que un nombre se pueda reclamar. #### Puntuaciones y calificaciones con comprobaciones desconocidas Las puntuaciones nunca cuentan una comprobación desconocida como ausente. La puntuación de seguridad DNS y la calificación de autenticación de correo dejan fuera las comprobaciones desconocidas, las indican en `checks_unknown` y establecen `score_confidence` en `partial`. Cuando todas las comprobaciones son desconocidas, la puntuación y la calificación son `null`. La calificación y la puntuación SSL son `null` con `grade_reason` establecido en `certificate_not_retrieved` cuando no se pudo leer ningún certificado, y la puntuación de reputación informa el aparcamiento desconocido como `null` en lugar de no aparcado.