openapi: 3.2.0
info:
  title: HumanMirror Forge API
  version: 1.0.0
  description: Five deterministic micro-tools for AI agents and automations.
servers:
- url: https://humanmirror.fr
tags:
- name: Forge
paths:
  /api/forge:
    get:
      summary: Get Forge service metadata and optional authenticated balance
      security:
      - {}
      - BearerAuth: []
      responses:
        '200':
          description: Forge service metadata
      tags:
      - Forge
      operationId: getApiForge
      x-operation-id-source: derived
  /api/forge/trial:
    post:
      summary: Create a 25-credit trial API key
      responses:
        '201':
          description: Trial key created
        '409':
          description: Trial already used for this network origin
      tags:
      - Forge
      operationId: postApiForgeTrial
      x-operation-id-source: derived
  /api/forge/run:
    post:
      summary: Run a Forge micro-tool
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgeRun'
      responses:
        '200':
          description: Tool result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgeSuccess'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgeError'
        '401':
          description: Invalid API key
        '402':
          description: Insufficient credits
        '429':
          description: Rate limited
      tags:
      - Forge
      operationId: postApiForgeRun
      x-operation-id-source: derived
components:
  schemas:
    ForgeRun:
      type: object
      required:
      - tool
      - input
      properties:
        tool:
          type: string
          enum:
          - clean_json
          - dedupe_records
          - normalize_entity
          - score_data_quality
          - detect_anomaly
        input: {}
        options:
          type: object
    ForgeError:
      type: object
      required:
      - ok
      - version
      - error
      properties:
        ok:
          const: false
        version:
          type: string
        request_id:
          type:
          - string
          - 'null'
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
    ForgeSuccess:
      type: object
      required:
      - ok
      - version
      - request_id
      - tool
      - result
      - usage
      properties:
        ok:
          const: true
        version:
          type: string
        request_id:
          type: string
        tool:
          type: string
        result:
          type: object
        usage:
          type: object
          properties:
            credits_used:
              type: integer
            credits_remaining:
              type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: hm_forge_*