openapi: 3.1.0
info:
  title: Agent Payment Error Corpus API
  version: 0.1.0
  description: Hosted D1 corpus of agent-payment failure signatures across x402, AP2, ACP/MPP, MCP, and TAP. Paid endpoints settle via x402 USDC on Base.
servers:
  - url: https://agent-payment-error-corpus.mtree.workers.dev
x-pricing:
  endpoints:
    - method: POST
      path: /v1/agent-payments/diagnose_error
      price_usd: 0.10
    - method: POST
      path: /v1/agent-payments/error_families
      price_usd: 0.05
paths:
  /healthz:
    get:
      operationId: healthz
      responses:
        '200': { description: OK }
  /dataset/health:
    get:
      operationId: datasetHealth
      responses:
        '200': { description: Dataset freshness and coverage }
  /v1/agent-payments/diagnose_error:
    post:
      operationId: diagnoseAgentPaymentError
      summary: Diagnose likely root cause/remediation for an agent-payment error artifact.
      x-x402-price-usd: 0.10
      x402:
        price: '$0.10'
        network: base
        asset: USDC
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                protocol: { type: string, examples: [x402, AP2, MCP] }
                error: { type: string }
                message: { type: string }
                status: { oneOf: [{ type: string }, { type: number }] }
                headers: { type: object, additionalProperties: true }
                request: { type: object, additionalProperties: true }
                response: { type: object, additionalProperties: true }
                payment_requirements: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Ranked diagnosis with remediation and source evidence.
  /v1/agent-payments/error_families:
    post:
      operationId: listAgentPaymentErrorFamilies
      summary: List known error families with protocol, surface signal, root cause, remediation, severity, source URL, and last_seen.
      x-x402-price-usd: 0.05
      x402:
        price: '$0.05'
        network: base
        asset: USDC
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                protocol: { type: string }
                severity: { type: string, enum: [critical, high, medium, low] }
                limit: { type: integer, minimum: 1, maximum: 100, default: 50 }
      responses:
        '200':
          description: Error-family rows.
components:
  schemas:
    ErrorFamily:
      type: object
      properties:
        id: { type: string }
        protocol: { type: string }
        family: { type: string }
        surface_signal: { type: string }
        root_cause: { type: string }
        remediation: { type: string }
        severity: { type: string }
        source_url: { type: string }
        last_seen: { type: string, format: date-time }
