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 é o stream de eventos empresarial da Tess AI. Ele expõe uma exportação normalizada e em tempo real das execuções de IA e da atividade do workspace, que qualquer plataforma empresarial pode consumir — SIEM, data lakes, ferramentas de governança, plataformas de FinOps, pipelines de analytics e fluxos personalizados. Como a Tess é a camada de orquestração que fica à frente de todos os provedores de modelos, este stream carrega um contexto que os provedores individualmente não conseguem enxergar: qual workspace e usuário disparou a atividade, a qual execução de agente ou chamada de ferramenta ela pertence, qual modelo e provedor a atendeu, quanto tempo levou, quais políticas foram aplicadas e quanto do saldo de créditos do workspace foi consumido. Isso torna o stream valioso muito além da auditoria — ele é uma base para observabilidade empresarial, gestão de custos e analytics.

Eventos de Auditoria estão disponíveis apenas para planos Enterprise. O workspace precisa ter a funcionalidade de eventos de auditoria habilitada, e o token de API precisa ter permissão para ler eventos de auditoria do workspace selecionado.

O que você pode construir

Um único stream habilita muitos casos de uso empresariais:

Monitoramento de segurança — encaminhe eventos para o seu SIEM e crie alertas para atividades de alto risco.
Conformidade e auditoria — mantenha um registro imutável de quem fez o quê, quando e sobre qual entidade.
Governança de IA — alimente plataformas de governança que acompanham o uso de modelos e a aplicação de políticas nas execuções.
AI FinOps e análise de custos — atribua o consumo de créditos e o volume de uso por workspace, usuário, modelo e provedor.
Chargeback e showback — cobre ou reporte o consumo de créditos para as equipes que o geram.
Análise de uso — entenda a adoção e o volume de execuções por agente e modelo.
Monitoramento operacional — acompanhe latência, falhas e comportamento de chamadas de ferramentas nas execuções.
Ingestão em data lake — armazene eventos brutos no seu data warehouse para análise de longo prazo.
Fluxos empresariais personalizados — dispare automações a partir de qualquer tipo de evento.

Consumidores suportados

O endpoint é uma exportação genérica, não um webhook exclusivo de segurança. Destinos comuns incluem:

Categoria	Exemplos
SIEM	Splunk, Microsoft Sentinel, IBM QRadar
Data lakes e data warehouses	Databricks, Snowflake, BigQuery
Plataformas de governança	Microsoft Purview, Collibra, BigID, Immuta
Streaming e mensageria	Apache Kafka, Azure Event Hub, Google Pub/Sub
Armazenamento de objetos	Amazon S3, Azure Blob Storage, Google Cloud Storage (GCS)
FinOps e analytics	Plataformas de análise de custos, pipelines internos de analytics
Personalizado	Qualquer webhook ou coletor HTTPS

Arquitetura

A Tess emite um único stream de eventos empresarial via HTTPS que se distribui para as plataformas que a sua organização utiliza.

                          TESS
                 Enterprise Event Stream
                          │
                    HTTPS / Webhook
        ┌─────────────┬───┴────────┬──────────────┐
        │             │            │              │
      SIEM        Data Lake    Governança      AI FinOps
        │             │            │              │
     Splunk       Databricks   MS Purview    Custo por time
     Sentinel     Snowflake    Collibra      Chargeback
     QRadar       BigQuery     BigID         Showback

Endpoint

GET https://api.tess.im/audit-events

Envie toda requisição com:

Authorization: Bearer YOUR_API_KEY
Accept: application/json
x-workspace-id: YOUR_WORKSPACE_ID

A resposta sempre fica limitada ao workspace informado em x-workspace-id. Eventos que não pertencem de forma clara a um único workspace não são emitidos neste feed.

Exemplo de requisição

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

obrigatório

Inicio da janela de auditoria. Use um timestamp ISO-8601.

date-time

obrigatório

Fim da janela de auditoria. Deve ser maior ou igual a from. A janela não pode exceder 30 dias.

integer

Número de eventos retornados. O padrão e 50. O mínimo e 1; o máximo e 200.

string

Cursor opaco retornado em page.next_cursor. Envie esse valor para continuar a leitura a partir da página anterior.

string

Filtra pela origem. Os valores suportados são auditable e activity.

string

Filtra pelo tipo de evento normalizado, como user_updated, workspace_created ou agent_execution_completed.

integer

Filtra pelo ID do usuário ator. Use 0 para eventos gerados pelo sistema.

string

Filtra pelo tipo da entidade, como user, workspace, agent_execution ou agent_message.

string

Filtra pelo ID da entidade.

string

Filtra pelo nível de risco. Os valores suportados são low, medium, high e critical.

Resposta

{
  "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"
  }
}

Schema do evento

Cada evento usa o mesmo formato normalizado:

id: ID único do evento com prefixo da origem, como activity:100001 ou auditable:9001.
occurred_at: Timestamp UTC do evento.
workspace_id: Workspace dono do evento.
source: Categoria de origem do evento, atualmente activity ou auditable.
event_type: Nome normalizado do evento.
action: Ação canônica, como created, updated, completed, failed ou blocked.
actor: Usuário ou sistema que causou o evento.
entity: Objeto afetado pelo evento.
changes: Detalhes estruturados da alteração, incluindo valores anteriores, novos valores e os campos alterados quando existe um diff disponível.
metadata: Contexto adicional que ajuda a classificar, investigar ou correlacionar o evento.
risk_level: low, medium, high ou critical.
schema_version: Versão do schema normalizado do evento.

