openapi: 3.2.0
info:
  title: MoltGuard Agent Graph 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-graph
  description: Endorsement graph score/neighbours/stats
paths:
  /api/graph/neighbours/{did}:
    get:
      tags:
      - agent-graph
      summary: Get endorsement-graph neighbours for a DID
      operationId: getGraphNeighbours
      parameters:
      - name: did
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Neighbours
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphNeighbours'
  /api/graph/score/{fromDid}/{toDid}:
    get:
      tags:
      - agent-graph
      summary: Compute graph-based trust score along an endorsement path
      operationId: getGraphScore
      parameters:
      - name: fromDid
        in: path
        required: true
        schema:
          type: string
      - name: toDid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Score edge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphScoreEdge'
  /api/graph/stats:
    get:
      tags:
      - agent-graph
      summary: Aggregate endorsement-graph statistics
      operationId: getGraphStats
      responses:
        '200':
          description: Stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphStats'
components:
  schemas:
    GraphScoreEdge:
      type: object
      additionalProperties: true
      properties:
        fromDid:
          type: string
        toDid:
          type: string
        score:
          type: number
        edgeType:
          type: string
    GraphStats:
      type: object
      additionalProperties: true
      properties:
        totalNodes:
          type: integer
        totalEdges:
          type: integer
        avgDegree:
          type: number
    GraphNeighbours:
      type: object
      additionalProperties: true
      properties:
        did:
          type: string
        neighbours:
          type: array
          items:
            type: object
            additionalProperties: true
  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.'