> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reportar Anomalia

> Reportar uma anomalia comportamental detetada na atividade de um agente de IA.

Reporta uma anomalia comportamental detetada na atividade de um agente de IA. As anomalias são observações sinalizadas que indicam que um agente pode estar a operar fora do seu envelope comportamental esperado — como picos de taxa súbitos, violações de âmbito, quedas na pontuação de confiança ou anomalias de acesso geográfico.

Os relatórios de anomalias criam alertas acionáveis para equipas de segurança e podem acionar políticas de resposta automatizadas (por exemplo, limitação, revogação de sessão ou suspensão de agente) dependendo da gravidade e da configuração do inquilino.

### Tipos de Anomalia

| Tipo | Descrição |
| :- | :- |
| `rate_spike` | Taxa de solicitação do Agente excede significativamente a linha de base histórica |
| `scope_violation` | O agente tentou acessar um recurso fora de seus escopos concedidos |
| `trust_drop` | Pontuação de confiança calculada do Agente caiu abaixo do limite |
| `pattern_deviation` | O padrão de comportamento do agente se desvia de sua linha de base treinada |
| `geographic_anomaly` | Agente acessado de um local geográfico ou faixa de IP inesperada |

### Níveis de Gravidade

| Gravidade | SLA | Resposta Automática |
| :- | :- | :- |
| `low` | revisão de 24h | Apenas registrado |
| `medium` | Revisão de 4h | Agente restringido |
| `high` | revisão de 1h | Sessões suspensas |
| `critical` | Revisão de 15min | Agente revogado aguardando investigação |

### Resposta

**id** `string`

Identificador de anomalia único no formato MAIP (`maip-anom:ULID`).

**agent\_id** `string`

O agente associado à anomalia.

**anomaly\_type** `string`

Tipo de anomalia relatada.

**severity** `string`

Nível de gravidade.

**status** `string`

Status da anomalia. Sempre `open` na criação.

**auto\_response** `string`

Ação de resposta automatizada tomada (se houver), com base na gravidade e na política do locatário.

**created\_at** `string`

Carimbo de data/hora de criação ISO 8601.


## OpenAPI

````yaml pt/mint-openapi.yaml POST /v1/agents/{agentId}/anomalies
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >-
    Truthlocks é uma infraestrutura de verificação universal para documentos,
    credenciais e ativos digitais.

    Esta especificação define a API canônica para interagir com os serviços
    Truthlocks.


    ## URLs Base

    - **Produção**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Autenticação

    - **Chaves de API**: Use o cabeçalho `X-API-Key` para operações máquina a
    máquina

    - **Tokens de Portador**: Use `Authorization: Bearer <jwt>` para operações
    iniciadas pelo usuário


    ## Identidade do Inquilino

    Em produção, a identidade do inquilino é derivada do contexto autenticado
    (chave de API ou JWT).

    O cabeçalho `X-Tenant-ID` é ignorado em produção para evitar falsificação.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: API de Produção
  - url: https://sandbox-api.truthlocks.com
    description: Ambiente Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gerenciamento de chaves e tokens de API
  - name: Issuers
    description: Registro do emissor e gerenciamento de confiança
  - name: Keys
    description: Gerenciamento de chaves criptográficas para emissores
  - name: Attestations
    description: Ciclo de vida da atestação (cunhar, revogar, substituir)
  - name: Verification
    description: Verificação de atestado e pacotes de prova
  - name: Governance
    description: Fluxos de trabalho de governança do emissor (somente administrador)
  - name: Identity
    description: Gerenciamento de organização, usuário e função
  - name: Audit
    description: Consultas de eventos de auditoria
  - name: Tenant Console
    description: Endpoints de perfil e ciclo de vida do locatário
  - name: Health
    description: Endpoints de saúde e prontidão do serviço
  - name: Risk
    description: Ingestão de sinal de risco e detecção de fraude
  - name: Risk Enforcement
    description: Ações de aplicação de risco — bloqueio, desafio, quarentena e configuração
  - name: Billing
    description: Gerenciamento de faturamento, assinatura e complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidade de Agente de Máquina (MAIP) — registro de agente,
      sessões, confiança, testemunha, conformidade, orquestração e
      observabilidade
externalDocs:
  description: API somente leitura de transparência (especificação de serviço separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/agents/{agentId}/anomalies:
    post:
      tags:
        - Machine Identity
      summary: Reportar Anomalia
      description: >-
        Reporta uma anomalia comportamental ou de segurança detetada para um
        agente. As anomalias são rastreadas e podem afetar a pontuação de
        confiança do agente.
      operationId: maip.anomalies.report
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Identificador do agente
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                actual_value:
                  nullable: true
                  type: number
                anomaly_score:
                  type: number
                anomaly_type:
                  type: string
                  description: >-
                    Classificação (por exemplo, scope_escalation,
                    unusual_volume, auth_failure_burst)
                baseline_value:
                  nullable: true
                  type: number
                description:
                  type: string
                  description: Descrição legível por humanos da anomalia
              type: object
              required:
                - anomaly_type
      responses:
        '201':
          description: Anomalia reportada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipAnomaly'
        '400':
          description: Erro de validação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticação necessária
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Agente não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Limite de taxa excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipAnomaly:
      type: object
      properties:
        anomaly_id:
          type: string
          format: uuid
        agent_id:
          type: string
          format: uuid
        anomaly_type:
          type: string
        severity:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
        details:
          type: object
          additionalProperties: true
        status:
          type: string
          enum:
            - open
            - investigating
            - resolved
            - dismissed
        resolution:
          type: string
        resolved_by:
          type: string
        created_at:
          type: string
          format: date-time
        resolved_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Código de erro legível por máquina
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensagem de erro legível por humanos
        http_status:
          type: integer
          description: Código de status HTTP
        retry_after_ms:
          type: integer
          description: >-
            Milissegundos para aguardar antes de tentar novamente (para limites
            de taxa)
        details:
          type: object
          description: Contexto de erro adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Chave de API para autenticação máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operações iniciadas pelo usuário

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.