{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan Visa Renewal Window Check API",
    "version": "1.0.0",
    "description": "When can you renew your visa in Japan? See the day your renewal window opens (3 months before expiry), your last day, the 2-month special period while ISA decides, the 2026-10-01 fee for the period you expect, and permanent-resident card renewal dates under the June 2026 card rules.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp"
  },
  "servers": [
    {
      "url": "https://japan-visa-renewal.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanVisaRenewalCheck",
        "summary": "When can I renew my visa / residence card in Japan? Window, last day, special period, fee",
        "description": "Applies ISA's renewal rules (as of 2026-11-08). Period of stay (在留期間更新): window opens 3 months before expiry when the current period is 6 months or longer (any time before expiry for shorter periods; earlier only for listed unavoidable reasons); last day is the expiry date; if you applied in time and no decision has come, the special period lets you stay until the decision or 2 months after expiry. Fee by period granted (2026-10-01 table: counter ¥10,000–¥75,000, online ¥10,000–¥65,000 + ¥330/¥550). Permanent residents / HSP(ii) (在留カード有効期間更新): free, from 3 months before card expiry (6 months for old cards ending at the 16th birthday); new-format cards from 2026-06-14 last until the 10th birthday after issue (5th if under 18). Returns verdict (too_early | open | urgent | pending | special_period | expired), summary, windowOpens, lastDay, daysLeft, specialPeriodEnd, fee, card16, nextCardValidity, deadlines, actions, warnings, sources, disclaimer.\n\nExample: https://japan-visa-renewal.vercel.app/api/check?expiryDate=2027-03-20&currentPeriodMonths=12&holder=fixed",
        "parameters": [
          {
            "name": "expiryDate",
            "in": "query",
            "required": true,
            "description": "YYYY-MM-DD period-of-stay expiry on your residence card (for permanent / hsp2: the card's validity expiry). Aliases: expiry, periodExpiry, cardExpiry, 満了日.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD period-of-stay expiry on your residence card (for permanent / hsp2: the card's validity expiry). Aliases: expiry, periodExpiry, cardExpiry, 満了日."
            }
          },
          {
            "name": "holder",
            "in": "query",
            "required": false,
            "description": "fixed (any status with a period of stay) | permanent (永住者) | hsp2 (高度専門職2号). Aliases: pr, 永住…",
            "schema": {
              "type": "string",
              "description": "fixed (any status with a period of stay) | permanent (永住者) | hsp2 (高度専門職2号). Aliases: pr, 永住…",
              "enum": [
                "fixed",
                "permanent",
                "hsp2"
              ],
              "default": "fixed"
            }
          },
          {
            "name": "currentPeriodMonths",
            "in": "query",
            "required": false,
            "description": "Length of your current period of stay: months (12) or years (3y). Under 6 months removes the 3-month rule.",
            "schema": {
              "type": "string",
              "description": "Length of your current period of stay: months (12) or years (3y). Under 6 months removes the 3-month rule.",
              "default": "12"
            }
          },
          {
            "name": "expectedGrantMonths",
            "in": "query",
            "required": false,
            "description": "Period you expect ISA to grant, for the fee band (default = current period). Months or years (5y).",
            "schema": {
              "type": "string",
              "description": "Period you expect ISA to grant, for the fee band (default = current period). Months or years (5y)."
            }
          },
          {
            "name": "appliedDate",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD if you already applied (turns on special-period logic).",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD if you already applied (turns on special-period logic)."
            }
          },
          {
            "name": "birthDate",
            "in": "query",
            "required": false,
            "description": "Optional YYYY-MM-DD; enables the under-16 card rule and the next card's validity.",
            "schema": {
              "type": "string",
              "description": "Optional YYYY-MM-DD; enables the under-16 card rule and the next card's validity."
            }
          },
          {
            "name": "cardIssueDate",
            "in": "query",
            "required": false,
            "description": "Optional YYYY-MM-DD card issue date (cards from 2026-06-14 follow new validity rules).",
            "schema": {
              "type": "string",
              "description": "Optional YYYY-MM-DD card issue date (cards from 2026-06-14 follow new validity rules)."
            }
          },
          {
            "name": "method",
            "in": "query",
            "required": false,
            "description": "counter (revenue stamps) or online.",
            "schema": {
              "type": "string",
              "description": "counter (revenue stamps) or online.",
              "enum": [
                "counter",
                "online"
              ],
              "default": "counter"
            }
          },
          {
            "name": "wantSpecialCard",
            "in": "query",
            "required": false,
            "description": "You want the 特定在留カード (residence card + My Number card).",
            "schema": {
              "type": "boolean",
              "description": "You want the 特定在留カード (residence card + My Number card).",
              "default": false
            }
          },
          {
            "name": "today",
            "in": "query",
            "required": false,
            "description": "Override today's date (default: today in Japan).",
            "schema": {
              "type": "string",
              "description": "Override today's date (default: today in Japan)."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      },
      "post": {
        "operationId": "japanVisaRenewalCheckPost",
        "summary": "When can I renew my visa / residence card in Japan? Window, last day, special period, fee (JSON body)",
        "description": "Applies ISA's renewal rules (as of 2026-11-08). Period of stay (在留期間更新): window opens 3 months before expiry when the current period is 6 months or longer (any time before expiry for shorter periods; earlier only for listed unavoidable reasons); last day is the expiry date; if you applied in time and no decision has come, the special period lets you stay until the decision or 2 months after expiry. Fee by period granted (2026-10-01 table: counter ¥10,000–¥75,000, online ¥10,000–¥65,000 + ¥330/¥550). Permanent residents / HSP(ii) (在留カード有効期間更新): free, from 3 months before card expiry (6 months for old cards ending at the 16th birthday); new-format cards from 2026-06-14 last until the 10th birthday after issue (5th if under 18). Returns verdict (too_early | open | urgent | pending | special_period | expired), summary, windowOpens, lastDay, daysLeft, specialPeriodEnd, fee, card16, nextCardValidity, deadlines, actions, warnings, sources, disclaimer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "expiryDate"
                ],
                "properties": {
                  "expiryDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD period-of-stay expiry on your residence card (for permanent / hsp2: the card's validity expiry). Aliases: expiry, periodExpiry, cardExpiry, 満了日."
                  },
                  "holder": {
                    "type": "string",
                    "description": "fixed (any status with a period of stay) | permanent (永住者) | hsp2 (高度専門職2号). Aliases: pr, 永住…",
                    "enum": [
                      "fixed",
                      "permanent",
                      "hsp2"
                    ],
                    "default": "fixed"
                  },
                  "currentPeriodMonths": {
                    "type": "string",
                    "description": "Length of your current period of stay: months (12) or years (3y). Under 6 months removes the 3-month rule.",
                    "default": "12"
                  },
                  "expectedGrantMonths": {
                    "type": "string",
                    "description": "Period you expect ISA to grant, for the fee band (default = current period). Months or years (5y)."
                  },
                  "appliedDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD if you already applied (turns on special-period logic)."
                  },
                  "birthDate": {
                    "type": "string",
                    "description": "Optional YYYY-MM-DD; enables the under-16 card rule and the next card's validity."
                  },
                  "cardIssueDate": {
                    "type": "string",
                    "description": "Optional YYYY-MM-DD card issue date (cards from 2026-06-14 follow new validity rules)."
                  },
                  "method": {
                    "type": "string",
                    "description": "counter (revenue stamps) or online.",
                    "enum": [
                      "counter",
                      "online"
                    ],
                    "default": "counter"
                  },
                  "wantSpecialCard": {
                    "type": "boolean",
                    "description": "You want the 特定在留カード (residence card + My Number card).",
                    "default": false
                  },
                  "today": {
                    "type": "string",
                    "description": "Override today's date (default: today in Japan)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      }
    },
    "/api/rules": {
      "get": {
        "operationId": "japanVisaRenewalRules",
        "summary": "Japan renewal rules: period-of-stay window (3 months before expiry), special period (2 months), 2026-10-01 fee bands, residence card validity renewal (PR / HSP ii), 2026-06-14 card rules, sources",
        "description": "Returns the rules the checker applies, with official sources and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}