openapi: 3.2.0
info:
  title: MoltGuard Agent Flags API
  version: 1.5.0
  description: 'Trust & Integrity Service for the x402 Agent Economy. Sub-API of MolTrust Trust Registry (api.moltrust.ch). See also: https://api.moltrust.ch/openapi.json (parent service).'
  contact:
    name: CryptoKRI GmbH
    url: https://moltrust.ch
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.moltrust.ch/guard
  description: Production
security: []
tags:
- name: agent-flags
  description: Anomaly flag tracking + record
paths:
  /api/flags:
    get:
      tags:
      - agent-flags
      summary: List active anomaly flags
      operationId: listFlags
      responses:
        '200':
          description: Flag list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagList'
  /api/flags/record:
    post:
      tags:
      - agent-flags
      summary: Record a new anomaly flag
      operationId: recordFlag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagRecordResult'
  /api/flags/track-record:
    get:
      tags:
      - agent-flags
      summary: Aggregated flag track-record (open vs resolved)
      operationId: getFlagTrackRecord
      responses:
        '200':
          description: Track record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagTrackRecord'
  /api/flags/{flagId}:
    get:
      tags:
      - agent-flags
      summary: Get a flag by id
      operationId: getFlag
      parameters:
      - name: flagId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Flag detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagSummary'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Short error code
        message:
          type: string
          description: Human-readable detail
      required:
      - error
    FlagTrackRecord:
      type: object
      additionalProperties: true
      properties:
        totalFlags:
          type: integer
        resolvedCount:
          type: integer
        openCount:
          type: integer
    FlagRecordResult:
      type: object
      additionalProperties: true
      properties:
        ok:
          type: boolean
        flagId:
          type: string
    FlagList:
      type: array
      items:
        $ref: '#/components/schemas/FlagSummary'
    FlagSummary:
      type: object
      additionalProperties: true
      properties:
        flagId:
          type: string
        severity:
          type: string
        target:
          type: string
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: 'x402 v2 payment receipt header. Format: "x402 <base64-encoded-receipt>". See https://x402.org/writing/x402-v2-launch.'