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

> Record an LLM inference call within an orchestration for cost tracking and provenance auditing.

Records an individual LLM inference call that occurred within a running orchestration. Each inference record captures the model, provider, token counts, latency, cost, and content hashes -- enabling fine-grained cost attribution and provenance auditing of every AI decision.

This endpoint is called by agent runtimes after each LLM API call completes. The inference record is linked to the parent orchestration and included in the final transparency-log receipt.

### Authentication

<ParamField header="X-API-Key" type="string" required>
  API key with `orchestrations: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>

### Path Parameters

<ParamField path="id" type="string" required>
  Parent orchestration identifier (`maip-orch:ULID`). Must be in `running`
  status.
</ParamField>

### Request

<ParamField body="model" type="string" required>
  LLM model identifier (e.g. `claude-sonnet-4-20250514`, `gpt-4o`,
  `amazon.titan-text-express`).
</ParamField>

<ParamField body="provider" type="string" required>
  LLM provider. Accepted values: `openai`, `anthropic`, `bedrock`, `custom`.
</ParamField>

<ParamField body="prompt_tokens" type="integer">
  Number of input tokens consumed by the inference call.
</ParamField>

<ParamField body="completion_tokens" type="integer">
  Number of output tokens generated by the inference call.
</ParamField>

<ParamField body="latency_ms" type="integer">
  End-to-end latency of the inference call in milliseconds.
</ParamField>

<ParamField body="cost_cents" type="number">
  Cost of the inference call in US cents. Calculated by the agent runtime based
  on provider pricing.
</ParamField>

<ParamField body="input_hash" type="string">
  SHA-256 hex digest of the prompt input. Enables verification that the exact
  input can be reproduced.
</ParamField>

<ParamField body="output_hash" type="string">
  SHA-256 hex digest of the model output. Enables verification that the recorded
  output matches what was returned.
</ParamField>

### Response

<ResponseField name="inference_id" type="string">
  Unique identifier for this inference record.
</ResponseField>

<ResponseField name="orchestration_id" type="string">
  Parent orchestration identifier.
</ResponseField>

<ResponseField name="model" type="string">
  LLM model used.
</ResponseField>

<ResponseField name="provider" type="string">
  LLM provider.
</ResponseField>

<ResponseField name="prompt_tokens" type="integer">
  Input token count.
</ResponseField>

<ResponseField name="completion_tokens" type="integer">
  Output token count.
</ResponseField>

<ResponseField name="cost_cents" type="number">
  Inference cost in US cents.
</ResponseField>

<ResponseField name="recorded_at" type="string">
  ISO 8601 timestamp when the inference was recorded.
</ResponseField>


## OpenAPI

````yaml mint-openapi.yaml POST /v1/orchestrate/llm/inference
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/orchestrate/llm/inference:
    post:
      tags:
        - Machine Identity
      summary: LLM Inference with Receipt
      description: |
        Performs an LLM inference call on behalf of an agent. The call is logged
        with a receipt including token usage and cost for full auditability.
      operationId: maip.orchestrations.llmInference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
                - agent_id
              properties:
                model:
                  type: string
                  description: Model identifier (e.g. gpt-4, claude-3)
                prompt:
                  type: string
                  description: Input prompt
                agent_id:
                  type: string
                  format: uuid
                  description: Invoking agent
                parameters:
                  type: object
                  additionalProperties: true
                  description: Model parameters (temperature, max_tokens, etc.)
            example:
              model: claude-3-sonnet
              prompt: Analyze this dataset for anomalies
              agent_id: 550e8400-e29b-41d4-a716-446655440000
              parameters:
                temperature: 0.3
                max_tokens: 2048
      responses:
        '200':
          description: Inference result with receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipLlmInferenceResult'
        '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:
    MaipLlmInferenceResult:
      type: object
      properties:
        response:
          type: string
        receipt_id:
          type: string
          format: uuid
        tokens_used:
          type: integer
        cost:
          type: number
          format: float
    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

````