openapi: 3.2.0
info:
  title: HumanMirror AgentOps Trace API
  version: 1.0.0
  description: Deterministic operational utilities for AI-agent workflows. Authentication uses a HumanMirror Nexus API key.
servers:
- url: https://humanmirror.fr
tags:
- name: Trace
paths:
  /api/trace/issue:
    post:
      summary: Issue a verifiable Trace receipt
      security:
      - NexusBearer: []
      responses:
        '200':
          description: Receipt issued
        '401':
          description: Invalid Nexus key
        '402':
          description: Insufficient credits
      tags:
      - Trace
      operationId: postApiTraceIssue
      x-operation-id-source: derived
  /api/trace/verify:
    get:
      summary: Verify whether a Trace receipt exists
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Receipt exists
        '404':
          description: Receipt not found
      tags:
      - Trace
      operationId: getApiTraceVerify
      x-operation-id-source: derived
    post:
      summary: Verify a Trace receipt and optionally compare supplied payload hashes
      responses:
        '200':
          description: Verification result
        '404':
          description: Receipt not found
      tags:
      - Trace
      operationId: postApiTraceVerify
      x-operation-id-source: derived
components:
  securitySchemes:
    NexusBearer:
      type: http
      scheme: bearer
      bearerFormat: hm_nexus_*