Eventos de auditoria

curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>' \
  --header 'x-workspace-id: <x-workspace-id>'

import requests

url = "https://api.tess.im/audit-events"

headers = {
    "x-workspace-id": "<x-workspace-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-workspace-id': '<x-workspace-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.tess.im/audit-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/audit-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-workspace-id: <x-workspace-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tess.im/audit-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-workspace-id", "<x-workspace-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.tess.im/audit-events")
  .header("x-workspace-id", "<x-workspace-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tess.im/audit-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-workspace-id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

GET

audit-events

Eventos de auditoria

curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>' \
  --header 'x-workspace-id: <x-workspace-id>'

import requests

url = "https://api.tess.im/audit-events"

headers = {
    "x-workspace-id": "<x-workspace-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-workspace-id': '<x-workspace-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.tess.im/audit-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/audit-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-workspace-id: <x-workspace-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tess.im/audit-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-workspace-id", "<x-workspace-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.tess.im/audit-events")
  .header("x-workspace-id", "<x-workspace-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tess.im/audit-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-workspace-id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Eventos de auditoria es el stream de eventos empresarial de Tess AI. Expone una exportacion normalizada y en tiempo real de las ejecuciones de IA y la actividad del workspace, que cualquier plataforma empresarial puede consumir: SIEM, data lakes, herramientas de gobernanza, plataformas de FinOps, pipelines de analitica y flujos personalizados. Como Tess es la capa de orquestacion que se ubica frente a todos los proveedores de modelos, este stream transporta un contexto que los proveedores por si solos no pueden ver: que workspace y usuario genero la actividad, a que ejecucion de agente o llamada de herramienta pertenece, que modelo y proveedor la atendio, cuanto tardo, que politicas se aplicaron y cuanto del saldo de creditos del workspace consumio. Esto hace que el stream sea valioso mucho mas alla de la auditoria: es una base para observabilidad empresarial, gestion de costos y analitica.

Eventos de auditoria esta disponible solo para planes Enterprise. El workspace debe tener habilitada la función de eventos de auditoria, y el token de API debe tener permiso para leer eventos de auditoria del workspace seleccionado.

Que puedes construir

Un unico stream habilita muchos casos de uso empresariales:

Monitoreo de seguridad — reenvia eventos a tu SIEM y crea alertas para actividad de alto riesgo.
Cumplimiento y auditoria — conserva un registro inmutable de quien hizo que, cuando y sobre que entidad.
Gobernanza de IA — alimenta plataformas de gobernanza que rastrean el uso de modelos y la aplicacion de politicas en las ejecuciones.
AI FinOps y analisis de costos — atribuye el consumo de creditos y el volumen de uso por workspace, usuario, modelo y proveedor.
Chargeback y showback — cobra o reporta el consumo de creditos a los equipos que lo generan.
Analisis de uso — comprende la adopcion y el volumen de ejecuciones por agente y modelo.
Monitoreo operativo — rastrea latencia, fallos y comportamiento de llamadas a herramientas en las ejecuciones.
Ingestion en data lake — almacena eventos en bruto en tu data warehouse para analisis a largo plazo.
Flujos empresariales personalizados — dispara automatizaciones a partir de cualquier tipo de evento.

Consumidores compatibles

El endpoint es una exportacion generica, no un webhook exclusivo de seguridad. Destinos comunes incluyen:

Categoria	Ejemplos
SIEM	Splunk, Microsoft Sentinel, IBM QRadar
Data lakes y data warehouses	Databricks, Snowflake, BigQuery
Plataformas de gobernanza	Microsoft Purview, Collibra, BigID, Immuta
Streaming y mensajeria	Apache Kafka, Azure Event Hub, Google Pub/Sub
Almacenamiento de objetos	Amazon S3, Azure Blob Storage, Google Cloud Storage (GCS)
FinOps y analitica	Plataformas de analisis de costos, pipelines internos de analitica
Personalizado	Cualquier webhook o colector HTTPS

Arquitectura

Tess emite un unico stream de eventos empresarial via HTTPS que se distribuye a las plataformas que utiliza tu organizacion.

                          TESS
                 Enterprise Event Stream
                          │
                    HTTPS / Webhook
        ┌─────────────┬───┴────────┬──────────────┐
        │             │            │              │
      SIEM        Data Lake    Gobernanza      AI FinOps
        │             │            │              │
     Splunk       Databricks   MS Purview    Costo por equipo
     Sentinel     Snowflake    Collibra      Chargeback
     QRadar       BigQuery     BigID         Showback

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 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

Parametros de consulta

date-time

requerido

Inicio de la ventana de auditoria. Usa un timestamp ISO-8601.

date-time

requerido

Fin de la ventana de auditoria. Debe ser mayor o igual que from. La ventana no puede exceder 30 dias.

integer

Numero de eventos devueltos. El valor predeterminado es 50. El minimo es 1; el maximo es 200.

string

Cursor opaco devuelto en page.next_cursor. Envialo para continuar leyendo desde la pagina anterior.

string

Filtra por origen. Los valores admitidos son auditable y activity.

string

Filtra por tipo de evento normalizado, como user_updated, workspace_created o agent_execution_completed.

integer

Filtra por ID del usuario actor. Usa 0 para eventos generados por el sistema.

string

Filtra por tipo de entidad, como user, workspace, agent_execution o agent_message.

string

Filtra por ID de entidad.

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.

Contexto de ejecucion en metadata

Para eventos de ejecucion de IA, el campo metadata transporta el contexto de orquestacion que solo Tess puede proporcionar. Segun el tipo de evento, puede incluir:

Identificadores de workspace y actor (usuario o sistema)
La entidad relacionada, como la ejecucion de agente o el mensaje de agente
Modelo y proveedor de la herramienta
Latencia (duration_ms)
Detalles de la llamada a herramienta (tool_call_id, tool_name, tool_status)
Aplicacion de politicas (policy_name, policy_reason y si la llamada fue bloqueada)
Consumo de creditos (amount, credit_operation, credit_bucket) por cada incremento, decremento o perdida de credito
Estado del resultado

Esto es lo que hace que el stream sea util para analitica empresarial y gestion de costos de IA, no solo para auditoria de seguridad.

AI FinOps

Como Tess orquesta todas las ejecuciones de IA, puede exportar señales de uso que los proveedores de modelos no pueden producir por si solos. Usa el stream para impulsar iniciativas de AI FinOps:

Consumo de creditos por workspace y usuario — cada incremento, decremento o perdida en el saldo de creditos de un workspace es un evento auditado, con amount, credit_operation y credit_bucket.
Volumen de uso por modelo y proveedor — los eventos de ejecucion de agente y de llamada a herramienta transportan model y tool_provider, lo que permite desglosar el volumen de ejecuciones segun lo que tu organizacion realmente usa.
Chargeback y showback — atribuye el consumo de creditos al workspace o usuario que lo genero.
Señales operativas de costo — duration_ms en ejecuciones y llamadas a herramientas muestra donde se concentra la latencia, y por lo tanto el tiempo de computo.

Almacena el stream en tu data warehouse (Snowflake, BigQuery, Databricks) o plataforma de FinOps y agrega por estos campos de metadata para construir dashboards de consumo por workspace, usuario, modelo y proveedor.

Consumir el stream

Usa este endpoint como una fuente pull desde cualquier colector, pipeline o plataforma. Configuración recomendada:

Crea un token de API Enterprise dedicado para la ingestion de eventos.
Guarda el token en el gestor de secretos de tu plataforma.
Consulta GET /audit-events con una ventana corta, como 5 o 15 minutos.
Conserva el ultimo next_cursor exitoso por workspace.
Preserva el JSON original en el momento de la ingestión.
Mapea campos como event_type, actor.id, entity.type, entity.id, risk_level y workspace_id al esquema o las propiedades personalizadas de tu plataforma.
Crea alertas, o agregaciones, para tipos de evento y campos de metadata segun tu caso de uso.

Usa id y occurred_at para deduplicacion y replay seguro.

Ejemplo: ingestion en SIEM

Para un SIEM como Splunk, Microsoft Sentinel o IBM QRadar, trata el endpoint como una fuente de logs JSON basada en pull y crea alertas para tipos de evento de alto riesgo o valores de risk_level segun la politica de seguridad de tu organizacion. Especificamente 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

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 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

Errores

401 o 403: Token invalido, falta del plan Enterprise, falta del permiso de eventos de auditoria 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.

Encabezados

integer

requerido

ID del workspace. Obligatorio a partir del 01/09/2026. Hasta entonces, si se omite, se usa el workspace seleccionado del usuario (deprecated). Después de la fecha, ausencia → 422.

De import template

Listar Agentes

⌘I

Guía de API

Referencia de API

Integraciones

Protocolo de Contexto de Modelo (MCP)

Eventos de auditoria

Que puedes construir

Consumidores compatibles

Arquitectura

Endpoint

Ejemplo de solicitud

Parametros de consulta

Respuesta

Esquema del evento

Contexto de ejecucion en metadata

AI FinOps

Consumir el stream

Ejemplo: ingestion en SIEM

Paginacion

Errores

Encabezados

​Que puedes construir

​Consumidores compatibles

​Arquitectura

​Endpoint

​Ejemplo de solicitud

​Parametros de consulta

​Respuesta

​Esquema del evento

​Contexto de ejecucion en metadata

​AI FinOps

​Consumir el stream

​Ejemplo: ingestion en SIEM

​Paginacion

​Errores

​Encabezados

Que puedes construir

Consumidores compatibles

Arquitectura

Endpoint

Ejemplo de solicitud

Parametros de consulta

Respuesta

Esquema del evento

Contexto de ejecucion en metadata

AI FinOps

Consumir el stream

Ejemplo: ingestion en SIEM

Paginacion

Errores

Encabezados