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

# Attest Model

> Create a provenance attestation for an AI model, linking it to training datasets and recording framework metadata.

Creates a cryptographically anchored attestation for an AI model. The attestation captures the model's framework, training lineage, hyperparameters, and evaluation metrics. It is linked to the originating agent and anchored in the transparency log.

Model attestations provide an auditable record of what was trained, how it was trained, and what data was used -- enabling compliance teams and downstream consumers to verify model provenance before deployment.

### Authentication

<ParamField header="X-API-Key" type="string" required>
  API key with `models:write` scope. Alternatively, pass a Bearer JWT token in
  the `Authorization` header.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  Tenant identifier for multi-tenant isolation.
</ParamField>

### Request

<ParamField body="agent_id" type="string" required>
  MAIP agent identifier that trained or owns this model.
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable model name. Must be unique within the agent's namespace per
  version.
</ParamField>

<ParamField body="version" type="string">
  Semantic version of the model (e.g. `2.1.0`). Defaults to `1.0.0` if omitted.
</ParamField>

<ParamField body="framework" type="string">
  ML framework used to train the model. Accepted values: `pytorch`,
  `tensorflow`, `onnx`, `custom`.
</ParamField>

<ParamField body="hash" type="string">
  SHA-256 hex digest of the serialized model weights. Used for integrity
  verification at deployment time.
</ParamField>

<ParamField body="training_dataset_ids" type="string[]">
  Array of dataset attestation identifiers (`maip-ds:ULID`) used to train this
  model. Creates lineage edges automatically.
</ParamField>

<ParamField body="hyperparameters" type="object">
  Key-value map of hyperparameters used during training (e.g. `learning_rate`,
  `batch_size`, `epochs`).
</ParamField>

<ParamField body="metrics" type="object">
  Key-value map of evaluation metrics (e.g. `accuracy`, `f1_score`, `auc_roc`).
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique model attestation identifier in MAIP format (`maip-model:ULID`).
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent that attested this model.
</ResponseField>

<ResponseField name="name" type="string">
  Model name as provided in the request.
</ResponseField>

<ResponseField name="version" type="string">
  Resolved version of the model.
</ResponseField>

<ResponseField name="framework" type="string">
  ML framework identifier.
</ResponseField>

<ResponseField name="hash" type="string">
  SHA-256 hex digest stored for integrity verification.
</ResponseField>

<ResponseField name="training_dataset_ids" type="string[]">
  Linked training dataset attestation identifiers.
</ResponseField>

<ResponseField name="status" type="string">
  Attestation status. Always `attested` on creation.
</ResponseField>

<ResponseField name="receipt_id" type="string">
  Transparency-log receipt anchoring this attestation.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of creation.
</ResponseField>


## OpenAPI

````yaml mint-openapi.yaml POST /v1/models/attest
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks is a universal verification infrastructure for documents,
    credentials, and digital assets.

    This specification defines the canonical API for interacting with Truthlocks
    services.


    ## Base URLs

    - **Production**: `https://api.truthlocks.com`

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


    ## Authentication

    - **API Keys**: Use `X-API-Key` header for machine-to-machine operations

    - **Bearer Tokens**: Use `Authorization: Bearer <jwt>` for user-initiated
    operations


    ## Tenant Identity

    In production, tenant identity is derived from the authenticated context
    (API key or JWT).

    The `X-Tenant-ID` header is ignored in production to prevent spoofing.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Production API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox Environment
security:
  - APIKey: []
tags:
  - name: Authentication
    description: API key and token management
  - name: Issuers
    description: Issuer registration and trust management
  - name: Keys
    description: Cryptographic key management for issuers
  - name: Attestations
    description: Attestation lifecycle (mint, revoke, supersede)
  - name: Verification
    description: Attestation verification and proof bundles
  - name: Governance
    description: Issuer governance workflows (admin only)
  - name: Identity
    description: Organization, user, and role management
  - name: Audit
    description: Audit event queries
  - name: Platform
    description: Platform administration (super admin only)
  - name: Platform Review
    description: Staff review workflows for issuer applications
  - name: Tenant Console
    description: Tenant profile and lifecycle endpoints
  - name: Health
    description: Service health and readiness endpoints
  - name: Risk
    description: Risk signal ingestion and fraud detection
  - name: Risk Enforcement
    description: Risk enforcement actions — block, challenge, quarantine, and configuration
  - name: Billing
    description: Billing, subscription, and addon management
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
      trust, witness, compliance, orchestration, and observability
externalDocs:
  description: Transparency read-only API (separate service spec)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/models/attest:
    post:
      tags:
        - Machine Identity
      summary: Attest Model
      description: >
        Creates a cryptographic attestation for a machine learning model,
        recording

        its hash, framework, version, and training dataset lineage.
      operationId: maip.models.attest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - hash
                - framework
                - version
                - agent_id
              properties:
                name:
                  type: string
                  description: Model name
                hash:
                  type: string
                  description: SHA-256 hash of the model weights
                framework:
                  type: string
                  description: ML framework (e.g. pytorch, tensorflow, onnx)
                version:
                  type: string
                  description: Model version string
                agent_id:
                  type: string
                  format: uuid
                  description: Attesting agent
                training_dataset_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: IDs of attested training datasets
            example:
              name: fraud-detection-v2
              hash: a1b2c3d4e5f6789012345678abcdef0123456789abcdef0123456789abcdef01
              framework: pytorch
              version: 2.1.0
              agent_id: 550e8400-e29b-41d4-a716-446655440000
              training_dataset_ids:
                - 660e8400-e29b-41d4-a716-446655440000
      responses:
        '201':
          description: Model attested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipModel'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipModel:
      type: object
      properties:
        model_id:
          type: string
          format: uuid
        receipt_id:
          type: string
          format: uuid
        name:
          type: string
        hash:
          type: string
        framework:
          type: string
        version:
          type: string
        agent_id:
          type: string
          format: uuid
        training_dataset_ids:
          type: array
          items:
            type: string
            format: uuid
        created_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Machine-readable error code
          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: Human-readable error message
        http_status:
          type: integer
          description: HTTP status code
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying (for rate limits)
        details:
          type: object
          description: Additional error context
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````