{
  "openapi": "3.1.0",
  "info": {
    "title": "Siima Public eSIM API",
    "version": "1.0.0",
    "summary": "Search travel eSIM plans and mint guest checkout links. No authentication.",
    "description": "The public subset of the Siima API that AI agents and third-party integrators may call. Every endpoint documented here is unauthenticated and safe to call on a user's behalf.\n\nPurchase flow: search plans -> create a checkout link -> hand the URL to the user. The user confirms their email with a 6-digit code and pays on siima.online; nothing is ordered or charged until they do. After payment the eSIM (QR code, one-tap activation link and manual installation codes) is emailed to them within about a minute.\n\nAn MCP server wrapping these same operations is available at https://api.siima.online/mcp (Streamable HTTP, no auth) and is the recommended integration path.",
    "contact": { "name": "Siima Support", "email": "support@siima.online", "url": "https://siima.online/ai" },
    "license": { "name": "Proprietary", "url": "https://siima.online/terms" }
  },
  "servers": [{ "url": "https://api.siima.online", "description": "Production" }],
  "externalDocs": { "description": "Siima for AI agents", "url": "https://siima.online/ai" },
  "paths": {
    "/api/v1/plans": {
      "get": {
        "operationId": "searchEsimPlans",
        "summary": "Search eSIM plans",
        "description": "Filtered, paginated list of purchasable eSIM data plans. Prices are in USD.",
        "parameters": [
          { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country code, e.g. JP.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "JP" },
          { "name": "region", "in": "query", "description": "Region name, e.g. Europe, Asia.", "schema": { "type": "string" } },
          { "name": "coverageType", "in": "query", "schema": { "type": "string", "enum": ["country", "regional", "global"] } },
          { "name": "coverageLabel", "in": "query", "description": "Provider coverage name, e.g. \"Europe+\".", "schema": { "type": "string" } },
          { "name": "minDataGb", "in": "query", "schema": { "type": "number", "exclusiveMinimum": 0 } },
          { "name": "maxPriceUsd", "in": "query", "schema": { "type": "number", "exclusiveMinimum": 0 } },
          { "name": "durationDays", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 6000, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "A page of matching plans.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["data", "total", "page", "pageSize"],
                      "properties": {
                        "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } },
                        "total": { "type": "integer" },
                        "page": { "type": "integer" },
                        "pageSize": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/api/v1/plans/{id}": {
      "get": {
        "operationId": "getEsimPlan",
        "summary": "Get one eSIM plan",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "The plan.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": { "data": { "$ref": "#/components/schemas/Plan" } }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/checkout/links": {
      "post": {
        "operationId": "createCheckoutLink",
        "summary": "Create a guest checkout link",
        "description": "Mints a secure siima.online checkout URL for a plan. Creates no order and charges nothing — the returned URL is for the user to open. Rate limited.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["planId"],
                "properties": {
                  "planId": { "type": "string", "format": "uuid" },
                  "email": { "type": "string", "format": "email", "description": "Optional. Pre-fills the buyer's address at checkout; they still verify it with an emailed 6-digit code." },
                  "currency": { "type": "string", "enum": ["usd", "eur", "gbp"], "default": "usd" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout link created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["url", "amountCents", "currency", "planName"],
                      "properties": {
                        "url": { "type": "string", "format": "uri", "description": "Give this to the user. Final checkout total, all fees included." },
                        "orderId": { "type": ["string", "null"], "format": "uuid" },
                        "amountCents": { "type": "integer" },
                        "currency": { "type": "string", "enum": ["usd", "eur", "gbp"] },
                        "planName": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "responses": { "200": { "description": "Service is up." } }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid request.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Not found.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": {} } },
      "Plan": {
        "type": "object",
        "required": ["id", "name", "dataBytes", "durationDays", "priceUsd", "countries", "coverageType"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "providerId": { "type": "string" },
          "providerProductId": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "dataBytes": {
            "type": "integer",
            "description": "Data allowance in bytes. Unlimited plans report Number.MAX_SAFE_INTEGER (9007199254740991) — treat that as \"unlimited\", never as a byte count, and exclude it from per-GB arithmetic."
          },
          "durationDays": { "type": "integer" },
          "priceUsd": { "type": "number", "description": "Wholesale-derived base price in USD. The buyer's final total is returned by createCheckoutLink." },
          "regions": { "type": "array", "items": { "type": "string" } },
          "countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "ISO 3166-1 alpha-2 codes." },
          "coverageType": { "type": "string", "enum": ["country", "regional", "global"] },
          "coverageLabel": { "type": ["string", "null"] },
          "isActive": { "type": "boolean" },
          "creditBackPercent": { "type": "number" },
          "syncedAt": { "type": "string", "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}