> ## 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.

# Calcular puntuación de confianza

> Recalcular la puntuación de confianza para un agente de máquina basándose en las señales de comportamiento actuales

Activa un recálculo bajo demanda de la puntuación de confianza para un agente específico. La puntuación se deriva de múltiples factores ponderados, incluyendo la tasa de anomalías, el historial de tiempo de actividad, la profundidad de la delegación y el volumen de recibos. Utilice este endpoint después de un evento significativo (rotación de claves, violación de políticas, ráfaga de atestaciones) para asegurarse de que la puntuación refleje la postura actual del agente.

Las puntuaciones de confianza van de `0.0` (sin confianza) a `1.0` (confianza total) y son utilizadas por los motores de políticas, la selección de testigos y las puertas de delegación en toda la plataforma.

### Autenticación

Requiere el encabezado `X-API-Key` o el token Bearer JWT. El espacio de trabajo se deriva de la credencial autenticada; no envíe `X-Tenant-ID`.

### Respuesta

**agent\_id** `string`

El identificador del agente que fue puntuado.

**score** `number`

La puntuación de confianza calculada como un número flotante entre `0.0` y `1.0`.

**factors** `object`

Desglose de los factores individuales que contribuyeron a la puntuación.

**Factor fields**

**factors.anomaly\_rate** `number`

Relación de eventos anómalos con el total de eventos en la ventana de puntuación. Cuanto menor, mejor.

**factors.uptime** `number`

Relación de disponibilidad del agente durante los últimos 30 días. `1.0` significa 100% de tiempo de actividad.

**factors.delegation\_depth** `integer`

Profundidad actual de la cadena de delegación del agente. Las cadenas profundas reducen la confianza.

**factors.receipt\_count** `integer`

Número total de recibos válidos que ha acumulado el agente.

**computed\_at** `string`

Marca de tiempo ISO 8601 de cuándo se completó el cálculo.

### Pesos del factor de puntuación

| Factor | Peso | Descripción |
| :- | :- | :- |
| `anomaly_rate` | 30% | Penaliza a los agentes con altas tasas de anomalías |
| `uptime` | 25% | Recompensa la disponibilidad constante |
| `delegation_depth` | 20% | Cadenas más profundas reducen la confianza proporcionalmente |
| `receipt_count` | 25% | Más recibos indican un historial establecido |


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/trust/compute
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/trust/compute:
    post:
      tags:
        - Machine Identity
      summary: Recalcular puntuación de confianza
      description: >-
        Fuerza un recálculo inmediato de la puntuación de confianza del agente
        utilizando las últimas señales. Devuelve los factores contribuyentes
        individuales.
      operationId: maip.agents.trust.compute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_id:
                  type: string
                  description: >-
                    Identificador de agente MAIP (por ejemplo,
                    maip:a0000000:01abc...)
              type: object
              required:
                - agent_id
      responses:
        '200':
          description: Puntuación de confianza recalculada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipTrustScore'
        '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:
    MaipTrustScore:
      type: object
      properties:
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
        factors:
          type: object
          additionalProperties: true
        deltas:
          type: object
          additionalProperties: true
        computed_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.