{
  "openapi": "3.1.0",
  "info": {
    "title": "BanglaVerse Cloud API",
    "version": "1.0.0",
    "description": "Public and payable APIs provided by BanglaVerse Cloud (https://banglaverse.net) for Minecraft server telemetry, Spark performance report analysis, automated server provisioning, domain management, and Machine Payments Protocol (MPP) payment discovery.",
    "contact": {
      "name": "BanglaVerse Cloud Support",
      "url": "https://banglaverse.net",
      "email": "admin@banglaverse.net"
    }
  },
  "x-service-info": {
    "categories": [
      "game-hosting",
      "cloud-infrastructure",
      "minecraft",
      "developer-tools",
      "payments",
      "bdix"
    ],
    "description": "BanglaVerse Cloud provides ultra-low latency Minecraft gaming server hosting with BDIX peering, DDR5 memory, NVMe SSDs, server telemetry, and autonomous AI agent operations via Machine Payments Protocol (MPP).",
    "docs": {
      "homepage": "https://banglaverse.net",
      "llms": "https://banglaverse.net/llms.txt",
      "auth": "https://banglaverse.net/auth.md",
      "apiCatalog": "https://banglaverse.net/.well-known/api-catalog",
      "ucp": "https://banglaverse.net/.well-known/ucp"
    }
  },
  "servers": [
    {
      "url": "https://banglaverse.net",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api": {
      "get": {
        "summary": "Autonomous Agent API Gateway (x402 Protected)",
        "description": "Public and agent-native gateway for autonomous evaluations, server automation, and telemetry. Protected by the x402 Payment Protocol (https://x402.org).",
        "operationId": "getApiGateway",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "0.01",
          "currency": "USD",
          "description": "API query access fee"
        },
        "responses": {
          "200": {
            "description": "API Gateway access granted after x402 payment settlement"
          },
          "402": {
            "description": "Payment Required - returns x402 payment requirements for AI agents"
          }
        }
      }
    },
    "/api/server-status": {
      "get": {
        "summary": "Check Minecraft Server Status",
        "description": "Checks connectivity, ping latency, active player count, server version, and formatted MOTD for any Minecraft Java or Bedrock server.",
        "operationId": "getServerStatus",
        "parameters": [
          {
            "name": "ip",
            "in": "query",
            "required": true,
            "description": "The server hostname or IP address (e.g. play.hypixel.net)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "port",
            "in": "query",
            "required": false,
            "description": "The server port (defaults to 25565)",
            "schema": {
              "type": "integer",
              "default": 25565
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Server status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "online": {
                      "type": "boolean"
                    },
                    "ip": {
                      "type": "string"
                    },
                    "port": {
                      "type": "integer"
                    },
                    "hostname": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "players": {
                      "type": "object",
                      "properties": {
                        "online": {
                          "type": "integer"
                        },
                        "max": {
                          "type": "integer"
                        }
                      }
                    },
                    "motd": {
                      "type": "object",
                      "properties": {
                        "clean": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "html": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "ping": {
                      "type": "number",
                      "description": "Latency in milliseconds"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters"
          }
        }
      }
    },
    "/api/spark-analyzer": {
      "post": {
        "summary": "Analyze Minecraft Spark Profiler Report",
        "description": "Parses a Spark profiler report link, identifies performance bottlenecks (high MSPT, entity tick lag, garbage collection pauses), and generates tailored server optimization recommendations.",
        "operationId": "analyzeSparkReport",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "URL to the Spark profiler report (e.g. https://spark.lucko.me/abc123xyz)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Performance report analyzed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metrics": {
                      "type": "object"
                    },
                    "recommendations": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid report URL"
          }
        }
      }
    },
    "/api/domain-check": {
      "get": {
        "summary": "Domain Availability Check",
        "description": "Checks registration availability for a domain name via WHOIS.",
        "operationId": "checkDomain",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Domain name to check (e.g. example.com)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Availability status retrieved successfully"
          }
        }
      }
    },
    "/api/domain-prices": {
      "get": {
        "summary": "Get TLD Pricing",
        "description": "Retrieves current domain registration prices across supported TLDs.",
        "operationId": "getDomainPrices",
        "responses": {
          "200": {
            "description": "Domain pricing retrieved successfully"
          }
        }
      }
    },
    "/api/server/provision": {
      "post": {
        "summary": "Provision Minecraft Game Server",
        "description": "Orders and provisions an instant Minecraft gaming server instance with BDIX connectivity, DDR5 RAM, and NVMe SSD storage.",
        "operationId": "provisionServer",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "2.30",
          "currency": "USD",
          "description": "Instant Minecraft server provisioning (Wood Package: 2GB DDR5 RAM, 200% vCPU, Unlimited NVMe)",
          "offers": [
            {
              "intent": "charge",
              "method": "tempo",
              "amount": "2.30",
              "currency": "USD",
              "description": "Tempo machine payment"
            },
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "250",
              "currency": "BDT",
              "description": "Stripe checkout"
            },
            {
              "intent": "charge",
              "method": "card",
              "amount": "250",
              "currency": "BDT",
              "description": "Credit/Debit Card payment"
            },
            {
              "intent": "charge",
              "method": "lightning",
              "amount": "2500",
              "currency": "sats",
              "description": "Bitcoin Lightning payment"
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan",
                  "serverName"
                ],
                "properties": {
                  "plan": {
                    "type": "string",
                    "enum": [
                      "wood",
                      "stone",
                      "iron",
                      "gold",
                      "redstone",
                      "diamond"
                    ],
                    "description": "Hosting package tier"
                  },
                  "serverName": {
                    "type": "string",
                    "description": "Custom server identifier"
                  },
                  "software": {
                    "type": "string",
                    "default": "purpur",
                    "enum": [
                      "purpur",
                      "paper",
                      "spigot",
                      "fabric",
                      "forge"
                    ],
                    "description": "Server software core"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server provisioned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "serverId": {
                      "type": "string"
                    },
                    "ip": {
                      "type": "string"
                    },
                    "port": {
                      "type": "integer"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid server parameters"
          },
          "402": {
            "description": "Payment Required - Machine Payments Protocol (MPP) challenge with payment details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "payment_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/server/renew": {
      "post": {
        "summary": "Renew Minecraft Server Subscription",
        "description": "Renews an active Minecraft server subscription for one billing month.",
        "operationId": "renewServer",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "250",
          "currency": "BDT",
          "description": "Monthly hosting renewal for Wood Package",
          "offers": [
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "250",
              "currency": "BDT",
              "description": "Stripe automated recurring billing"
            },
            {
              "intent": "charge",
              "method": "tempo",
              "amount": "2.30",
              "currency": "USD",
              "description": "Tempo payment"
            },
            {
              "intent": "charge",
              "method": "card",
              "amount": "250",
              "currency": "BDT",
              "description": "Credit/Debit Card payment"
            },
            {
              "intent": "charge",
              "method": "lightning",
              "amount": "2500",
              "currency": "sats",
              "description": "Bitcoin Lightning payment"
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "serverId"
                ],
                "properties": {
                  "serverId": {
                    "type": "string"
                  },
                  "months": {
                    "type": "integer",
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server renewed successfully"
          },
          "402": {
            "description": "Payment Required - Machine Payments Protocol (MPP) challenge with payment details"
          }
        }
      }
    },
    "/api/domain/register": {
      "post": {
        "summary": "Register Domain Name",
        "description": "Registers a domain name (.bd, .com, .net, etc.) with automated DNS configuration.",
        "operationId": "registerDomain",
        "x-payment-info": {
          "intent": "charge",
          "method": "card",
          "amount": "1200",
          "currency": "BDT",
          "description": "1-year domain registration fee",
          "offers": [
            {
              "intent": "charge",
              "method": "card",
              "amount": "1200",
              "currency": "BDT",
              "description": "Credit/Debit Card payment"
            },
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "1200",
              "currency": "BDT",
              "description": "Stripe payment"
            },
            {
              "intent": "charge",
              "method": "tempo",
              "amount": "10.50",
              "currency": "USD",
              "description": "Tempo payment"
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "years": {
                    "type": "integer",
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Domain registered successfully"
          },
          "402": {
            "description": "Payment Required - Machine Payments Protocol (MPP) challenge with payment details"
          }
        }
      }
    },
    "/api/spark-analyzer/deep-audit": {
      "post": {
        "summary": "Spark Profiler Deep AI Audit Session",
        "description": "Interactive multi-tick profiler session analyzing JVM garbage collection pauses, thread locks, and entity tick performance.",
        "operationId": "startSparkDeepAuditSession",
        "x-payment-info": {
          "intent": "session",
          "method": "tempo",
          "amount": "0.50",
          "currency": "USD",
          "description": "Interactive deep Spark performance audit session",
          "offers": [
            {
              "intent": "session",
              "method": "tempo",
              "amount": "0.50",
              "currency": "USD",
              "description": "Tempo streaming session payment"
            },
            {
              "intent": "session",
              "method": "stripe",
              "amount": "55",
              "currency": "BDT",
              "description": "Stripe metered session"
            },
            {
              "intent": "session",
              "method": "lightning",
              "amount": "500",
              "currency": "sats",
              "description": "Lightning Network per-session payment"
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "durationMinutes": {
                    "type": "integer",
                    "default": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit session initialized"
          },
          "402": {
            "description": "Payment Required - Machine Payments Protocol (MPP) session challenge"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "mppPayment": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "description": "Machine Payments Protocol (MPP) payment authorization credential"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 / Agent Auth bearer token"
      }
    }
  }
}