{
  "openapi": "3.1.0",
  "info": {
    "title": "Alt eSIM — public agent APIs",
    "description": "Read-only catalog for travel data eSIMs, plus discovery pointers to the MCP server (search / recommend / Stripe checkout link). All prices USD. No auth on these public surfaces.",
    "version": "1.32.0",
    "contact": {
      "name": "Alt eSIM support",
      "email": "support@altesim.com",
      "url": "https://altesim.com/en/contact"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://altesim.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "catalog",
      "description": "Public read-only plan catalog"
    },
    {
      "name": "discovery",
      "description": "Machine-readable discovery files"
    },
    {
      "name": "mcp",
      "description": "Model Context Protocol (JSON-RPC over HTTP POST)"
    }
  ],
  "paths": {
    "/api/catalog": {
      "get": {
        "tags": ["catalog"],
        "summary": "List all fulfillable eSIM plans",
        "description": "Every active, fulfillable plan with USD price, SKU, planType/dataPerDayGb/totalGb, validity, carriers, and productUrl. No auth. CORS enabled. Cached ~7 days.",
        "operationId": "getCatalog",
        "responses": {
          "200": {
            "description": "Catalog payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "tags": ["mcp"],
        "summary": "MCP Streamable HTTP endpoint",
        "description": "JSON-RPC 2.0 Model Context Protocol server (protocol 2025-06-18). Stateless: one POST → one JSON response. Methods: initialize, tools/list, tools/call, ping, notifications/*. Tools: get_shop_facts, list_destinations, search_esim_plans, recommend_plans, get_esim_plan, create_checkout (returns Stripe payment_url; agent never handles cards), get_qr_code. No auth. Do not call create_checkout in automated benchmarks without a disposable email — it creates a real Stripe Checkout Session (unpaid until the buyer opens the link).",
        "operationId": "mcpJsonRpc",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-06-18",
                      "capabilities": {},
                      "clientInfo": { "name": "example", "version": "1.0" }
                    }
                  }
                },
                "toolsList": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 2,
                    "method": "tools/list"
                  }
                },
                "searchJapan": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 3,
                    "method": "tools/call",
                    "params": {
                      "name": "search_esim_plans",
                      "arguments": { "country": "japan" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted notification (no body)"
          },
          "405": {
            "description": "GET not supported — use POST"
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "MCP manifest",
        "operationId": "getMcpManifest",
        "responses": {
          "200": {
            "description": "MCP endpoint pointer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["name", "endpoint"],
                  "properties": {
                    "name": { "type": "string" },
                    "description": { "type": "string" },
                    "endpoint": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["discovery"],
        "summary": "LLM briefing",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "Markdown briefing for AI systems",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CatalogPlan": {
        "type": "object",
        "required": [
          "id",
          "sku",
          "title",
          "country",
          "region",
          "dataAmount",
          "planType",
          "validityDays",
          "priceUSD",
          "currency",
          "productUrl"
        ],
        "properties": {
          "id": { "type": "string" },
          "sku": { "type": "string", "example": "eSIM_Alt_JP_1DG1" },
          "title": { "type": "string" },
          "country": { "type": "string", "description": "Destination slug", "example": "japan" },
          "countryIso": { "type": ["string", "null"] },
          "region": { "type": "string" },
          "dataAmount": { "type": "string" },
          "planType": { "type": "string", "enum": ["daily", "total"] },
          "dataPerDayGb": { "type": ["number", "null"] },
          "totalGb": { "type": ["number", "null"] },
          "throttleKbps": { "type": ["number", "null"] },
          "validityDays": { "type": "integer" },
          "validUntil": {
            "type": ["string", "null"],
            "description": "Fixed expiry YYYY-MM-DD when set; prefer over validityDays for those SKUs"
          },
          "priceUSD": { "type": "number" },
          "currency": { "type": "string", "enum": ["USD"] },
          "carriers": { "type": "array", "items": { "type": "string" } },
          "coverage": { "type": "array", "items": { "type": "string" } },
          "productUrl": {
            "type": "string",
            "format": "uri",
            "description": "Human product page where this plan can be bought"
          }
        }
      },
      "CatalogResponse": {
        "type": "object",
        "required": ["brand", "site", "currency", "count", "plans", "agent_access"],
        "properties": {
          "brand": { "type": "string" },
          "site": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "currency": { "type": "string", "enum": ["USD"] },
          "pricing_note": { "type": "string" },
          "languages": { "type": "array", "items": { "type": "string" } },
          "agent_access": {
            "type": "object",
            "properties": {
              "catalog_json": { "type": "string", "format": "uri" },
              "mcp_endpoint": { "type": "string", "format": "uri" },
              "mcp_transport": { "type": "string" },
              "acp_product_feed": { "type": "string", "format": "uri" },
              "full_reference": { "type": "string", "format": "uri" },
              "how_to_buy": { "type": "string" }
            }
          },
          "count": { "type": "integer" },
          "plans": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CatalogPlan" }
          },
          "destinations": { "type": "array", "items": { "type": "object" } },
          "generated_at": { "type": "string", "format": "date-time" }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "number", "null"] },
          "method": { "type": "string" },
          "params": { "type": "object" }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": ["string", "number", "null"] },
          "result": {},
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}