Saltar al contenido principal
GET
/
audit-events
Eventos de auditoria
curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>'

Documentation Index

Fetch the complete documentation index at: https://docs.tess.im/llms.txt

Use this file to discover all available pages before exploring further.

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.