Contexto de execução no metadata

Para eventos de execução de IA, o campo metadata carrega o contexto de orquestração que só a Tess consegue fornecer. Dependendo do tipo de evento, ele pode incluir:

Identificadores de workspace e ator (usuário ou sistema)
A entidade relacionada, como a execução de agente ou a mensagem de agente
Modelo e provedor da ferramenta
Latência (duration_ms)
Detalhes da chamada de ferramenta (tool_call_id, tool_name, tool_status)
Aplicação de políticas (policy_name, policy_reason e se a chamada foi bloqueada)
Consumo de créditos (amount, credit_operation, credit_bucket) para cada incremento, decremento ou perda de crédito
Status do resultado

É isso que torna o stream útil para analytics empresarial e gestão de custos de IA, não apenas para auditoria de segurança.

AI FinOps

Como a Tess orquestra todas as execuções de IA, ela consegue exportar sinais de uso que os provedores de modelos não conseguem produzir por conta própria. Use o stream para impulsionar iniciativas de AI FinOps:

Consumo de créditos por workspace e usuário — todo incremento, decremento ou perda no saldo de créditos de um workspace é um evento auditado, com amount, credit_operation e credit_bucket.
Volume de uso por modelo e provedor — eventos de execução de agente e de chamada de ferramenta carregam model e tool_provider, permitindo detalhar o volume de execuções pelo que a sua organização realmente usa.
Chargeback e showback — atribua o consumo de créditos ao workspace ou usuário que o gerou.
Sinais operacionais de custo — duration_ms em execuções e chamadas de ferramentas mostra onde a latência, e portanto o tempo de computação, se concentra.

Armazene o stream no seu data warehouse (Snowflake, BigQuery, Databricks) ou plataforma de FinOps e agregue por esses campos de metadata para montar dashboards de consumo por workspace, usuário, modelo e provedor.

Consumindo o stream

Use este endpoint como uma fonte pull a partir de qualquer coletor, pipeline ou plataforma. Configuração recomendada:

Crie um token de API Enterprise dedicado para ingestão de eventos.
Armazene o token no gerenciador de segredos da sua plataforma.
Consulte GET /audit-events com uma janela curta, como 5 ou 15 minutos.
Guarde o último next_cursor bem-sucedido por workspace.
Preserve o JSON original no momento da ingestão.
Mapeie campos como event_type, actor.id, entity.type, entity.id, risk_level e workspace_id para o schema ou as propriedades customizadas da sua plataforma.
Crie alertas, ou agregações, para tipos de evento e campos de metadata de acordo com o seu caso de uso.

Use id e occurred_at para deduplicação e replay seguro.

Exemplo: ingestão em SIEM

Para um SIEM como Splunk, Microsoft Sentinel ou IBM QRadar, trate o endpoint como uma fonte de logs JSON baseada em pull e crie alertas para tipos de evento de alto risco ou valores de risk_level de acordo com a política de segurança da sua organização. Especificamente no IBM QRadar, configure a Tess AI como uma fonte de logs JSON customizada ou direcione a API por um coletor intermediário que encaminhe os eventos para o QRadar. Preserve o JSON normalizado e crie propriedades customizadas para:

workspace_id
source
event_type
action
actor.id
actor.type
entity.type
entity.id
risk_level
id
schema_version

Paginação

Leia os eventos em ordem crescente por occurred_at e ID do evento. Se page.has_more for true, chame o endpoint novamente com os mesmos filtros e o valor retornado em 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'

Erros

401 ou 403: Token inválido, ausência do plano Enterprise, ausência da permissão de eventos de auditoria ou falta de acesso ao workspace.
422: Parâmetros ausentes ou inválidos, x-workspace-id ausente, cursor inválido ou janela maior que 30 dias.
429: Limite de requisições excedido.
503: Uma das fontes de eventos de auditoria está temporariamente indisponível. Tente a mesma requisição novamente mais tarde.

Cabeçalhos

integer

obrigatório

ID do workspace. Obrigatório a partir de 01/09/2026. Até lá, se omitido, usa o workspace selecionado do usuário (deprecated). Após a data, ausência → 422.

Importar Template Pack

Listar Agentes

⌘I

Guia da API

Referência da API

Integrações

Protocolo de Contexto de Modelo (MCP)

Eventos de auditoria

O que você pode construir

Consumidores suportados

Arquitetura

Endpoint

Exemplo de requisição

Parametros de consulta

Resposta

Schema do evento

Contexto de execução no metadata

AI FinOps

Consumindo o stream

Exemplo: ingestão em SIEM

Paginação

Erros

Cabeçalhos

​O que você pode construir

​Consumidores suportados

​Arquitetura

​Endpoint

​Exemplo de requisição

​Parametros de consulta

​Resposta

​Schema do evento

​Contexto de execução no metadata

​AI FinOps

​Consumindo o stream

​Exemplo: ingestão em SIEM

​Paginação

​Erros

​Cabeçalhos

O que você pode construir

Consumidores suportados

Arquitetura

Endpoint

Exemplo de requisição

Parametros de consulta

Resposta

Schema do evento

Contexto de execução no metadata

AI FinOps

Consumindo o stream

Exemplo: ingestão em SIEM

Paginação

Erros

Cabeçalhos