> ## 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 Anomalía

> Reportar una anomalía de comportamiento detectada en la actividad de un agente de IA.

Reporta una anomalía de comportamiento detectada en la actividad de un agente de IA. Las anomalías son observaciones marcadas que indican que un agente puede estar operando fuera de su envolvente de comportamiento esperado, como picos repentinos de velocidad, violaciones de alcance, caídas en la puntuación de confianza o anomalías de acceso geográfico.

Los informes de anomalías crean alertas procesables para los equipos de seguridad y pueden activar políticas de respuesta automatizadas (por ejemplo, limitación, revocación de sesión o suspensión de agentes) según la gravedad y la configuración del inquilino.

### Tipos de anomalías

| Tipo | Descripción |
| :- | :- |
| `rate_spike` | La tasa de solicitudes del agente supera significativamente la línea base histórica |
| `scope_violation` | El agente intentó acceder a un recurso fuera de sus ámbitos concedidos |
| `trust_drop` | La puntuación de confianza calculada del agente cayó por debajo del umbral |
| `pattern_deviation` | El patrón de comportamiento del agente se desvía de su línea base entrenada |
| `geographic_anomaly` | Agente accedido desde una ubicación geográfica o rango de IP inesperado |

### Niveles de gravedad

| Gravedad | SLA | Respuesta automática |
| :- | :- | :- |
| `low` | Revisión de 24h | Solo registrado |
| `medium` | Revisión de 4h | Agente limitado |
| `high` | Revisión de 1h | Sesiones suspendidas |
| `critical` | Revisión de 15min | Agente revocado pendiente de investigación |

### Respuesta

**id** `string`

Identificador único de anomalía en formato MAIP (`maip-anom:ULID`).

**agent\_id** `string`

El agente asociado con la anomalía.

**anomaly\_type** `string`

Tipo de anomalía reportada.

**severity** `string`

Nivel de gravedad.

**status** `string`

Estado de anomalía. Siempre `open` en la creación.

**auto\_response** `string`

Acción de respuesta automatizada tomada (si la hay), basada en la gravedad y la política del inquilino.

**created\_at** `string`

Marca de tiempo de creación ISO 8601.


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/agents/{agentId}/anomalies
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks es una infraestructura de verificación universal para documentos,
    credenciales y activos digitales.

    Esta especificación define la API canónica para interactuar con los
    servicios de Truthlocks.


    ## URLs Base

    - **Producción**: `https://api.truthlocks.com`

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


    ## Autenticación

    - **Claves API**: Use el encabezado `X-API-Key` para operaciones máquina a
    máquina

    - **Tokens Bearer**: Use `Authorization: Bearer <jwt>` para operaciones
    iniciadas por el usuario


    ## Identidad del Inquilino

    En producción, la identidad del inquilino se deriva del contexto autenticado
    (clave API o JWT).

    El encabezado `X-Tenant-ID` se ignora en producción para evitar la
    suplantación de identidad.
  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 producción
  - url: https://sandbox-api.truthlocks.com
    description: Entorno Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gestión de claves y tokens de API
  - name: Issuers
    description: Registro del emisor y gestión de la confianza
  - name: Keys
    description: Gestión de claves criptográficas para emisores
  - name: Attestations
    description: Ciclo de vida de la atestación (acuñar, revocar, reemplazar)
  - name: Verification
    description: Verificación de atestación y paquetes de prueba
  - name: Governance
    description: Flujos de trabajo de gobernanza del emisor (solo administrador)
  - name: Identity
    description: Gestión de organización, usuarios y roles
  - name: Audit
    description: Consultas de eventos de auditoría
  - name: Tenant Console
    description: Puntos finales de perfil y ciclo de vida del inquilino
  - name: Health
    description: Endpoints de estado y preparación del servicio
  - name: Risk
    description: Ingesta de señales de riesgo y detección de fraude
  - name: Risk Enforcement
    description: >-
      Acciones de aplicación de riesgos: bloqueo, desafío, cuarentena y
      configuración
  - name: Billing
    description: Gestión de facturación, suscripciones y complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidad de Agente de Máquina (MAIP) — registro de agentes,
      sesiones, confianza, testigo, cumplimiento, orquestación y observabilidad
externalDocs:
  description: API de transparencia de solo lectura (especificación de servicio separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/agents/{agentId}/anomalies:
    post:
      tags:
        - Machine Identity
      summary: Reportar Anomalía
      description: >-
        Reporta una anomalía de comportamiento o seguridad detectada para un
        agente. Las anomalías se rastrean y pueden afectar la puntuación de
        confianza del agente.
      operationId: maip.anomalies.report
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Identificador de agente
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                actual_value:
                  nullable: true
                  type: number
                anomaly_score:
                  type: number
                anomaly_type:
                  type: string
                  description: >-
                    Clasificación (por ejemplo, scope_escalation,
                    unusual_volume, auth_failure_burst)
                baseline_value:
                  nullable: true
                  type: number
                description:
                  type: string
                  description: Descripción legible por humanos de la anomalía
              type: object
              required:
                - anomaly_type
      responses:
        '201':
          description: Anomalía reportada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipAnomaly'
        '400':
          description: Error de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Autenticación requerida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Agente no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Límite de velocidad 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 error legible 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: Mensaje de error legible por humanos
        http_status:
          type: integer
          description: Código de estado HTTP
        retry_after_ms:
          type: integer
          description: Milisegundos a esperar antes de reintentar (para límites de tasa)
        details:
          type: object
          description: Contexto de error adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clave API para autenticación máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operaciones iniciadas por el usuario

````

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