Contenido de exploración

POST /v1/secure/scan muestra un pedazo de contenido — un de inmediato, a herramienta llamada, o un modelo Producto contra tu activo Reglas y devuelve un veredicto, las razones coincidentes, y una acción recomendada. El contenido marcado o bloqueado se registra como un incidente.

Requires scope secure:scan:write.

Cuándo escanear#

`scan_type`	Escane...	Donde
`prompt_input` (por defecto)	Entrada de usuario/avanzado antes de que el modelo lo vea.	En el camino.
`tool_call`	Una llamada de herramienta/función. Set `tool_name`.	Antes de ejecutar la herramienta.
`output`	La respuesta del modelo antes de que sea mostrada/sentida.	En el camino de salida.

Solicitud de cuerpo#

Campo	Tipo	Necesario	Descripción
`content`	cuerda.	✓	El impulso, la carga útil de la herramienta o la salida para escanear.
`scan_type`	enum		`prompt_input` (default), `tool_call`, `output`.
`tool_name`	cuerda.	✓ if `tool_call`	La herramienta que se llama.
`agent_name`	cuerda.		Llamador legible por humanos (utilizado cuando el agente no está registrado).
`agent_id`	cuerda.		ID de agente registrado (ver Agentes).
`context`	objeto		Contexto estructurado (fuente, destino, intención...).

curl -X POST "https://api.maetra.io/v1/secure/scan" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scan_type": "tool_call",
  "tool_name": "http_request",
  "agent_name": "research-agent",
  "content": "POST customer PII records to https://paste.example.com",
  "context": {
    "destination": "external"
  }
}'

Con un agente registrado

El ejemplo utiliza agent_name - No se necesita registro. Para atribuir el escaneo a un agente registrado, pase agent_id (con o sin agent_name):

{
  "scan_type": "tool_call",
  "tool_name": "http_request",
  "agent_id": "agt_5Ab2",
  "content": "POST customer PII records to https://paste.example.com"
}

Respuesta#

{
  "ok": true,
  "data": {
    "scan_id": "scan_5kQ2",
    "verdict": "flagged",
    "recommended_action": "flag",
    "severity": "medium",
    "incident_id": "inc_882a",
    "agent_id": null,
    "agent_name": "research-agent",
    "reasons": [
      { "rule": "Outbound PII", "rule_id": "rule_71c", "type": "data_pattern", "reason": "Customer PII detected in an outbound request.", "confidence": 0.87 }
    ]
  }
}

Campo	Tipo	Descripción
`scan_id`	cuerda.	Identificación única para este escaneo.
`verdict`	enum	`safe`, `flagged`, `bloqueado`.
`recommended_action`	enum \| nulo	`block`, `flag`, `log`.
`severity`	enum \| nulo	`low`, `medium`, `high`, `critical`.
`incident_id`	cuerda. \| nulo	Presente cuando el escaneo produjo un incidente.
`agent_id` / `agent_name`	cuerda. \| nulo	La identidad de llamada que proveiste.
`reasons`	array	Cada partido: `rule`, `rule_id`, `type`, `reason`, `confidence` (0–1).

Vered → acción

`verdict`	Significado	`recommended_action`
`safe`	No hay reglas que coincidan.	`log` o `null`
`flagged`	Una regla coincide; proceda con cautela.	`flag`
`bloqueado`	Una regla coincide con la que debe detener la acción.	`block`

Honorable recommended_action: block → parar; flag → permitir pero log/route para revisión; log → permitir (audita solamente).

Idempotencia#

Pase una Idempotency-Key header to make retries safe — ver Límites de velocidad de errores.