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

# Record a Guardrail Score

> Apply thresholds to a score supplied by your application.

Records your application's score for an agent's input or output. It does not scan raw text or calculate an independent safety score. Supply the score produced by your own detector.

The required fields are `agent_id`, `check_type`, and `guardrail_type`. `check_type` must be `input` or `output`.

| Submitted score | Result |
| - | - |
| Greater than 0.8 | `fail` |
| Greater than 0.5, up to 0.8 | `warn` |
| 0.5 or lower | `pass` |

The current handler treats an omitted score as zero. Always send an explicit score; a `pass` result does not establish that content is safe. A failed check attempts to open the agent's circuit breaker.

`content_hash` is metadata, not uploaded content for analysis. The current receipt uses a system marker in its signature field; do not treat it as cryptographic proof.


## OpenAPI

````yaml mint-openapi.yaml POST /v1/guardrails/check
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: []
  - BearerAuth: []
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: 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/guardrails/check:
    post:
      tags:
        - Machine Identity
      summary: Check Guardrail
      description: >-
        Records a caller-supplied score and applies thresholds: above 0.8 fails,
        above 0.5 warns, otherwise passes. Does not scan raw content or
        calculate an independent safety score.
      operationId: maip.guardrails.check
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_id:
                  type: string
                  description: Agent requesting the action
                  format: uuid
                check_type:
                  type: string
                content_hash:
                  type: string
                details: {}
                execution_id:
                  nullable: true
                  type: string
                guardrail_type:
                  type: string
                metadata: {}
                score:
                  type: number
              type: object
              required:
                - check_type
                - guardrail_type
                - agent_id
      responses:
        '200':
          description: Guardrail check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipGuardrailResult'
        '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:
    MaipGuardrailResult:
      type: object
      properties:
        allowed:
          type: boolean
        violations:
          type: array
          items:
            type: object
            properties:
              rule:
                type: string
              description:
                type: string
              severity:
                type: string
                enum:
                  - low
                  - medium
                  - high
                  - critical
        receipt_id:
          type: string
          format: uuid
    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
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT for user-initiated operations

````

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