Saltar al contenido principal
GET
/
audit-events
Eventos de auditoria
curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>'
La API de Eventos de auditoria expone un feed normalizado de actividad del workspace para monitoreo de seguridad, revision de cumplimiento e ingestion en plataformas SIEM.
Eventos de auditoria esta disponible solo para planes Enterprise. El workspace debe tener habilitada la función de SIEM audit events, y el token de API debe tener permiso para leer eventos de auditoria del workspace seleccionado.

​
Endpoint

GET https://api.tess.im/audit-events
Envia cada solicitud con:
  • Authorization: Bearer YOUR_API_KEY
  • Accept: application/json
  • x-workspace-id: YOUR_WORKSPACE_ID
La respuesta siempre esta limitada al workspace informado en x-workspace-id. Los eventos que no pertenecen claramente a un unico workspace no se emiten en este feed.

​
Ejemplo de solicitud

curl --request GET \
  --url 'https://api.tess.im/audit-events?from=2026-04-08T00:00:00Z&to=2026-04-09T00:00:00Z&limit=100' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

​
Parametros de consulta

​
from
date-time
requerido
Inicio de la ventana de auditoria. Usa un timestamp ISO-8601.
​
to
date-time
requerido
Fin de la ventana de auditoria. Debe ser mayor o igual que from. La ventana no puede exceder 30 dias.
​
limit
integer
Numero de eventos devueltos. El valor predeterminado es 50. El minimo es 1; el maximo es 200.
​
cursor
string
Cursor opaco devuelto en page.next_cursor. Envialo para continuar leyendo desde la pagina anterior.
​
source
string
Filtra por origen. Los valores admitidos son auditable y activity.
​
event_type
string
Filtra por tipo de evento normalizado, como user_updated, workspace_created o agent_execution_completed.
​
actor_id
integer
Filtra por ID del usuario actor. Usa 0 para eventos generados por el sistema.
​
entity_type
string
Filtra por tipo de entidad, como user, workspace, agent_execution o agent_message.
​
entity_id
string
Filtra por ID de entidad.
​
risk_level
string
Filtra por nivel de riesgo. Los valores admitidos son low, medium, high y critical.

​
Respuesta

{
  "data": [
    {
      "id": "activity:100001",
      "occurred_at": "2026-04-08T10:00:00Z",
      "workspace_id": 242,
      "source": "activity",
      "event_type": "agent_execution_completed",
      "action": "completed",
      "actor": {
        "id": 16643,
        "email": "user@example.com",
        "type": "user",
        "ip": null,
        "user_agent": null
      },
      "entity": {
        "type": "agent_execution",
        "id": "183450",
        "name": null
      },
      "changes": {
        "before": {},
        "after": {},
        "changed_fields": []
      },
      "metadata": {
        "workspace_id": 242,
        "actor_user_id": 16643,
        "status": "succeeded",
        "duration_ms": 1200
      },
      "risk_level": "low",
      "schema_version": 1
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  },
  "meta": {
    "workspace_id": 242,
    "from": "2026-04-08T00:00:00Z",
    "to": "2026-04-09T00:00:00Z",
    "generated_at": "2026-04-09T00:00:02Z"
  }
}

​
Esquema del evento

Cada evento usa el mismo formato normalizado:
  • id: ID unico del evento con prefijo de origen, como activity:100001 o auditable:9001.
  • occurred_at: Timestamp UTC del evento.
  • workspace_id: Workspace propietario del evento.
  • source: Categoria de origen del evento, actualmente activity o auditable.
  • event_type: Nombre normalizado del evento.
  • action: Acción canónica, como created, updated, completed, failed o blocked.
  • actor: Usuario o sistema que causo el evento.
  • entity: Objeto afectado por el evento.
  • changes: Detalles estructurados del cambio, incluidos valores anteriores, nuevos valores y los campos modificados cuando hay un diff disponible.
  • metadata: Contexto adicional que ayuda a clasificar, investigar o correlacionar el evento.
  • risk_level: low, medium, high o critical.
  • schema_version: Version del esquema normalizado del evento.

​
Paginacion

Lee los eventos en orden ascendente por occurred_at e ID del evento. Si page.has_more es true, llama al endpoint nuevamente con los mismos filtros y el valor devuelto en page.next_cursor. 
curl --request GET \
  --url 'https://api.tess.im/audit-events?from=2026-04-08T00:00:00Z&to=2026-04-09T00:00:00Z&limit=100&cursor=NEXT_CURSOR' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

​
Integración con SIEM

Usa este endpoint como una fuente pull desde tu SIEM o colector de logs. Configuración recomendada:
  1. Crea un token de API Enterprise dedicado para ingestion SIEM.
  2. Guarda el token en el gestor de secretos de tu plataforma SIEM.
  3. Consulta GET /audit-events con una ventana corta, como 5 o 15 minutos.
  4. Conserva el ultimo next_cursor exitoso por workspace.
  5. Preserva el JSON original en el momento de la ingestión.
  6. Mapea campos como event_type, actor.id, entity.type, entity.id, risk_level y workspace_id a propiedades personalizadas del SIEM.
  7. Crea alertas para tipos de evento o valores de risk_level segun la politica de seguridad de tu organizacóon.

​
Notas para QRadar

En IBM QRadar, configura Tess AI como una fuente de logs JSON personalizada o enruta la API por un colector intermedio que reenvie eventos a QRadar. Conserva el JSON normalizado y crea propiedades personalizadas para:
  • workspace_id
  • source
  • event_type
  • action
  • actor.id
  • actor.type
  • entity.type
  • entity.id
  • risk_level
  • id
  • schema_version
Usa id y occurred_at para deduplicacion y replay seguro.

​
Errores

  • 401 o 403: Token invalido, falta del plan Enterprise, falta de permiso SIEM o sin acceso al workspace.
  • 422: Parametros ausentes o invalidos, x-workspace-id ausente, cursor invalido o ventana mayor que 30 dias.
  • 429: Limite de solicitudes excedido.
  • 503: Una de las fuentes de eventos de auditoria esta temporalmente no disponible. Intenta la misma solicitud mas tarde.