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

# Registrar herramienta

> Registrar una herramienta en el registro de herramientas MAIP con requisitos de alcance, clasificación de riesgos y límites de velocidad

# Registrar Herramienta

`POST /v1/tools`

Registra una nueva herramienta en el registro de herramientas MAIP del inquilino. Las herramientas representan capacidades externas (APIs, funciones, servicios) que los agentes de máquina pueden invocar. Cada herramienta está asociada con un alcance requerido, nivel de riesgo y una puerta de aprobación opcional.

La plataforma eleva automáticamente el nivel de riesgo a `"high"` si el nombre de la herramienta o el alcance requerido contiene verbos de acción peligrosos (escribir, eliminar, enviar, ejecutar, desplegar, destruir, soltar, truncar).

> [!NOTE]
>
> Los nombres de las herramientas deben ser únicos por inquilino. Intentar registrar una herramienta con un
> que ya existe devuelve `409 Conflict`.

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

**id** `string`

UUID de la herramienta recién registrada.

**tenant\_id** `string`

UUID del inquilino propietario.

**name** `string`

Nombre de la herramienta legible por máquina.

**display\_name** `string`

Nombre de la herramienta legible por humanos.

**description** `string`

Descripción de la herramienta.

**scope\_required** `string`

Alcance requerido para la invocación.

**risk\_level** `string`

Clasificación de riesgo efectiva (puede ser elevada automáticamente).

**requires\_approval** `boolean`

Si se requiere aprobación humana.

**rate\_limit\_per\_minute** `integer`

Límite de tasa por agente.

**category** `string`

Categoría de herramienta.

**status** `string`

Estado de la herramienta. Siempre `"active"` en la creación.

**metadata** `object`

Metadatos de la herramienta.

**created\_at** `string`

Marca de tiempo de creación ISO 8601.

**updated\_at** `string`

Marca de tiempo de última actualización ISO 8601.

### Ejemplo

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search.web",
    "display_name": "Web Search",
    "description": "Performs web searches via SerpAPI and returns structured results",
    "scope_required": "tool:search.web",
    "risk_level": "low",
    "rate_limit_per_minute": 30,
    "category": "search",
    "metadata": {
      "endpoint_url": "https://serpapi.com/search",
      "auth_type": "api_key",
      "max_results": 10
    }
  }'
```

***

### Elevación automática del nivel de riesgo

La plataforma escanea los nombres de las herramientas y los requisitos de alcance en busca de verbos de acción peligrosos. Si se detectan, el nivel de riesgo se eleva automáticamente:

| Verbo detectado | Elevación automática |
| - | - |
| `write`, `delete`, `send` | Elevado a `"high"` |
| `execute`, `deploy`, `destroy` | Elevado a `"high"` |
| `drop`, `truncate` | Elevado a `"high"` |

Las herramientas con nivel de riesgo `"critical"` siempre requieren aprobación humana, independientemente de la configuración de `requires_approval`.


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/tools
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/tools:
    post:
      tags:
        - Machine Identity
      summary: Registrar herramienta
      description: >-
        Registra una herramienta invocable que los agentes pueden llamar. El
        esquema de la herramienta define los argumentos de entrada esperados
        utilizando JSON Schema.
      operationId: maip.tools.register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                category:
                  type: string
                description:
                  type: string
                  description: Descripción de la herramienta legible por humanos
                display_name:
                  type: string
                metadata: {}
                name:
                  type: string
                  description: Nombre de herramienta único
                rate_limit_per_minute:
                  type: integer
                requires_approval:
                  type: boolean
                risk_level:
                  type: string
                scope_required:
                  type: string
              type: object
              required:
                - name
                - display_name
                - scope_required
      responses:
        '201':
          description: Herramienta registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipTool'
        '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'
        '429':
          description: Límite de velocidad excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipTool:
      type: object
      properties:
        tool_id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        schema:
          type: object
          additionalProperties: true
        agent_id:
          type: string
          format: uuid
        created_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.