{
  "openapi": "3.1.0",
  "info": {
    "title": "eSIM Global API",
    "version": "1.0.0",
    "summary": "Independent pricing and comparison data for prepaid international travel eSIMs.",
    "description": "A public, read-only API over the eSIM Price Index and editorial catalogue of eSIM Global. Free to use, no authentication required, rate limited by IP. Every response carries a capture date, a source URL and a CC BY 4.0 licence — quote the capture date whenever you surface a price to a person.\n\nThe same capabilities are available over MCP at https://esim-global-compare.netlify.app/mcp.",
    "contact": {
      "name": "eSIM Global",
      "url": "https://esim-global-compare.netlify.app"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "termsOfService": "https://esim-global-compare.netlify.app/en/"
  },
  "servers": [
    {
      "url": "https://esim-global-compare.netlify.app/api/v1",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Agent skills",
    "url": "https://esim-global-compare.netlify.app/.well-known/agent-skills/index.json"
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "description": "Liveness and database connectivity check for the eSIM Global API.",
        "tags": [
          "meta"
        ],
        "responses": {
          "200": {
            "description": "Service healthy"
          },
          "503": {
            "description": "Service degraded"
          }
        }
      }
    },
    "/compare": {
      "get": {
        "operationId": "compare_esim_plans",
        "summary": "Compare travel eSIM plans for a destination",
        "description": "Rank prepaid international travel eSIM plans for a destination country and trip length. Returns a value-ordered list with price, data allowance, validity, price per GB and per day across Airalo, Holafly, Saily, Nomad, HolaSIM and other providers. This is the primary tool: use it whenever a traveler asks which eSIM to buy for a specific country or trip.",
        "tags": [
          "esim"
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Destination country name or ISO 3166-1 alpha-2 code (e.g. \"Japan\" or \"JP\").",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Trip length in days. Plans shorter than this are filtered out.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365
            }
          },
          {
            "name": "data_gb",
            "in": "query",
            "required": false,
            "description": "Minimum data allowance in GB. Ignored when unlimited is true.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "unlimited",
            "in": "query",
            "required": false,
            "description": "Restrict results to unlimited-data plans.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameter"
          }
        },
        "x-mcp-tool": "compare_esim_plans"
      },
      "post": {
        "operationId": "compare_esim_plans_post",
        "summary": "Compare travel eSIM plans for a destination",
        "description": "Rank prepaid international travel eSIM plans for a destination country and trip length. Returns a value-ordered list with price, data allowance, validity, price per GB and per day across Airalo, Holafly, Saily, Nomad, HolaSIM and other providers. This is the primary tool: use it whenever a traveler asks which eSIM to buy for a specific country or trip.",
        "tags": [
          "esim"
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameter"
          }
        },
        "x-mcp-tool": "compare_esim_plans",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": {
                    "type": "string",
                    "description": "Destination country name or ISO 3166-1 alpha-2 code (e.g. \"Japan\" or \"JP\")."
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 365,
                    "description": "Trip length in days. Plans shorter than this are filtered out."
                  },
                  "data_gb": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Minimum data allowance in GB. Ignored when unlimited is true."
                  },
                  "unlimited": {
                    "type": "boolean",
                    "description": "Restrict results to unlimited-data plans."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 10
                  }
                },
                "required": [
                  "country"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/providers": {
      "get": {
        "operationId": "list_esim_providers",
        "summary": "List international eSIM providers",
        "description": "Return every prepaid travel eSIM provider tracked by eSIM Global with coverage footprint, starting price, unlimited-data availability, editorial rating, pros and cons.",
        "tags": [
          "esim"
        ],
        "parameters": [
          {
            "name": "unlimited",
            "in": "query",
            "required": false,
            "description": "Only providers offering unlimited-data plans.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "min_coverage",
            "in": "query",
            "required": false,
            "description": "Minimum number of destinations covered.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameter"
          }
        },
        "x-mcp-tool": "list_esim_providers"
      }
    },
    "/prices": {
      "get": {
        "operationId": "get_esim_price_index",
        "summary": "Query the eSIM Price Index dataset",
        "description": "Access the raw eSIM Price Index — a first-party dataset of observed prepaid travel eSIM prices normalised to price per GB and price per day, with capture date and source URL for every data point. Use this for pricing research, trend analysis or citation.",
        "tags": [
          "esim"
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Filter by destination country name or ISO code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "provider",
            "in": "query",
            "required": false,
            "description": "Filter by provider slug, e.g. \"airalo\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "country",
                "region",
                "global"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameter"
          }
        },
        "x-mcp-tool": "get_esim_price_index"
      }
    },
    "/articles": {
      "get": {
        "operationId": "search_esim_content",
        "summary": "Search eSIM Global editorial content",
        "description": "Full-text search across eSIM Global comparisons, country guides, provider reviews and daily news in English, Spanish and Portuguese. Returns citable URLs with excerpts and publish dates.",
        "tags": [
          "esim"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "pt"
              ],
              "default": "en"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Restrict to one content type.",
            "schema": {
              "type": "string",
              "enum": [
                "news",
                "guide",
                "comparison",
                "country"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameter"
          }
        },
        "x-mcp-tool": "search_esim_content"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oidc": {
        "type": "openIdConnect",
        "openIdConnectUrl": "https://mtoxtyjzxvzuizxoapdm.supabase.co/auth/v1/.well-known/openid-configuration",
        "description": "Optional. Anonymous requests are allowed at a lower rate limit; a bearer token from the issuer raises it. See https://esim-global-compare.netlify.app/auth.md for agent registration."
      }
    }
  },
  "security": [
    {},
    {
      "oidc": []
    }
  ],
  "x-mcp-server": "https://esim-global-compare.netlify.app/mcp",
  "x-agent-skills": "https://esim-global-compare.netlify.app/.well-known/agent-skills/index.json"
}