{
  "openapi": "3.1.0",
  "info": {
    "title": "Reloadpi Catalog API",
    "description": "Public read-only API for browsing Reloadpi's catalog of gift vouchers, mobile topups and eSIM plans. All products are payable with cryptocurrency. No authentication required. Each product includes a buy_url linking directly to checkout on reloadpi.com.",
    "version": "1.0.0",
    "contact": {
      "name": "Reloadpi Support",
      "url": "https://reloadpi.com/community/support",
      "email": "support@reloadpi.com"
    },
    "license": {
      "name": "Public",
      "url": "https://reloadpi.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://shoppi-backend.onrender.com/ai",
      "description": "Production API"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Entry points for AI agents to understand what Reloadpi offers"
    },
    {
      "name": "Vouchers",
      "description": "Gift cards and vouchers for brands worldwide — Amazon, Steam, Netflix, iTunes, Xbox and hundreds more"
    },
    {
      "name": "Topups",
      "description": "Mobile airtime and data topups for operators in 100+ countries"
    },
    {
      "name": "eSIMs",
      "description": "Travel eSIM data plans with global coverage"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Discovery"],
        "summary": "API index",
        "description": "Entry point for AI agents. Returns a summary of what Reloadpi sells, accepted cryptocurrencies, and links to all catalog endpoints.",
        "operationId": "getIndex",
        "responses": {
          "200": {
            "description": "Shop overview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IndexResponse"
                },
                "example": {
                  "name": "Reloadpi",
                  "description": "Instant digital shop: gift vouchers, mobile topups and eSIMs — all payable with crypto. No card, no KYC.",
                  "accepts_crypto": ["BTC", "ETH", "USDT", "LTC", "XMR"],
                  "delivery": "instant",
                  "website": "https://reloadpi.com",
                  "catalogs": {
                    "vouchers": "/ai/vouchers",
                    "topups": "/ai/topups",
                    "esims": "/ai/esims"
                  },
                  "capabilities": "/ai/capabilities"
                }
              }
            }
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Shop capabilities",
        "description": "Returns all supported countries, regions, brands, subtypes and accepted cryptocurrencies. Use this before querying specific catalogs to check if Reloadpi can fulfil a user request.",
        "operationId": "getCapabilities",
        "responses": {
          "200": {
            "description": "Full capabilities including countries, brands and payment methods",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CapabilitiesResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/vouchers": {
      "get": {
        "tags": ["Vouchers"],
        "summary": "Search gift vouchers",
        "description": "Search and filter gift vouchers by country, brand, category or free text. Returns paginated results each with a buy_url for direct checkout. Supports brands like Amazon, Steam, Netflix, Spotify, iTunes, Xbox, PlayStation, Google Play, Starbucks, Nike, Zalando and hundreds more.",
        "operationId": "searchVouchers",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "ISO 3166-1 alpha-2 country code (e.g. NG, US, GB, DE, IT, GH, KE)",
            "schema": { "type": "string", "example": "NG" }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Brand name (e.g. Amazon, Steam, Netflix, iTunes, Xbox)",
            "schema": { "type": "string", "example": "Amazon" }
          },
          {
            "name": "subType",
            "in": "query",
            "description": "Product category filter",
            "schema": {
              "type": "string",
              "enum": [
                "Gaming & Entertainment",
                "Restaurant",
                "Food & Beverage",
                "Shopping",
                "Travel & Experience",
                "Supermarket",
                "Electronics",
                "Digital Apps",
                "Health & Beauty",
                "Sports & Outdoors",
                "Utilities",
                "Home & Garden",
                "Clothing & Accessories",
                "General Merchandise",
                "Dating",
                "EGIFT"
              ],
              "example": "Gaming & Entertainment"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Free text search across brand names and descriptions",
            "schema": { "type": "string", "example": "restaurant" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page (max 50)",
            "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0, "minimum": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of voucher offers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoucherSearchResult"
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/topups": {
      "get": {
        "tags": ["Topups"],
        "summary": "Search mobile topups",
        "description": "Search mobile airtime and data topup offers by country, operator or region. Supports MTN, Airtel, Glo, Vodafone, Orange, Digicel and more in 100+ countries.",
        "operationId": "searchTopups",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "ISO 3166-1 alpha-2 country code (e.g. NG, GH, KE, IN, PH, BR)",
            "schema": { "type": "string", "example": "NG" }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Mobile operator name (e.g. MTN, Airtel, Glo, Vodafone)",
            "schema": { "type": "string", "example": "MTN" }
          },
          {
            "name": "subType",
            "in": "query",
            "description": "Topup type",
            "schema": {
              "type": "string",
              "enum": ["data", "voice", "bundle"],
              "example": "data"
            }
          },
          {
            "name": "region",
            "in": "query",
            "description": "Region name",
            "schema": {
              "type": "string",
              "enum": [
                "Africa",
                "Asia",
                "Southeast Asia",
                "South Asia",
                "Western Europe",
                "Eastern Europe",
                "Middle East and North Africa",
                "North America",
                "South America",
                "Central America",
                "Caribbean",
                "Oceania"
              ],
              "example": "Africa"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page (max 50)",
            "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0, "minimum": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of topup offers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopupSearchResult"
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/esims": {
      "get": {
        "tags": ["eSIMs"],
        "summary": "Search eSIM plans",
        "description": "Search travel eSIM data plans by country, region or data size. Global coverage — Europe, Asia, Americas, Africa, Middle East. Instant activation after purchase.",
        "operationId": "searchEsims",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "ISO 3166-1 alpha-2 country code (e.g. IT, US, JP, DE, ES, FR)",
            "schema": { "type": "string", "example": "IT" }
          },
          {
            "name": "regions",
            "in": "query",
            "description": "Region name for multi-country plans",
            "schema": {
              "type": "string",
              "enum": ["Europe", "Asia", "Americas", "Africa", "Middle East", "Global"],
              "example": "Europe"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Free text search (e.g. '10GB', '30 days', 'unlimited')",
            "schema": { "type": "string", "example": "10GB" }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "eSIM provider brand",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page (max 50)",
            "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0, "minimum": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of eSIM plans",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EsimSearchResult"
                }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IndexResponse": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "accepts_crypto": {
            "type": "array",
            "items": { "type": "string" }
          },
          "delivery": { "type": "string" },
          "website": { "type": "string", "format": "uri" },
          "catalogs": {
            "type": "object",
            "properties": {
              "vouchers": { "type": "string" },
              "topups": { "type": "string" },
              "esims": { "type": "string" }
            }
          },
          "capabilities": { "type": "string" }
        }
      },
      "CapabilitiesResponse": {
        "type": "object",
        "properties": {
          "accepts_crypto": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["BTC", "ETH", "USDT", "LTC", "XMR"]
          },
          "delivery": { "type": "string", "example": "instant" },
          "no_account_required": { "type": "boolean", "example": true },
          "vouchers": {
            "type": "object",
            "properties": {
              "countries": { "type": "array", "items": { "type": "string" } },
              "subtypes": { "type": "array", "items": { "type": "string" } },
              "regions": { "type": "array", "items": { "type": "string" } },
              "brands": { "type": "array", "items": { "type": "string" } },
              "query_url": { "type": "string" }
            }
          },
          "topups": {
            "type": "object",
            "properties": {
              "countries": { "type": "array", "items": { "type": "string" } },
              "regions": { "type": "array", "items": { "type": "string" } },
              "query_url": { "type": "string" }
            }
          },
          "esims": {
            "type": "object",
            "properties": {
              "coverage": { "type": "string", "example": "global" },
              "query_url": { "type": "string" }
            }
          }
        }
      },
      "MoneyLike": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "currency": { "type": "string", "example": "USD" },
              "currencyDivisor": { "type": "integer", "example": 100 },
              "fixed": { "type": "number", "example": 1000 },
              "min": { "type": "number" },
              "max": { "type": "number" }
            }
          },
          { "type": "number" }
        ]
      },
      "VoucherOffer": {
        "type": "object",
        "properties": {
          "offerId": { "type": "string", "example": "AMAZON_US_10" },
          "brand": { "type": "string", "example": "Amazon" },
          "brandName": { "type": "string", "example": "Amazon" },
          "country": { "type": "string", "example": "US" },
          "regions": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["North America"]
          },
          "subTypes": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["General Merchandise"]
          },
          "description": { "type": "string" },
          "shortNotes": { "type": "string" },
          "productType": { "type": "string", "example": "VOUCHER" },
          "price": { "$ref": "#/components/schemas/MoneyLike" },
          "image": { "type": "string", "format": "uri" },
          "buy_url": {
            "type": "string",
            "format": "uri",
            "description": "Direct link to purchase this product on reloadpi.com",
            "example": "https://reloadpi.com/vouchers/offer/AMAZON_US_10"
          }
        }
      },
      "VoucherSearchResult": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "example": 148 },
          "limit": { "type": "integer", "example": 20 },
          "offset": { "type": "integer", "example": 0 },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/VoucherOffer" }
          }
        }
      },
      "TopupOffer": {
        "type": "object",
        "properties": {
          "offerId": { "type": "string", "example": "MTN_NG_DATA_1GB" },
          "brand": { "type": "string", "example": "MTN" },
          "brandName": { "type": "string", "example": "MTN Nigeria" },
          "country": { "type": "string", "example": "NG" },
          "regions": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Africa"]
          },
          "subTypes": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["data"]
          },
          "dataGb": { "type": "number", "example": 1 },
          "dataUnlimited": { "type": "boolean" },
          "durationDays": { "type": "integer", "example": 30 },
          "voiceMinutes": { "type": "integer" },
          "smsNumber": { "type": "integer" },
          "price": { "$ref": "#/components/schemas/MoneyLike" },
          "buy_url": {
            "type": "string",
            "format": "uri",
            "description": "Direct link to purchase this topup on reloadpi.com",
            "example": "https://reloadpi.com/topups/offer/MTN_NG_DATA_1GB"
          }
        }
      },
      "TopupSearchResult": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "facets": {
            "type": "object",
            "properties": {
              "countries": { "type": "array", "items": { "type": "string" } },
              "regions": { "type": "array", "items": { "type": "string" } },
              "brands": { "type": "array", "items": { "type": "string" } },
              "subTypes": { "type": "array", "items": { "type": "string" } }
            }
          },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TopupOffer" }
          }
        }
      },
      "EsimPlan": {
        "type": "object",
        "properties": {
          "offerId": { "type": "string", "example": "ESIM_IT_10GB_30D" },
          "brand": { "type": "string" },
          "country": { "type": "string", "example": "IT" },
          "regions": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Europe"]
          },
          "dataGb": { "type": "number", "example": 10 },
          "dataUnlimited": { "type": "boolean", "example": false },
          "durationDays": { "type": "integer", "example": 30 },
          "price": { "$ref": "#/components/schemas/MoneyLike" },
          "subTypes": { "type": "array", "items": { "type": "string" } },
          "shortNotes": { "type": "string" },
          "buy_url": {
            "type": "string",
            "format": "uri",
            "description": "Direct link to purchase this eSIM plan on reloadpi.com",
            "example": "https://reloadpi.com/esims/offer/ESIM_IT_10GB_30D"
          }
        }
      },
      "EsimSearchResult": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/EsimPlan" }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Too many requests — rate limit is 60 requests per minute per IP",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string", "example": "Too many requests" },
                "retryAfterSeconds": { "type": "integer", "example": 30 }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  }
}