{ "openapi": "3.1.1", "info": { "title": "Salary Reality Check API", "version": "1.0.0", "summary": "Compare job offers by real net pay per hour, including commute time and living costs.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://salaryrealitycheck.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Compare job offers by real net pay per hour, including commute time and living costs.", "description": "Enter 2–4 job offers with salary, your own effective tax rate, bonus, benefits, commute and cost-of-living differences. The tool ranks them by net income per hour of working plus commuting time, so a higher salary with a long commute or an expensive city is put into perspective.\n\nMethodology:\n- Gross total = gross salary + annual bonus. Net annual = gross total × (1 − effective tax+social rate) + benefits value (benefits are treated as already net).\n- The effective tax+social rate is supplied by you; no national tax rules are applied.\n- Commute days per year = working days × (1 − remote days per week ÷ 5). Commute hours = commute days × 2 × one-way minutes ÷ 60.\n- Work hours per year = weekly hours ÷ 5 × working days (a 5-day week is assumed).\n- Net after costs = net annual − 12 × monthly commute cost − 12 × monthly living cost difference.\n- Net per hour incl. commute = net after costs ÷ (work hours + commute hours). Offers are ranked by this value; ties keep input order.\n- Value of commute time = commute hours × (net annual ÷ work hours).", "tags": [ "money" ], "x-mcp-tool": "salary_reality_check", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryRealityCheckInput" }, "examples": { "example1": { "summary": "City job vs. remote-friendly job", "value": { "currency": "EUR", "offers": [ { "name": "Big-city bank", "grossAnnual": 72000, "taxRatePercent": 42, "bonus": 6000, "benefitsValue": 1200, "commuteMinutesOneWay": 55, "commuteCostMonthly": 90, "workingDays": 220, "weeklyHours": 42, "livingCostDiffMonthly": 450, "remoteDaysPerWeek": 1 }, { "name": "Local software firm", "grossAnnual": 62000, "taxRatePercent": 39, "bonus": 0, "benefitsValue": 800, "commuteMinutesOneWay": 20, "commuteCostMonthly": 40, "workingDays": 220, "weeklyHours": 40, "livingCostDiffMonthly": 0, "remoteDaysPerWeek": 3 } ] } }, "example2": { "summary": "Three offers with different hours", "value": { "currency": "USD", "offers": [ { "name": "Startup", "grossAnnual": 95000, "taxRatePercent": 30, "benefitsValue": 3000, "commuteMinutesOneWay": 30, "commuteCostMonthly": 120, "weeklyHours": 50 }, { "name": "Corporate", "grossAnnual": 105000, "taxRatePercent": 32, "bonus": 10000, "benefitsValue": 8000, "commuteMinutesOneWay": 60, "commuteCostMonthly": 250, "weeklyHours": 45 }, { "name": "Fully remote", "grossAnnual": 88000, "taxRatePercent": 29, "benefitsValue": 2000, "remoteDaysPerWeek": 5, "weeklyHours": 40 } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryRealityCheckResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "SalaryRealityCheckInput": { "type": "object", "additionalProperties": false, "properties": { "currency": { "title": "Currency", "description": "Shown in results only; no conversion is performed.", "type": "string", "maxLength": 8, "default": "EUR" }, "offers": { "title": "Job offers", "description": "Tax rate is YOUR effective tax + social contribution rate in % of gross (look it up in a local net-pay calculator); this tool does not implement any national tax law. Living cost difference is extra rent/living cost per month for this job compared to your baseline (negative if cheaper).", "type": "array", "minItems": 2, "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Offer", "type": "string" }, "grossAnnual": { "title": "Gross salary / year", "type": "number", "minimum": 0 }, "taxRatePercent": { "title": "Effective tax + social %", "type": "number", "minimum": 0, "maximum": 95, "x-unit": "%" }, "bonus": { "title": "Bonus / year", "type": "number", "minimum": 0, "default": 0 }, "benefitsValue": { "title": "Benefits value / year", "type": "number", "minimum": 0, "default": 0 }, "commuteMinutesOneWay": { "title": "Commute one way", "type": "number", "minimum": 0, "maximum": 600, "default": 0, "x-unit": "min" }, "commuteCostMonthly": { "title": "Commute cost / month", "type": "number", "minimum": 0, "default": 0 }, "workingDays": { "title": "Working days / year", "type": "integer", "minimum": 1, "maximum": 366, "default": 220, "x-unit": "days" }, "weeklyHours": { "title": "Hours / week", "type": "number", "minimum": 1, "maximum": 100, "default": 40, "x-unit": "h" }, "livingCostDiffMonthly": { "title": "Living cost difference / month", "type": "number", "default": 0 }, "remoteDaysPerWeek": { "title": "Remote days / week", "type": "number", "minimum": 0, "maximum": 5, "default": 0, "x-unit": "days" } }, "required": [ "name", "grossAnnual", "taxRatePercent" ] } } }, "required": [ "offers" ] }, "SalaryRealityCheckResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "currency", "best", "ranking" ], "properties": { "currency": { "type": "string" }, "best": { "type": "string", "description": "Offer with the highest net income per hour of working plus commuting, after commute and living costs." }, "ranking": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "rank", "name", "grossTotal", "netAnnual", "commuteDaysPerYear", "commuteHoursPerYear", "commuteCostPerYear", "livingCostDiffPerYear", "netAfterCosts", "workHoursPerYear", "netPerWorkHour", "netPerHourInclCommute", "commuteTimeValue", "differenceToBestPerYear" ], "properties": { "rank": { "type": "integer" }, "name": { "type": "string" }, "grossTotal": { "type": "number", "description": "Gross salary + bonus." }, "netAnnual": { "type": "number", "description": "(Gross + bonus) × (1 − tax rate) + benefits." }, "commuteDaysPerYear": { "type": "number" }, "commuteHoursPerYear": { "type": "number" }, "commuteCostPerYear": { "type": "number" }, "livingCostDiffPerYear": { "type": "number" }, "netAfterCosts": { "type": "number", "description": "Net annual − commute cost − living cost difference." }, "workHoursPerYear": { "type": "number" }, "netPerWorkHour": { "type": "number", "description": "Net annual ÷ work hours (ignores commute)." }, "netPerHourInclCommute": { "type": "number", "description": "Net after costs ÷ (work hours + commute hours)." }, "commuteTimeValue": { "type": "number", "description": "Commute hours valued at the net hourly wage of this offer." }, "differenceToBestPerYear": { "type": "number", "description": "Net after costs of the best offer minus this offer." } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }