Referencia de API REST

Referencia completa de endpoints para la API de gestión de ShieldAgent. URL base: https://api.shieldagent.io

Autenticación

Todos los endpoints (excepto los marcados como públicos) requieren un token Bearer JWT en el encabezado Authorization. Los tokens se obtienen a través de /auth/login o /auth/signup.

Example

curl https://api.shieldagent.io/tenants \
  -H 'Authorization: Bearer <your-jwt>' \
  -H 'Content-Type: application/json'

Formato de Error

Todas las respuestas de error siguen una estructura JSON consistente. Los errores de validación (400) incluyen detalles a nivel de campo a través de Zod.

Error response

{
  "error": "Validation failed",
  "message": "Invalid request body",
  "issues": [
    { "path": ["name"], "message": "Required" },
    { "path": ["riskTier"], "message": "Invalid enum value" }
  ]
}

400Error de validación — revisar el array issues para detalles de campo

401Encabezado Authorization ausente o inválido

403Token válido pero permisos RBAC insuficientes

404Recurso no encontrado

409Conflicto — recurso duplicado (p. ej., el email ya existe)

429Límite de tasa excedido — ver encabezado Retry-After

Paginación

Los endpoints de lista que soportan paginación aceptan parámetros de consulta limit y offset y retornan un objeto pagination:

Paginated response

{
  "data": [ ... ],
  "pagination": {
    "total": 142,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Autenticación

POST

/auth/signup

Registra un nuevo tenant y usuario administrador. Devuelve un JWT.

Auth:none (public)

Limitado a 5 solicitudes por minuto.

Parameter	In	Type	Required	Description
email	body	string	yes	User email address
password	body	string	yes	Minimum 8 characters
tenantName	body	string	yes	Organization name

Request body

{
  "email": "admin@acme.com",
  "password": "<your-password>",
  "tenantName": "Acme Corp"
}

Response 201

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "u_01abc...", "email": "admin@acme.com", "role": "tenant_admin" },
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

POST

/auth/login

Autentica con email y contraseña. Devuelve un JWT.

Auth:none (public)

Limitado a 10 solicitudes por minuto. Devuelve 403 con el error SSORequired si la cuenta usa SSO.

Parameter	In	Type	Required	Description
email	body	string	yes	User email address
password	body	string	yes	User password

Request body

{
  "email": "admin@acme.com",
  "password": "<your-password>"
}

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "u_01abc...", "email": "admin@acme.com", "role": "tenant_admin" },
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

GET

/auth/me

Obtiene el perfil del usuario actualmente autenticado.

Auth:Bearer token

Response 200

{
  "id": "u_01abc...",
  "email": "admin@acme.com",
  "role": "tenant_admin",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

POST

/auth/refresh-entitlements

Renueva el JWT con el nivel de plan y derechos actuales.

Auth:Bearer token

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "u_01abc...", "email": "admin@acme.com", "role": "tenant_admin" },
  "tenant": { "id": "t_01xyz...", "name": "Acme Corp" }
}

Tenants

POST

/tenants

Crea una nueva organización tenant.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
name	body	string	yes	Tenant display name
planTier	body	string	no	One of: free, team, starter, pro, business, enterprise_cloud, enterprise_onprem. Defaults to free.
kmsKeyId	body	string	no	Optional KMS key for envelope encryption

Request body

{
  "name": "Acme Corp",
  "planTier": "pro"
}

Response 201

{
  "id": "t_01xyz...",
  "name": "Acme Corp",
  "planTier": "pro",
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants

Lista tenants. Los administradores de plataforma ven todos; el resto solo ve su propio tenant.

Auth:Bearer token|Permission:tenant:read

Response 200

[
  {
    "id": "t_01xyz...",
    "name": "Acme Corp",
    "planTier": "pro",
    "createdAt": "2026-04-24T12:00:00.000Z"
  }
]

GET

/tenants/:tenantId

Obtiene un único tenant por ID.

Auth:Bearer token|Permission:tenant:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

PUT

/tenants/:tenantId

Actualiza campos del tenant.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
name	body	string	no	Updated tenant name
planTier	body	string	no	New plan tier
kmsKeyId	body	string	no	Updated KMS key ID

DELETE

/tenants/:tenantId

Elimina un tenant y todos los datos asociados.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

Response 200

{ "deleted": true, "id": "t_01xyz..." }

Usuarios

GET

/tenants/:tenantId/users

Lista los usuarios de un tenant con sus asignaciones de rol.

Auth:Bearer token|Permission:user:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

Response 200

[
  {
    "id": "u_01abc...",
    "email": "admin@acme.com",
    "role": "tenant_admin",
    "active": true,
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
]

POST

/tenants/:tenantId/users/invite

Invita a un nuevo usuario al tenant.

Auth:Bearer token|Permission:user:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
email	body	string	yes	Email address of the user to invite
password	body	string	yes	Initial password (min 8 characters)
role	body	string	no	One of: tenant_admin, security_operator, auditor, aiops_engineer, viewer. Default: viewer

Request body

{
  "email": "analyst@acme.com",
  "password": "<your-password>",
  "role": "security_operator"
}

Response 201

{
  "id": "u_02def...",
  "email": "analyst@acme.com",
  "role": "security_operator",
  "active": true,
  "createdAt": "2026-04-24T14:00:00.000Z"
}

PATCH

/tenants/:tenantId/users/:userId

Actualiza el rol o el estado activo de un usuario.

Auth:Bearer token|Permission:user:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
userId	path	uuid	yes	User UUID
role	body	string	no	New role assignment
active	body	boolean	no	Set false to deactivate

DELETE

/tenants/:tenantId/users/:userId

Elimina a un usuario del tenant. Los usuarios no pueden eliminarse a sí mismos.

Auth:Bearer token|Permission:user:delete

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
userId	path	uuid	yes	User UUID

GET

/roles

Lista todos los roles disponibles con sus permisos.

Auth:Bearer token

Response 200

[
  {
    "id": "role_01...",
    "name": "security_operator",
    "scope": "tenant",
    "description": "Can triage incidents, manage alert rules, view audit logs",
    "isSystem": true,
    "permissions": ["incident:triage", "alert:write", "audit:read"]
  }
]

Agentes

POST

/tenants/:tenantId/agents

Registra un nuevo agente de IA. Devuelve una clave de agente para la autenticación del proxy.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
name	body	string	yes	Agent display name
description	body	string	no	Agent purpose description
riskTier	body	string	no	Initial risk tier: low, medium, high, critical
shadowMode	body	boolean	no	Start in shadow mode (log only, never block). Default: false

Request body

{
  "name": "code-assistant",
  "description": "GitHub PR review agent",
  "riskTier": "medium"
}

Response 201

{
  "id": "agt_01HXYZ...",
  "name": "code-assistant",
  "agentKey": "eyJ...",
  "riskTier": "medium",
  "shadowMode": false,
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/agents

Lista todos los agentes de un tenant.

Auth:Bearer token|Permission:agent:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID

GET

/tenants/:tenantId/agents/:agentId

Obtiene un único agente con su configuración completa.

Auth:Bearer token|Permission:agent:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	path	uuid	yes	Agent UUID

PATCH

/tenants/:tenantId/agents/:agentId

Actualiza los metadatos del agente (name, description, shadowMode, riskTier).

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	path	uuid	yes	Agent UUID
name	body	string	no	Updated agent name
description	body	string	no	Updated description
shadowMode	body	boolean	no	Toggle shadow mode
riskTier	body	string	no	Updated risk tier

DELETE

/tenants/:tenantId/agents/:agentId

Da de baja a un agente y revoca su clave.

Auth:Bearer token|Permission:agent:delete

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	path	uuid	yes	Agent UUID

Response 200

{ "deleted": true, "id": "agt_01HXYZ..." }

POST

/tenants/:tenantId/agents/:agentId/rotate-key

Rota la clave de API del agente. La clave anterior se revoca de inmediato.

Auth:Bearer token|Permission:agent:write

Response 200

{
  "agentKey": "eyJ_NEW...",
  "rotatedAt": "2026-04-24T12:00:00.000Z"
}

PATCH

/tenants/:tenantId/agents/:agentId/security-config

Configura los ajustes de detección de seguridad por agente.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
injectionDetectionEnabled	body	boolean	no	Enable ML injection detection
dlpEnabled	body	boolean	no	Enable DLP scanning
excessiveAgencyEnabled	body	boolean	no	Enable excessive agency detection
toolDriftEnabled	body	boolean	no	Enable tool drift monitoring

PATCH

/tenants/:tenantId/agents/:agentId/baseline-config

Configura los parámetros de aprendizaje de la línea base.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
warmupDays	body	integer	no	Days before drift detection activates (default: 7)
sensitivityMultiplier	body	number	no	Drift sensitivity (0.5–3.0, default: 1.0)

POST

/tenants/:tenantId/agents/:agentId/lock

Suspende a un agente. Todas las llamadas a herramientas se bloquearán hasta que se desbloquee.

Auth:Bearer token|Permission:agent:write

Parameter	In	Type	Required	Description
reason	body	string	no	Reason for suspension (written to audit trail)

POST

/tenants/:tenantId/agents/:agentId/unlock

Reincorpora a un agente suspendido.

Auth:Bearer token|Permission:agent:write

DELETE

/tenants/:tenantId/agents/:agentId/baseline

Reinicia la línea base de comportamiento de un agente. La puntuación de desviación se reinicia desde cero.

Auth:Bearer token|Permission:agent:write

Response 200

{ "reset": true, "agentId": "agt_01HXYZ..." }

Políticas

POST

/tenants/:tenantId/policies

Crea una regla de política para un tenant, agente o herramienta.

Auth:Bearer token|Permission:policy:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	body	uuid	no	Scope to a specific agent (omit for tenant-wide)
toolName	body	string	yes	Tool pattern to match (supports wildcards)
action	body	string	yes	allow, deny, or shadow
conditions	body	object	no	Optional condition object (method, path, param matchers)
priority	body	integer	no	Evaluation priority (lower = first). Default: 100.

Request body

{
  "agentId": "agt_01HXYZ...",
  "toolName": "rest:stripe",
  "action": "deny",
  "conditions": { "method": "DELETE" }
}

Response 201

{
  "id": "pol_01...",
  "toolName": "rest:stripe",
  "action": "deny",
  "conditions": { "method": "DELETE" },
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/policies

Lista las políticas activas de un tenant, opcionalmente filtradas por agente.

Auth:Bearer token|Permission:policy:read

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
agentId	query	uuid	no	Filter by agent

GET

/tenants/:tenantId/policies/:policyId

Obtiene una única política por ID.

Auth:Bearer token|Permission:policy:read

PUT

/tenants/:tenantId/policies/:policyId

Reemplaza una regla de política.

Auth:Bearer token|Permission:policy:write

PATCH

/tenants/:tenantId/policies/:policyId

Actualiza parcialmente una regla de política.

Auth:Bearer token|Permission:policy:write

DELETE

/tenants/:tenantId/policies/:policyId

Elimina una regla de política.

Auth:Bearer token|Permission:policy:delete

Response 200

{ "deleted": true, "id": "pol_01..." }

POST

/tenants/:tenantId/policies/evaluate

Simulación (dry-run): evalúa las políticas frente a una llamada a herramienta hipotética sin escribir en el rastro de auditoría.

Auth:Bearer token|Permission:policy:read

Parameter	In	Type	Required	Description
agentId	body	uuid	no	Agent UUID to evaluate against
toolName	body	string	yes	Tool name to test
params	body	object	no	Tool parameters

Response 200

{
  "decision": "deny",
  "matchedPolicy": { "id": "pol_01...", "toolName": "rest:stripe", "action": "deny" },
  "reason": "Matched deny rule for DELETE on rest:stripe"
}

GET

/tenants/:tenantId/policies/templates

Lista las plantillas de política integradas disponibles.

Auth:Bearer token|Permission:policy:read

Plantillas de Políticas

GET

/policy-templates

Lista todas las plantillas de política integradas disponibles.

Auth:Bearer token|Permission:policy:read

Response 200

[
  {
    "id": "pii-protection",
    "name": "PII Protection",
    "description": "Block tool calls that expose PII fields",
    "policyCount": 4
  }
]

GET

/policy-templates/:templateId

Obtiene una única plantilla con todas las definiciones de política.

Auth:Bearer token|Permission:policy:read

Parameter	In	Type	Required	Description
templateId	path	string	yes	Template slug (e.g. pii-protection)

POST

/tenants/:tenantId/policy-templates/:templateId/apply

Aplica una plantilla — crea todas sus políticas en el tenant.

Auth:Bearer token|Permission:policy:write

Parameter	In	Type	Required	Description
tenantId	path	uuid	yes	Tenant UUID
templateId	path	string	yes	Template slug
agentId	body	uuid	no	Scope policies to a specific agent (omit for tenant-wide)

Response 200

{
  "templateName": "pii-protection",
  "policiesCreated": 4,
  "policyIds": ["pol_01...", "pol_02...", "pol_03...", "pol_04..."]
}

DELETE

/tenants/:tenantId/policy-templates/:templateId/remove

Elimina todas las políticas que se aplicaron desde una plantilla.

Auth:Bearer token|Permission:policy:delete

Response 200

{ "removed": 4, "templateName": "pii-protection" }

GET

/tenants/:tenantId/policy-templates/applied

Lista las plantillas que se han aplicado a este tenant.

Auth:Bearer token|Permission:policy:read

Incidentes

GET

/tenants/:tenantId/incidents

Lista incidentes con filtrado por estado, severidad y agente.

Auth:Bearer token|Permission:incident:read

Parameter	In	Type	Required	Description
status	query	string	no	Filter: open, investigating, resolved
severity	query	string	no	Filter: low, medium, high, critical
agentId	query	uuid	no	Filter by agent
limit	query	integer	no	Max results (default 50, max 500)
offset	query	integer	no	Pagination offset

POST

/tenants/:tenantId/incidents

Abre un nuevo incidente manualmente.

Auth:Bearer token|Permission:incident:write

Parameter	In	Type	Required	Description
agentId	body	uuid	no	Related agent
title	body	string	yes	Incident title
severity	body	string	yes	low, medium, high, or critical
type	body	string	no	injection, drift, policy_violation, anomaly, or manual
data	body	object	no	Arbitrary incident context data

Response 201

{
  "id": "inc_01...",
  "title": "Prompt injection detected",
  "severity": "critical",
  "status": "open",
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/incidents/:incidentId

Obtiene un único incidente con el contexto de auditoría completo.

Auth:Bearer token|Permission:incident:read

PATCH

/tenants/:tenantId/incidents/:incidentId

Actualiza el estado o la severidad de un incidente.

Auth:Bearer token|Permission:incident:triage

Parameter	In	Type	Required	Description
status	body	string	no	open, investigating, or resolved
severity	body	string	no	Updated severity
resolution	body	string	no	Resolution notes (required when status = resolved)

GET

/tenants/:tenantId/incidents/count

Obtiene el recuento de incidentes agrupado por estado y severidad.

Auth:Bearer token|Permission:incident:read

Response 200

{
  "total": 42,
  "byStatus": { "open": 12, "investigating": 5, "resolved": 25 },
  "bySeverity": { "critical": 3, "high": 8, "medium": 18, "low": 13 }
}

GET

/tenants/:tenantId/incidents/:incidentId/audit

Lista los eventos de auditoría vinculados a un incidente.

Auth:Bearer token|Permission:incident:read

Rastro de Auditoría

GET

/tenants/:tenantId/audit

Lista eventos de auditoría con filtrado, paginación y prueba de Merkle opcional.

Auth:Bearer token|Permission:audit:read

Parameter	In	Type	Required	Description
agentId	query	uuid	no	Filter by agent
tool	query	string	no	Filter by tool name
outcome	query	string	no	Filter: allow, block, shadow
from	query	ISO8601	no	Start timestamp
to	query	ISO8601	no	End timestamp
limit	query	integer	no	Max results (default 100, max 1000)
offset	query	integer	no	Pagination offset

Response 200 (excerpt)

{
  "data": [
    {
      "id": "evt_01...",
      "agentId": "agt_01HXYZ...",
      "tool": "read_file",
      "outcome": "block",
      "riskScore": 0.87,
      "decision": "injection_detected",
      "timestamp": "2026-04-24T12:00:00.000Z",
      "merkleHash": "sha256:abc123..."
    }
  ],
  "pagination": { "total": 1420, "limit": 100, "offset": 0, "hasMore": true }
}

GET

/tenants/:tenantId/audit/:eventId

Obtiene un único evento de auditoría con el payload completo y la prueba de Merkle.

Auth:Bearer token|Permission:audit:read

POST

/tenants/:tenantId/audit/verify

Verifica la integridad Merkle de un lote de eventos de auditoría.

Auth:Bearer token|Permission:audit:read

Parameter	In	Type	Required	Description
eventIds	body	uuid[]	yes	Array of event IDs to verify

Response 200

{
  "verified": true,
  "checkedCount": 50,
  "tamperDetected": false
}

GET

/tenants/:tenantId/audit/export

Transmite eventos de auditoría como NDJSON para exportación masiva.

Auth:Bearer token|Permission:audit:read

La respuesta se transmite en streaming. Content-Type: application/x-ndjson. Sin paginación — devuelve todos los eventos de la ventana.

Parameter	In	Type	Required	Description
from	query	ISO8601	no	Start timestamp (required)
to	query	ISO8601	no	End timestamp (required)
format	query	string	no	ndjson or json (default: ndjson)

Puntuación de Riesgo

GET

/tenants/:tenantId/risk/scores

Obtiene las puntuaciones de riesgo actuales de todos los agentes de un tenant.

Auth:Bearer token|Permission:risk:read

Response 200

{
  "data": [
    {
      "agentId": "agt_01HXYZ...",
      "agentName": "code-assistant",
      "currentScore": 0.67,
      "tier": "high",
      "trend": "increasing",
      "updatedAt": "2026-04-24T14:23:00Z"
    }
  ]
}

GET

/tenants/:tenantId/risk/scores/:agentId

Obtiene la puntuación de riesgo detallada con desglose por componente para un agente específico.

Auth:Bearer token|Permission:risk:read

Response 200

{
  "agentId": "agt_01HXYZ...",
  "currentScore": 0.67,
  "tier": "high",
  "components": {
    "injectionScore": 0.12,
    "toolDriftScore": 0.71,
    "excessiveAgencyScore": 0.55,
    "anomalyScore": 0.84,
    "policyViolationRate": 0.03
  },
  "trend": "increasing",
  "trendDelta": 0.14,
  "updatedAt": "2026-04-24T14:23:00Z"
}

GET

/tenants/:tenantId/risk/scores/:agentId/history

Obtiene el historial de puntuación de riesgo de un agente (ventana móvil de 24h por defecto).

Auth:Bearer token|Permission:risk:read

Parameter	In	Type	Required	Description
window	query	string	no	Time window: 1h, 6h, 24h, 7d (default: 24h)

POST

/tenants/:tenantId/risk/scores/:agentId/recalculate

Fuerza un recálculo inmediato de la puntuación de riesgo de un agente.

Auth:Bearer token|Permission:risk:write

Response 200

{
  "agentId": "agt_01HXYZ...",
  "previousScore": 0.67,
  "newScore": 0.54,
  "recalculatedAt": "2026-04-24T14:30:00Z"
}

GET

/tenants/:tenantId/risk/config

Obtiene la configuración de aplicación de riesgo del tenant.

Auth:Bearer token|Permission:risk:read

Response 200

{
  "monitorThreshold": "<your-threshold>",
  "blockThreshold": "<your-threshold>",
  "autoLockThreshold": "<your-threshold>",
  "humanReviewThreshold": "<your-threshold>"
}

PATCH

/tenants/:tenantId/risk/config

Actualiza los umbrales de aplicación de riesgo del tenant.

Auth:Bearer token|Permission:risk:write

Parameter	In	Type	Required	Description
monitorThreshold	body	number	no	Score at which monitoring alerts trigger (0.0–1.0)
blockThreshold	body	number	no	Score at which auto-block activates (0.0–1.0)
autoLockThreshold	body	number	no	Score at which agent is suspended (0.0–1.0)
humanReviewThreshold	body	number	no	Score at which human review is required (0.0–1.0)

GET

/tenants/:tenantId/risk/baselines/:agentId

Obtiene la línea base de comportamiento de un agente.

Auth:Bearer token|Permission:risk:read

DELETE

/tenants/:tenantId/risk/baselines/:agentId

Reinicia la línea base de comportamiento de un agente.

Auth:Bearer token|Permission:risk:write

Response 200

{ "reset": true, "agentId": "agt_01HXYZ..." }

POST

/tenants/:tenantId/risk/anomalies/analyze

Ejecuta un análisis de anomalías sobre las últimas N horas de actividad del agente.

Auth:Bearer token|Permission:risk:read

Parameter	In	Type	Required	Description
agentId	body	uuid	no	Agent to analyze (omit for tenant-wide)
windowHours	body	integer	no	Lookback window (default: 24)

Response 200

{
  "anomaliesDetected": true,
  "results": [
    {
      "anomalyType": "tool_burst",
      "anomalyScore": 0.91,
      "explanation": "Agent called 47 tools in 60 seconds (4.2σ above baseline)"
    }
  ]
}

Cumplimiento

GET

/tenants/:tenantId/compliance/checklist

Obtiene la postura de cumplimiento actual con análisis de brechas.

Auth:Bearer token|Permission:compliance:read

POST

/tenants/:tenantId/compliance/annex-iv/report

Genera un informe PDF del Anexo IV a partir del rastro de auditoría.

Auth:Bearer token|Permission:compliance:read

La respuesta se transmite en streaming. Content-Type: application/pdf. El PDF se genera a partir del rastro de auditoría inmutable con pruebas de integridad Merkle.

Parameter	In	Type	Required	Description
periodStart	body	ISO8601	yes	Report period start
periodEnd	body	ISO8601	yes	Report period end
format	body	string	no	pdf or json (default: pdf)

GET

/tenants/:tenantId/compliance/reports

Lista los informes de cumplimiento generados anteriormente.

Auth:Bearer token|Permission:compliance:read

GET

/tenants/:tenantId/compliance/snapshots

Obtiene instantáneas de cumplimiento a lo largo del tiempo (para tendencias).

Auth:Bearer token|Permission:compliance:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max snapshots (default 30)

GET

/tenants/:tenantId/compliance/iso42001/gap-analysis

Análisis de brechas ISO 42001 frente al inventario de agentes.

Auth:Bearer token|Permission:compliance:read

GET

/tenants/:tenantId/compliance/nist-ai-rmf/gap-analysis

Análisis de brechas del NIST AI RMF (funciones Govern, Map, Measure, Manage).

Auth:Bearer token|Permission:compliance:read

POST

/tenants/:tenantId/compliance/regulatory-notifications

Crea un borrador de notificación de incidente regulatorio (Art. 73 de la Ley de IA de la UE).

Auth:Bearer token|Permission:compliance:write

Parameter	In	Type	Required	Description
incidentId	body	uuid	yes	Related incident UUID
notificationDeadline	body	ISO8601	no	Regulatory deadline (auto-calculated from incident date if omitted)

Alertas

GET

/tenants/:tenantId/alerts/rules

Lista las reglas de alerta.

Auth:Bearer token|Permission:alert:read

POST

/tenants/:tenantId/alerts/rules

Crea una regla de alerta.

Auth:Bearer token|Permission:alert:write

Parameter	In	Type	Required	Description
name	body	string	yes	Rule name
condition	body	string	yes	CEL condition expression (e.g. riskScore >= 0.70)
severity	body	string	yes	low, medium, high, or critical
channels	body	string[]	no	Delivery channels: webhook, email, slack
webhookUrl	body	string	no	Webhook delivery URL
agentId	body	uuid	no	Scope to a specific agent

PATCH

/tenants/:tenantId/alerts/rules/:ruleId

Actualiza una regla de alerta.

Auth:Bearer token|Permission:alert:write

DELETE

/tenants/:tenantId/alerts/rules/:ruleId

Elimina una regla de alerta.

Auth:Bearer token|Permission:alert:delete

GET

/tenants/:tenantId/alerts/events

Lista los eventos de alerta disparados.

Auth:Bearer token|Permission:alert:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max results (default 100, max 500)
from	query	ISO8601	no	Start timestamp

Servidores MCP

POST

/tenants/:tenantId/mcp-servers

Registra un servidor MCP para escaneo y descubrimiento de herramientas.

Auth:Bearer token|Permission:mcp_server:write

Parameter	In	Type	Required	Description
name	body	string	yes	MCP server display name
url	body	string	yes	MCP server URL or stdio command
transport	body	string	no	http-sse or stdio (default: http-sse)
scanOnRegister	body	boolean	no	Run initial scan on registration (default: true)

Response 201

{
  "id": "mcp_01...",
  "name": "filesystem-server",
  "url": "http://localhost:8080",
  "transport": "http-sse",
  "createdAt": "2026-04-24T12:00:00.000Z"
}

GET

/tenants/:tenantId/mcp-servers

Lista los servidores MCP registrados.

Auth:Bearer token|Permission:mcp_server:read

GET

/tenants/:tenantId/mcp-servers/:mcpServerId

Obtiene un único servidor MCP con el inventario de herramientas.

Auth:Bearer token|Permission:mcp_server:read

PUT

/tenants/:tenantId/mcp-servers/:mcpServerId

Actualiza la configuración del servidor MCP.

Auth:Bearer token|Permission:mcp_server:write

DELETE

/tenants/:tenantId/mcp-servers/:mcpServerId

Da de baja a un servidor MCP.

Auth:Bearer token|Permission:mcp_server:delete

Response 200

{ "deleted": true, "id": "mcp_01..." }

POST

/tenants/:tenantId/mcp-servers/:mcpServerId/refresh-tools

Redescubre las herramientas del servidor MCP.

Auth:Bearer token|Permission:mcp_server:write

Response 200

{
  "toolsDiscovered": 12,
  "toolsAdded": 2,
  "toolsRemoved": 0,
  "refreshedAt": "2026-04-24T12:00:00.000Z"
}

POST

/tenants/:tenantId/mcp-servers/:mcpServerId/scan

Ejecuta un escaneo de seguridad sobre las herramientas del servidor MCP.

Auth:Bearer token|Permission:mcp_server:write

Response 200

{
  "scanId": "scan_01...",
  "status": "completed",
  "vulnerabilities": 1,
  "toolCount": 5,
  "scanDuration": 1240
}

GET

/tenants/:tenantId/mcp-servers/:mcpServerId/scans

Obtiene el historial de escaneos de un servidor MCP.

Auth:Bearer token|Permission:mcp_server:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max results (default 20, max 100)

GET

/tenants/:tenantId/scans

Historial de escaneos a nivel de tenant en todos los servidores MCP.

Auth:Bearer token|Permission:mcp_server:read

Parameter	In	Type	Required	Description
limit	query	integer	no	Max results (default 50, max 200)

Revisiones

Cola de revisión humana para llamadas de herramientas que requieren aprobación antes de ejecutarse.

GET

/tenants/:tenantId/reviews

Lista las revisiones pendientes con filtrado y paginación.

Auth:Bearer token|Permission:review:read

Parameter	In	Type	Required	Description
status	query	string	no	Filter: pending, approved, denied
agentId	query	uuid	no	Filter by agent
limit	query	integer	no	Max results (default 50, max 500)
offset	query	integer	no	Pagination offset

GET

/tenants/:tenantId/reviews/count

Obtiene el recuento de revisiones por estado.

Auth:Bearer token|Permission:review:read

Response 200

{ "pending": 5, "approved": 120, "denied": 8 }

GET

/tenants/:tenantId/reviews/:reviewId

Obtiene una única revisión con el nombre del agente.

Auth:Bearer token|Permission:review:read

POST

/tenants/:tenantId/reviews/:reviewId/decide

Aprueba o deniega una revisión pendiente.

Auth:Bearer token|Permission:review:triage

Parameter	In	Type	Required	Description
decision	body	string	yes	approved or denied
comment	body	string	no	Optional reviewer comment

Request body

{
  "decision": "approved",
  "comment": "Verified safe — one-time file access needed"
}

Notificaciones

GET

/tenants/:tenantId/notifications

Lista las notificaciones dentro de la aplicación para el usuario actual.

Auth:Bearer token

Parameter	In	Type	Required	Description
unreadOnly	query	boolean	no	Filter to unread only
limit	query	integer	no	Max results (default 50, max 200)

PATCH

/tenants/:tenantId/notifications/:id/read

Marca una única notificación como leída.

Auth:Bearer token

POST

/tenants/:tenantId/notifications/read-all

Marca todas las notificaciones no leídas como leídas.

Auth:Bearer token

Response 200

{ "marked": 12 }

Pasaportes

Los Pasaportes de Agente proporcionan tarjetas de identidad verificables para agentes de IA. Requiere el plan Scale.

GET

/tenants/:tenantId/agents/:agentId/passport

Obtiene el pasaporte de un agente con evaluación de riesgo, estado de cumplimiento y firma.

Auth:Bearer token|Permission:passport:read

Requiere el derecho de la función agent_passport (plan Scale).

PATCH

/tenants/:tenantId/agents/:agentId/passport

Actualiza los metadatos de visualización del pasaporte.

Auth:Bearer token|Permission:passport:write

Parameter	In	Type	Required	Description
displayName	body	string	no	Public display name
description	body	string	no	Public description
avatarUrl	body	string	no	Avatar image URL (SSRF-protected)
visibility	body	string	no	private, internal, or public

POST

/tenants/:tenantId/agents/:agentId/passport/refresh

Recalcula y vuelve a firmar el pasaporte con los datos más recientes.

Auth:Bearer token|Permission:passport:write

POST

/tenants/:tenantId/agents/:agentId/passport/publish

Publica el pasaporte para verificación externa.

Auth:Bearer token|Permission:passport:write

Publicar como público requiere un rol elevado (security_manager, tenant_admin o platform_admin).

Parameter	In	Type	Required	Description
visibility	body	string	no	public or internal (default: internal)

POST

/tenants/:tenantId/agents/:agentId/passport/unpublish

Despublica un pasaporte — establece la visibilidad como privada.

Auth:Bearer token|Permission:passport:write

GET

/public/passports/:tenantSlug/:agentSlug

Ver un pasaporte publicado (público, sin autenticación).

Auth:none (public)

Limitado a 60 solicitudes por minuto por IP. Devuelve una respuesta en caché (max-age 300s).

GET

/public/passports/:tenantSlug/:agentSlug/verify

Verifica la firma criptográfica de un pasaporte (público, sin autenticación).

Auth:none (public)

Response 200

{
  "verified": true,
  "valid": true,
  "passportHash": "sha256:abc123...",
  "signature": "base64:...",
  "signedAt": "2026-04-24T12:00:00.000Z",
  "keyId": "key_01...",
  "publicKey": "-----BEGIN PUBLIC KEY-----..."
}

GET

/public/passports/:tenantSlug/:agentSlug/badge.svg

Renderiza una insignia SVG incrustable para el agente (público, sin autenticación).

Auth:none (public)

Limitado a 300 solicitudes por minuto por IP. Content-Type: image/svg+xml.

Facturación

GET

/billing/status

Nivel de plan actual y estado de la suscripción.

Auth:Bearer token|Permission:tenant:read

Response 200

{
  "planTier": "pro",
  "billingState": "active",
  "hasStripeCustomer": true,
  "hasSubscription": true
}

GET

/billing/entitlements

Derechos de funciones y límites del plan actual.

Auth:Bearer token|Permission:tenant:read

Response 200

{
  "planTier": "pro",
  "billingState": "active",
  "entitlements": {
    "maxAgents": 50,
    "includedToolCalls": 100000,
    "retentionDays": 365,
    "features": ["agent_passport", "sso", "custom_policies"]
  }
}

GET

/billing/usage

Uso del mes actual y límites del plan.

Auth:Bearer token|Permission:tenant:read

Response 200

{
  "currentAgentCount": 12,
  "maxAgents": 50,
  "currentToolCalls": 45230,
  "includedToolCalls": 100000,
  "overageRate": 0.001,
  "billingPeriodStart": "2026-04-01T00:00:00.000Z",
  "billingPeriodEnd": "2026-04-30T23:59:59.999Z",
  "retentionDays": 365
}

POST

/billing/checkout

Crea una sesión de Stripe Checkout para la mejora de plan.

Auth:Bearer token|Permission:tenant:write

Parameter	In	Type	Required	Description
tier	body	string	yes	Target plan: free, team, starter, pro, business
successPath	body	string	no	Redirect path after success
cancelPath	body	string	no	Redirect path on cancel

Response 200

{ "checkoutUrl": "https://checkout.stripe.com/c/pay_..." }

POST

/billing/portal

Crea una sesión de Stripe Customer Portal para la gestión de la suscripción.

Auth:Bearer token|Permission:tenant:write

Response 200

{ "portalUrl": "https://billing.stripe.com/p/session_..." }

Configuraciones de Exportación

Configura la exportación automatizada del rastro de auditoría a destinos S3, webhooks o syslog. Las credenciales se cifran en reposo (AES-256-GCM) y nunca se devuelven en las respuestas de la API.

POST

/tenants/:tenantId/export-configs

Crea una configuración de exportación.

Auth:Bearer token|Permission:export:write

Parameter	In	Type	Required	Description
name	body	string	yes	Config display name
destinationType	body	string	yes	s3, webhook, or syslog
config	body	object	yes	Destination-specific config (bucket, url, host, etc.)
credentials	body	object	no	Auth credentials (encrypted at rest, never returned)
filters	body	object	no	Event filters (agent, tool, outcome, etc.)
intervalSeconds	body	integer	no	Export interval (30–86400 seconds)
format	body	string	no	ndjson or json (default: ndjson)
enabled	body	boolean	no	Active on creation (default: true)

Request body

{
  "name": "S3 Audit Export",
  "destinationType": "s3",
  "config": {
    "bucket": "acme-audit-logs",
    "region": "eu-west-1",
    "prefix": "shieldagent/"
  },
  "credentials": {
    "accessKeyId": "AKIA...",
    "secretAccessKey": "<your-aws-secret-key>"
  },
  "intervalSeconds": 300,
  "format": "ndjson"
}

GET

/tenants/:tenantId/export-configs

Lista las configuraciones de exportación (credenciales ocultas).

Auth:Bearer token|Permission:export:read

PATCH

/tenants/:tenantId/export-configs/:configId

Actualiza una configuración de exportación (actualización parcial, credenciales ocultas en la respuesta).

Auth:Bearer token|Permission:export:write

DELETE

/tenants/:tenantId/export-configs/:configId

Elimina una configuración de exportación.

Auth:Bearer token|Permission:export:delete

POST

/tenants/:tenantId/export-configs/:configId/test

Prueba la conexión del adaptador de exportación.

Auth:Bearer token|Permission:export:write

Response 200

{ "success": true, "latencyMs": 245 }

API de Veredicto

Responsabilidad de aplicación

La API de Veredicto ejecuta el pipeline de seguridad completo de ShieldAgent y devuelve un veredicto. Tu código de servidor es responsable de aplicar ese veredicto — ShieldAgent no reenvía ni bloquea el tráfico directamente. Si tu código ignora un veredicto block, la llamada a la herramienta se ejecuta de todos modos. Todos los veredictos de escaneo se registran en el rastro de auditoría con source: "verdict_api"; la detección de anomalías puede marcar agentes con 100% de veredictos de bloqueo pero con ejecución de herramientas continua.

La API de Veredicto permite el escaneo del lado del servidor para clientes que poseen y operan su propio servidor de API o MCP (Posiciones de Despliegue 2 y 3). En lugar de enrutar el tráfico a través del proxy de ShieldAgent, tu servidor envía el payload de la solicitud a ShieldAgent, recibe un veredicto de seguridad y lo aplica localmente. La comunicación del agente con tu servidor no cambia — no se modifican mensajes MCP, no se añaden encabezados HTTP.

Modelo de autenticación — clave de API de tenant, no JWT de usuario

Los endpoints de la API de Veredicto se autentican con una clave de API con ámbito de tenant (token Bearer), no el JWT de usuario emitido por /auth/login. Trata esta clave como un secreto del lado del servidor — nunca la expongas a los clientes agentes.

URL base (servicio proxy): https://proxy.shieldagent.io

POST

/tenants/:tenantId/scan

Envía una llamada a herramienta o solicitud de API para escaneo de seguridad. Devuelve un veredicto (allow / block / human_review). Tu servidor debe aplicar el veredicto — ShieldAgent no reenvía el tráfico.

Auth:Bearer token

Auth: Bearer <tenant-api-key>. Limitado por tenant y por agente. Se escribe un evento de auditoría en cada llamada con source: "verdict_api". Se ejecuta el mismo pipeline multietapa que el proxy en línea — se omite el reenvío.

Parameter	In	Type	Required	Description
tenantId	path	string (uuid)	yes	Your tenant UUID
agentId	body	string (uuid)	no	ShieldAgent agent UUID. Optional — omit when your server cannot identify the caller (e.g. typical MCP server, which has no agent identity in the protocol). When provided the agent must belong to this tenant; cross-tenant IDs are rejected with 403. When omitted the pipeline runs with tenant-level policies only.
clientHint	body	string	no	MCP clientInfo.name or similar client software identifier (e.g. "Claude Desktop"). Used for best-effort agent matching when agentId is unavailable: if exactly one registered agent matches, per-agent policies apply; otherwise falls back to tenant-level. Ignored when agentId is provided.
toolName	body	string	yes	Name of the tool being called (e.g. "read_file", "api:POST:/payments")
params	body	object	yes	Tool call parameters as a JSON object
include_findings	body	boolean	no	Request detailed findings in the response. Requires the verdictDetailedFindings tenant permission flag (off by default — see Response Tiering below). Without permission this field is ignored.
context.transport	body	"mcp" \| "rest" \| "custom"	no	Transport protocol between agent and your server
context.sourceIp	body	string	no	IP address of the agent. Used for per-IP rate limiting.
context.sessionId	body	string	no	Session identifier. Used for excessive agency detection across calls in the same session.

Request body

{
  "agentId": "a1b2c3d4-0000-0000-0000-000000000001",  // optional
  "clientHint": "Claude Desktop",                       // optional
  "toolName": "read_file",
  "params": { "path": "/etc/passwd" },
  "include_findings": false,
  "context": {
    "transport": "mcp",
    "sourceIp": "10.0.1.5",
    "sessionId": "sess-abc123"
  }
}

Response 200 — default tier (all callers)

{
  "action": "block",              // "allow" | "block" | "human_review"
  "reason": "Security threat detected",
  "riskScore": 87,
  "auditEventId": "evt-a1b2c3d4-0000-0000-0000-000000000001",
  "reviewId": null                // set when action is "human_review"
}

Niveles de respuesta — include_findings: true + verdictDetailedFindings tenant permission

Los hallazgos detallados están desactivados por defecto. La respuesta predeterminada omite deliberadamente nombres de escáneres, patrones de detección y detalles de estrategia para prevenir ataques de evasión iterativa (refleja el modelo de hallazgos DLP). Habilitar solo para depuración o pruebas de integración.

Response 200 — detailed tier

{
  "action": "block",
  "reason": "Prompt injection detected in tool arguments",
  "findings": [
    {
      "type": "injection",
      "severity": "critical",
      "detail": "Path traversal pattern detected",
      "scanner": "regex"
    }
  ],
  "riskScore": 87,
  "auditEventId": "evt-a1b2c3d4-...",
  "reviewId": null
}

Respuestas de error

401Clave de API de tenant ausente o inválida

403El agentId no pertenece a este tenant (suplantación entre tenants rechazada)

429Límite de tasa excedido — límite por tenant o por agente. Ver encabezado Retry-After.

Cuándo omitir agentId

Escenario	agentId	Comportamiento del pipeline
Servidor MCP (típico)	omitir	Solo políticas a nivel de tenant. Opcionalmente pasar clientHint del handshake MCP clientInfo.name.
API HTTP con mapeo de autenticación de agente	proveer	Pipeline completo por agente: políticas, puntuación de riesgo, límites de tasa, línea base, herramientas aprobadas.
API HTTP sin mapeo de agente	omitir	Solo políticas a nivel de tenant. Los límites de tasa se aplican por tenant.

POST

/tenants/:tenantId/verdict-confirmations

Informa si un veredicto fue aplicado por tu servidor. Callback opcional que cierra el ciclo de auditoría. Los tenants que nunca llaman a este endpoint aparecen como 'enforcement unknown' en los informes de cumplimiento.

Auth:Bearer token

No es obligatorio — la confirmación de aplicación es voluntaria. Contribuye a la métrica Verdict Enforcement Rate de tu tenant. Llama después de ejecutar o rechazar la llamada a la herramienta, no antes.

Parameter	In	Type	Required	Description
tenantId	path	string (uuid)	yes	Your tenant UUID
auditEventId	body	string (uuid)	yes	The auditEventId returned by POST /scan
executed	body	boolean	yes	true if the tool call was executed (verdict was "allow" or human review approved); false if it was rejected (verdict was "block" or human review denied)

Request body

{
  "auditEventId": "evt-a1b2c3d4-0000-0000-0000-000000000001",
  "executed": false
}

Response 200

{ "recorded": true }

Salud

GET

/healthz

Sonda de liveness. Devuelve el estado del servicio y una marca de tiempo.

Auth:none (public)

Excluido de la limitación de tasa. Úsalo para las sondas de liveness/readiness de Kubernetes.

Response 200

{
  "status": "ok",
  "timestamp": "2026-04-24T12:00:00.000Z"
}

Especificación OpenAPI

La especificación completa OpenAPI 3.1.0 está disponible para importar en Postman, Insomnia o cualquier herramienta compatible con OpenAPI. Consulta la página de Referencia OpenAPI para las URLs de especificación e instrucciones de generación de clientes.

bash

# Serve Swagger UI locally
npx @redocly/cli preview-docs docs/openapi/shieldagent-api.yaml