{
  "openapi": "3.1.0",
  "info": {
    "title": "esimgomobile API",
    "version": "1.0.0",
    "description": "Public read-only API for esimgomobile travel-eSIM tools and the published plan catalog. Catalog data is read live from esimgomobile.com (5-minute cache) with a versioned snapshot fallback; prices at esimgomobile.com/pricing are authoritative. Supplier-backed operations (order creation, provisioning, QR delivery, usage, account top-ups, suspend/revoke, SMS, webhooks) are pending supplier integration and are intentionally not exposed. The same 36 tools are available over MCP at POST /mcp."
  },
  "servers": [
    {
      "url": "https://mcp.esimgomobile.com"
    }
  ],
  "paths": {
    "/api/plans": {
      "get": {
        "operationId": "listPlans",
        "summary": "List published plans with filters and sorting",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "data_packs",
                "monthly",
                "day_passes"
              ],
              "default": "all"
            }
          },
          {
            "name": "max_price_usd",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "min_gb",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "single_country",
                "regional",
                "global"
              ],
              "default": "any"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "price",
                "gb",
                "per_gb"
              ],
              "default": "price"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered plan list with catalog metadata"
          }
        }
      }
    },
    "/api/plans/{id}": {
      "get": {
        "operationId": "getPlan",
        "summary": "One plan with price, allowance, validity, scope and per-GB unit price",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plan detail"
          },
          "404": {
            "description": "Unknown plan id"
          }
        }
      }
    },
    "/api/plans-compare": {
      "get": {
        "operationId": "comparePlans",
        "summary": "Compare 2-4 plans side by side with a best-value pick",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated plan ids"
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison with best_value id"
          },
          "400": {
            "description": "Fewer than 2 or more than 4 valid ids"
          }
        }
      }
    },
    "/api/orders/validate": {
      "post": {
        "operationId": "validateOrderDraft",
        "summary": "Dry-run order validation against the published catalog (no order placed, nothing charged, not a supplier quote)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan_id"
                ],
                "properties": {
                  "plan_id": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 1
                  },
                  "device_model": {
                    "type": "string"
                  },
                  "countries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result with published-price estimate"
          }
        }
      }
    },
    "/api/trip-plan": {
      "post": {
        "operationId": "planTrip",
        "summary": "Composite trip planner: data estimate, plan pick, per-country networks/freedom brief",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "countries",
                  "days",
                  "usage_profile"
                ],
                "properties": {
                  "countries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 10
                  },
                  "days": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 365
                  },
                  "usage_profile": {
                    "type": "string",
                    "enum": [
                      "light",
                      "moderate",
                      "heavy"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trip plan"
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/api/countries/{country}/networks": {
      "get": {
        "operationId": "countryNetworks",
        "summary": "Mobile networks, eSIM support, Wi-Fi and internet-freedom facts for one country",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country brief"
          },
          "404": {
            "description": "Country not in reference"
          }
        }
      }
    },
    "/api/countries": {
      "get": {
        "operationId": "listCountries",
        "summary": "Countries in the built-in reference with eSIM support and network summary",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country list"
          }
        }
      }
    },
    "/api/countries/{country}": {
      "get": {
        "operationId": "getCountry",
        "summary": "One country brief (same data as /networks)",
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country brief"
          },
          "404": {
            "description": "Country not in reference"
          }
        }
      }
    },
    "/api/devices": {
      "get": {
        "operationId": "deviceCompatibility",
        "summary": "eSIM device families, or check one model with ?model=",
        "parameters": [
          {
            "name": "model",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Device data"
          }
        }
      }
    },
    "/api/guides/installation": {
      "get": {
        "operationId": "installationGuides",
        "summary": "eSIM install steps by os (ios|android) and method (qr|manual)",
        "parameters": [
          {
            "name": "os",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ios",
                "android"
              ]
            }
          },
          {
            "name": "method",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "qr",
                "manual"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Guides"
          },
          "400": {
            "description": "Bad filter"
          }
        }
      }
    },
    "/api/troubleshooting": {
      "get": {
        "operationId": "troubleshooting",
        "summary": "Fix steps by symptom",
        "parameters": [
          {
            "name": "symptom",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Steps"
          },
          "400": {
            "description": "Unknown symptom"
          }
        }
      }
    },
    "/api/apn": {
      "get": {
        "operationId": "apnSettings",
        "summary": "APN reference table, filter with ?carrier=",
        "parameters": [
          {
            "name": "carrier",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "APN rows"
          }
        }
      }
    },
    "/api/tools": {
      "get": {
        "operationId": "listTools",
        "summary": "List all 36 tools (names, titles, descriptions)",
        "responses": {
          "200": {
            "description": "Tool list"
          }
        }
      }
    },
    "/api/tools/{name}": {
      "post": {
        "operationId": "callTool",
        "summary": "Call any tool with a JSON body of arguments; returns the structured card result",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result"
          },
          "404": {
            "description": "Unknown tool"
          },
          "422": {
            "description": "Tool failed on the given arguments"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Service health and tool count",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "Model Context Protocol endpoint (Streamable HTTP, stateless JSON)",
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response"
          }
        }
      }
    }
  }
}