{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan HSP Points Calculator API",
    "version": "1.0.0",
    "description": "Do I reach 70 or 80 points for Japan's Highly Skilled Professional visa (高度専門職)? Item-by-item breakdown for academic, specialized and management categories, the ¥3M salary floor, the permanent-residence fast track (70 → 3 years, 80 → 1 year), J-Skip and the bonus points you could still add.\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-hsp-points.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanHspPointsCheck",
        "summary": "Japan Highly Skilled Professional (高度専門職) points: does this profile reach 70 or 80 points, and what does it mean for PR?",
        "description": "Applies the HSP points ordinance (平成26年法務省令第37号, art. 1 and 2) to a profile for one of the three categories: academic (HSP i-a, 高度専門職1号イ), specialized (i-b, 1号ロ) or management (i-c, 1号ハ). Scores education, experience, salary (age-banded minimums for i-a / i-b: under 30 from ¥4M, 30–34 ¥5M, 35–39 ¥6M, 40+ ¥8M; i-c from ¥10M), age, research, Japanese qualifications, position and the bonus items (innovation-support employer 10/20, SME R&D 5, foreign qualification 5, Japanese degree 10, JLPT N1 15 / N2 10, growth project 10, top university 10, JICA 5, ¥100M investment 5, investment management 10, local-government support 10). Checks the ¥3M salary floor (i-b, i-c), the J-Skip (特別高度人材) criteria, the permanent-residence fast track (70 → 3 years, 80 → 1 year) and HSP (ii). Returns verdict (qualifies_80 | qualifies_70 | below_70 | below_salary_floor), total, breakdown [{item, points, basis}], pointsTo70, pointsTo80, pr, jSkip, couldAdd, warnings, pendingRevision, sources and a disclaimer.\n\nExample: https://japan-hsp-points.vercel.app/api/check?category=specialized&age=31&education=master&experienceYears=4&annualSalary=7500000&japanese=n2&qualifications=1",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": true,
            "description": "academic (research / teaching, HSP i-a), specialized (engineer, specialist, most employees, HSP i-b), management (executive / business owner, HSP i-c). Aliases: a/b/c, イ/ロ/ハ, researcher, engineer, ceo…",
            "schema": {
              "type": "string",
              "description": "academic (research / teaching, HSP i-a), specialized (engineer, specialist, most employees, HSP i-b), management (executive / business owner, HSP i-c). Aliases: a/b/c, イ/ロ/ハ, researcher, engineer, ceo…",
              "enum": [
                "academic",
                "specialized",
                "management"
              ]
            }
          },
          {
            "name": "education",
            "in": "query",
            "required": true,
            "description": "Highest degree: doctor, mba (MBA / MOT professional degree), master (incl. other professional degrees), bachelor, none.",
            "schema": {
              "type": "string",
              "description": "Highest degree: doctor, mba (MBA / MOT professional degree), master (incl. other professional degrees), bachelor, none.",
              "enum": [
                "doctor",
                "mba",
                "master",
                "bachelor",
                "none"
              ]
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "description": "Age on the application date. Required for academic and specialized unless birthDate is given.",
            "schema": {
              "type": "integer",
              "description": "Age on the application date. Required for academic and specialized unless birthDate is given."
            }
          },
          {
            "name": "birthDate",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD; used with applicationDate (default today in Japan) when age is not given.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD; used with applicationDate (default today in Japan) when age is not given."
            }
          },
          {
            "name": "annualSalary",
            "in": "query",
            "required": true,
            "description": "Expected annual pay in Japan in yen, including bonuses (e.g. 7500000). Or annualSalaryMan in 万円 (750).",
            "schema": {
              "type": "number",
              "description": "Expected annual pay in Japan in yen, including bonuses (e.g. 7500000). Or annualSalaryMan in 万円 (750)."
            }
          },
          {
            "name": "experienceYears",
            "in": "query",
            "required": false,
            "description": "Years of experience: in research/teaching (academic), in the work you will do (specialized), in business management (management).",
            "schema": {
              "type": "number",
              "description": "Years of experience: in research/teaching (academic), in the work you will do (specialized), in business management (management).",
              "default": 0
            }
          },
          {
            "name": "multipleDegrees",
            "in": "query",
            "required": false,
            "description": "Doctor / master / professional degrees in two or more fields (+5).",
            "schema": {
              "type": "boolean",
              "description": "Doctor / master / professional degrees in two or more fields (+5).",
              "default": false
            }
          },
          {
            "name": "researchItems",
            "in": "query",
            "required": false,
            "description": "Kinds of research achievement (patent; 3+ foreign-government grants; 3+ papers as corresponding author; other). Academic: 1 → 20, 2+ → 25. Specialized: 1+ → 15.",
            "schema": {
              "type": "integer",
              "description": "Kinds of research achievement (patent; 3+ foreign-government grants; 3+ papers as corresponding author; other). Academic: 1 → 20, 2+ → 25. Specialized: 1+ → 15.",
              "default": 0,
              "minimum": 0,
              "maximum": 4
            }
          },
          {
            "name": "qualifications",
            "in": "query",
            "required": false,
            "description": "Specialized only: Japanese national qualifications / ISA-listed IT exams or qualifications related to the work. 1 → 5, 2+ → 10.",
            "schema": {
              "type": "integer",
              "description": "Specialized only: Japanese national qualifications / ISA-listed IT exams or qualifications related to the work. 1 → 5, 2+ → 10.",
              "default": 0
            }
          },
          {
            "name": "position",
            "in": "query",
            "required": false,
            "description": "Management only: representative (代表取締役 etc., 10) or officer (取締役 / 執行役, 5).",
            "schema": {
              "type": "string",
              "description": "Management only: representative (代表取締役 etc., 10) or officer (取締役 / 執行役, 5).",
              "enum": [
                "representative",
                "officer",
                "none"
              ],
              "default": "none"
            }
          },
          {
            "name": "innovationSupport",
            "in": "query",
            "required": false,
            "description": "Employer receives a listed innovation-support measure (10; 20 with sme=true).",
            "schema": {
              "type": "boolean",
              "description": "Employer receives a listed innovation-support measure (10; 20 with sme=true).",
              "default": false
            }
          },
          {
            "name": "sme",
            "in": "query",
            "required": false,
            "description": "Employer is a small or medium enterprise (only adds with innovationSupport).",
            "schema": {
              "type": "boolean",
              "description": "Employer is a small or medium enterprise (only adds with innovationSupport).",
              "default": false
            }
          },
          {
            "name": "smeResearch3pct",
            "in": "query",
            "required": false,
            "description": "SME employer whose R&D costs exceed 3% of revenue (5).",
            "schema": {
              "type": "boolean",
              "description": "SME employer whose R&D costs exceed 3% of revenue (5).",
              "default": false
            }
          },
          {
            "name": "foreignQualification",
            "in": "query",
            "required": false,
            "description": "Work-related foreign qualification, certification or award (5).",
            "schema": {
              "type": "boolean",
              "description": "Work-related foreign qualification, certification or award (5).",
              "default": false
            }
          },
          {
            "name": "japaneseDegree",
            "in": "query",
            "required": false,
            "description": "Graduated from a Japanese university or graduate course (10).",
            "schema": {
              "type": "boolean",
              "description": "Graduated from a Japanese university or graduate course (10).",
              "default": false
            }
          },
          {
            "name": "japanese",
            "in": "query",
            "required": false,
            "description": "n1 (JLPT N1, BJT 480+ or Japanese major abroad, 15) or n2 (JLPT N2 / BJT 400+, 10, not on top of japaneseDegree).",
            "schema": {
              "type": "string",
              "description": "n1 (JLPT N1, BJT 480+ or Japanese major abroad, 15) or n2 (JLPT N2 / BJT 400+, 10, not on top of japaneseDegree).",
              "enum": [
                "n1",
                "n2",
                "none"
              ],
              "default": "none"
            }
          },
          {
            "name": "growthProject",
            "in": "query",
            "required": false,
            "description": "Working on a ministry-certified advanced project in a growth field (10).",
            "schema": {
              "type": "boolean",
              "description": "Working on a ministry-certified advanced project in a growth field (10).",
              "default": false
            }
          },
          {
            "name": "topUniversity",
            "in": "query",
            "required": false,
            "description": "Degree from a designated university (top-300 rankings, Top Global University, Innovative Asia partner) (10).",
            "schema": {
              "type": "boolean",
              "description": "Degree from a designated university (top-300 rankings, Top Global University, Innovative Asia partner) (10).",
              "default": false
            }
          },
          {
            "name": "jicaTraining",
            "in": "query",
            "required": false,
            "description": "Completed JICA Innovative Asia training (5).",
            "schema": {
              "type": "boolean",
              "description": "Completed JICA Innovative Asia training (5).",
              "default": false
            }
          },
          {
            "name": "personalInvestment100m",
            "in": "query",
            "required": false,
            "description": "Management only: you invest ¥100M+ in the business (5).",
            "schema": {
              "type": "boolean",
              "description": "Management only: you invest ¥100M+ in the business (5).",
              "default": false
            }
          },
          {
            "name": "investmentManagement",
            "in": "query",
            "required": false,
            "description": "Specialized / management: investment-management work (10).",
            "schema": {
              "type": "boolean",
              "description": "Specialized / management: investment-management work (10).",
              "default": false
            }
          },
          {
            "name": "localGovSupport",
            "in": "query",
            "required": false,
            "description": "Employer receives local-government support for hiring highly skilled foreigners (10).",
            "schema": {
              "type": "boolean",
              "description": "Employer receives local-government support for hiring highly skilled foreigners (10).",
              "default": false
            }
          }
        ],
        "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": "japanHspPointsCheckPost",
        "summary": "Japan Highly Skilled Professional (高度専門職) points: does this profile reach 70 or 80 points, and what does it mean for PR? (JSON body)",
        "description": "Applies the HSP points ordinance (平成26年法務省令第37号, art. 1 and 2) to a profile for one of the three categories: academic (HSP i-a, 高度専門職1号イ), specialized (i-b, 1号ロ) or management (i-c, 1号ハ). Scores education, experience, salary (age-banded minimums for i-a / i-b: under 30 from ¥4M, 30–34 ¥5M, 35–39 ¥6M, 40+ ¥8M; i-c from ¥10M), age, research, Japanese qualifications, position and the bonus items (innovation-support employer 10/20, SME R&D 5, foreign qualification 5, Japanese degree 10, JLPT N1 15 / N2 10, growth project 10, top university 10, JICA 5, ¥100M investment 5, investment management 10, local-government support 10). Checks the ¥3M salary floor (i-b, i-c), the J-Skip (特別高度人材) criteria, the permanent-residence fast track (70 → 3 years, 80 → 1 year) and HSP (ii). Returns verdict (qualifies_80 | qualifies_70 | below_70 | below_salary_floor), total, breakdown [{item, points, basis}], pointsTo70, pointsTo80, pr, jSkip, couldAdd, warnings, pendingRevision, sources and a disclaimer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "education",
                  "annualSalary"
                ],
                "properties": {
                  "category": {
                    "type": "string",
                    "description": "academic (research / teaching, HSP i-a), specialized (engineer, specialist, most employees, HSP i-b), management (executive / business owner, HSP i-c). Aliases: a/b/c, イ/ロ/ハ, researcher, engineer, ceo…",
                    "enum": [
                      "academic",
                      "specialized",
                      "management"
                    ]
                  },
                  "education": {
                    "type": "string",
                    "description": "Highest degree: doctor, mba (MBA / MOT professional degree), master (incl. other professional degrees), bachelor, none.",
                    "enum": [
                      "doctor",
                      "mba",
                      "master",
                      "bachelor",
                      "none"
                    ]
                  },
                  "age": {
                    "type": "integer",
                    "description": "Age on the application date. Required for academic and specialized unless birthDate is given."
                  },
                  "birthDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD; used with applicationDate (default today in Japan) when age is not given."
                  },
                  "annualSalary": {
                    "type": "number",
                    "description": "Expected annual pay in Japan in yen, including bonuses (e.g. 7500000). Or annualSalaryMan in 万円 (750)."
                  },
                  "experienceYears": {
                    "type": "number",
                    "description": "Years of experience: in research/teaching (academic), in the work you will do (specialized), in business management (management).",
                    "default": 0
                  },
                  "multipleDegrees": {
                    "type": "boolean",
                    "description": "Doctor / master / professional degrees in two or more fields (+5).",
                    "default": false
                  },
                  "researchItems": {
                    "type": "integer",
                    "description": "Kinds of research achievement (patent; 3+ foreign-government grants; 3+ papers as corresponding author; other). Academic: 1 → 20, 2+ → 25. Specialized: 1+ → 15.",
                    "default": 0,
                    "minimum": 0,
                    "maximum": 4
                  },
                  "qualifications": {
                    "type": "integer",
                    "description": "Specialized only: Japanese national qualifications / ISA-listed IT exams or qualifications related to the work. 1 → 5, 2+ → 10.",
                    "default": 0
                  },
                  "position": {
                    "type": "string",
                    "description": "Management only: representative (代表取締役 etc., 10) or officer (取締役 / 執行役, 5).",
                    "enum": [
                      "representative",
                      "officer",
                      "none"
                    ],
                    "default": "none"
                  },
                  "innovationSupport": {
                    "type": "boolean",
                    "description": "Employer receives a listed innovation-support measure (10; 20 with sme=true).",
                    "default": false
                  },
                  "sme": {
                    "type": "boolean",
                    "description": "Employer is a small or medium enterprise (only adds with innovationSupport).",
                    "default": false
                  },
                  "smeResearch3pct": {
                    "type": "boolean",
                    "description": "SME employer whose R&D costs exceed 3% of revenue (5).",
                    "default": false
                  },
                  "foreignQualification": {
                    "type": "boolean",
                    "description": "Work-related foreign qualification, certification or award (5).",
                    "default": false
                  },
                  "japaneseDegree": {
                    "type": "boolean",
                    "description": "Graduated from a Japanese university or graduate course (10).",
                    "default": false
                  },
                  "japanese": {
                    "type": "string",
                    "description": "n1 (JLPT N1, BJT 480+ or Japanese major abroad, 15) or n2 (JLPT N2 / BJT 400+, 10, not on top of japaneseDegree).",
                    "enum": [
                      "n1",
                      "n2",
                      "none"
                    ],
                    "default": "none"
                  },
                  "growthProject": {
                    "type": "boolean",
                    "description": "Working on a ministry-certified advanced project in a growth field (10).",
                    "default": false
                  },
                  "topUniversity": {
                    "type": "boolean",
                    "description": "Degree from a designated university (top-300 rankings, Top Global University, Innovative Asia partner) (10).",
                    "default": false
                  },
                  "jicaTraining": {
                    "type": "boolean",
                    "description": "Completed JICA Innovative Asia training (5).",
                    "default": false
                  },
                  "personalInvestment100m": {
                    "type": "boolean",
                    "description": "Management only: you invest ¥100M+ in the business (5).",
                    "default": false
                  },
                  "investmentManagement": {
                    "type": "boolean",
                    "description": "Specialized / management: investment-management work (10).",
                    "default": false
                  },
                  "localGovSupport": {
                    "type": "boolean",
                    "description": "Employer receives local-government support for hiring highly skilled foreigners (10).",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "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": "japanHspPointsRules",
        "summary": "Japan HSP points rules: points table per category (academic / specialized / management), age-banded salary minimums, bonuses, ¥3M floor, PR fast track, HSP (ii), J-Skip, pending revision, sources",
        "description": "Returns the rules the checker applies, with the ordinance tables, official sources and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}