Pular para o conteúdo 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.

A API de Eventos de Auditoria expõe um feed normalizado de atividades do workspace para monitoramento de segurança, revisão de conformidade e ingestão em plataformas SIEM.
Eventos de Auditoria estão disponíveis apenas para planos Enterprise. O workspace precisa ter a funcionalidade de SIEM audit events habilitada, e o token de API precisa ter permissão para ler eventos de auditoria do workspace selecionado.

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

​
Parametros de consulta

​
from
date-time
obrigatório
Inicio da janela de auditoria. Use um timestamp ISO-8601.
​
to
date-time
obrigatório
Fim da janela de auditoria. Deve ser maior ou igual a from. A janela não pode exceder 30 dias.
​
limit
integer
Número de eventos retornados. O padrão e 50. O mínimo e 1; o máximo e 200.
​
cursor
string
Cursor opaco retornado em page.next_cursor. Envie esse valor para continuar a leitura a partir da página anterior.
​
source
string
Filtra pela origem. Os valores suportados são auditable e activity.
​
event_type
string
Filtra pelo tipo de evento normalizado, como user_updated, workspace_created ou agent_execution_completed.
​
actor_id
integer
Filtra pelo ID do usuário ator. Use 0 para eventos gerados pelo sistema.
​
entity_type
string
Filtra pelo tipo da entidade, como user, workspace, agent_execution ou agent_message.
​
entity_id
string
Filtra pelo ID da entidade.
​
risk_level
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.

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

​
Integração com SIEM

Use este endpoint como uma fonte pull no seu SIEM ou coletor de logs. Configuração recomendada:
  1. Crie um token de API Enterprise dedicado para ingestão SIEM.
  2. Armazene o token no gerenciador de segredos da sua plataforma SIEM.
  3. Consulte GET /audit-events com uma janela curta, como 5 ou 15 minutos.
  4. Guarde o último next_cursor bem-sucedido por workspace.
  5. Preserve o JSON original no momento da ingestão.
  6. Mapeie campos como event_type, actor.id, entity.type, entity.id, risk_level e workspace_id para propriedades customizadas do SIEM.
  7. Crie alertas para tipos de evento ou valores de risk_level de acordo com a política de segurança da sua organização.

​
Observações para QRadar

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
Use id e occurred_at para deduplicação e replay seguro.

​
Erros

  • 401 ou 403: Token inválido, ausência do plano Enterprise, ausência da permissão SIEM 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.