{"openapi":"3.1.0","info":{"title":"Stupidly Clever API","description":"REST API for calculators, validators, and financial tools. Every endpoint has a matching MCP tool at https://api.stupidlyclever.com/mcp.","version":"1.0.0","contact":{"name":"Stupidly Clever","url":"https://www.stupidlyclever.com","email":"support@stupidlyclever.com"},"license":{"name":"Commercial","url":"https://www.stupidlyclever.com/terms"}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key from https://www.stupidlyclever.com/dashboard. Include as: Authorization: Bearer YOUR_KEY"}},"schemas":{"def-0":{"type":"object","description":"The request was invalid — a required parameter was missing or malformed.","properties":{"error":{"type":"string","description":"Human-readable description of what was wrong with the request."}},"required":["error"],"title":"ErrorResponse400"},"def-1":{"type":"object","description":"No valid API key was provided.","properties":{"error":{"type":"string","description":"Human-readable description of the authentication failure."}},"required":["error"],"title":"ErrorResponse401"}}},"paths":{"/status":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/date-diff":{"get":{"summary":"Calculate the difference between two dates in days, weeks, months, years, hours, minutes and seconds.","tags":["Dates & Time"],"description":"Calculate the difference between two dates in days, weeks, months, years, hours, minutes and seconds. Use this when a user asks how long until a deadline, how long since an event, or wants a precise date-span breakdown. Example: \"How many days are there between 1 March 2026 and 30 June 2026?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"startDate","required":true,"description":"The earlier date in YYYY-MM-DD format. Example: \"2026-03-01\""},{"schema":{"type":"string"},"in":"query","name":"endDate","required":true,"description":"The later date in YYYY-MM-DD format. Example: \"2026-06-30\""}],"responses":{"200":{"description":"The difference between two dates, expressed in several units.","content":{"application/json":{"schema":{"type":"object","description":"The difference between two dates, expressed in several units.","properties":{"result":{"type":"object","description":"The date-span breakdown.","properties":{"days":{"type":"number","description":"Whole days between the two dates. Example: 121"},"weeks":{"type":"number","description":"Whole weeks between the two dates. Example: 17"},"months":{"type":"number","description":"Calendar months between the two dates. Example: 3"},"years":{"type":"number","description":"Calendar years between the two dates. Example: 0"},"hours":{"type":"number","description":"Whole hours between the two dates. Example: 2904"},"minutes":{"type":"number","description":"Whole minutes between the two dates. Example: 174240"},"seconds":{"type":"number","description":"Whole seconds between the two dates. Example: 10454400"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"MarchToJune":{"summary":"Difference between 1 March 2026 and 30 June 2026","value":{"result":{"days":121,"weeks":17,"months":3,"years":0,"hours":2904,"minutes":174240,"seconds":10454400},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/public-holidays":{"get":{"summary":"List public holidays for a country in a given year.","tags":["Dates & Time"],"description":"List public holidays for a country in a given year. Use this when a user asks what holidays fall in a country during a given year, e.g. for trip planning or business scheduling. Returns a list of holiday names and dates. Example: \"What are the public holidays in Japan in 2027?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"countryCode","required":true,"description":"ISO 3166-1 alpha-2 country code. Example: \"JP\""},{"schema":{"type":"string"},"in":"query","name":"year","required":true,"description":"Four-digit year. Example: 2027"}],"responses":{"200":{"description":"The public holidays for a country in a given year, with English and local-language names.","content":{"application/json":{"schema":{"type":"object","description":"The public holidays for a country in a given year, with English and local-language names.","properties":{"result":{"type":"object","description":"The holiday list.","properties":{"holidays":{"type":"array","description":"Public holidays for the requested country and year, in date order.","items":{"type":"object","properties":{"date":{"type":"string","description":"Holiday date, YYYY-MM-DD. Example: \"2027-01-01\""},"name":{"type":"string","description":"English holiday name. Example: \"New Year's Day\""},"localName":{"type":"string","description":"Holiday name in the local language. Example: \"元日\""}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed, including whether it was served from cache.","properties":{"cached":{"type":"boolean","description":"Whether this result was served from cache rather than fetched live. Example: false"},"source":{"type":"string","description":"Where the data came from: \"redis\", \"redis-stale\" (fallback if the live fetch failed), or \"nager.date\" (live). Example: \"nager.date\""},"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"JapanPublicHolidays2027":{"summary":"Public holidays in Japan for 2027","value":{"result":{"holidays":[{"date":"2027-01-01","name":"New Year's Day","localName":"元日"},{"date":"2027-01-11","name":"Coming of Age Day","localName":"成人の日"},{"date":"2027-02-11","name":"Foundation Day","localName":"建国記念の日"},{"date":"2027-02-23","name":"The Emperor's Birthday","localName":"天皇誕生日"},{"date":"2027-03-21","name":"Vernal Equinox Day","localName":"春分の日"},{"date":"2027-04-29","name":"Shōwa Day","localName":"昭和の日"},{"date":"2027-05-03","name":"Constitution Memorial Day","localName":"憲法記念日"},{"date":"2027-05-04","name":"Greenery Day","localName":"みどりの日"},{"date":"2027-05-05","name":"Children's Day","localName":"こどもの日"},{"date":"2027-07-19","name":"Marine Day","localName":"海の日"},{"date":"2027-08-11","name":"Mountain Day","localName":"山の日"},{"date":"2027-09-20","name":"Respect for the Aged Day","localName":"敬老の日"},{"date":"2027-09-23","name":"Autumnal Equinox Day","localName":"秋分の日"},{"date":"2027-10-11","name":"Sports Day","localName":"スポーツの日"},{"date":"2027-11-03","name":"Culture Day","localName":"文化の日"},{"date":"2027-11-23","name":"Labour Thanksgiving Day","localName":"勤労感謝の日"}]},"meta":{"cached":false,"source":"nager.date","computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/business-days":{"get":{"summary":"Count business days between two dates, excluding weekends and public holidays for a given country.","tags":["Dates & Time"],"description":"Count business days between two dates, excluding weekends and public holidays for a given country. Use this when a user asks how many working days remain in a deadline, billing period, or project timeline. Returns the number of business days. Example: \"How many business days are there between 1 March and 30 June 2026 in the UK?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"startDate","required":true,"description":"Start date in YYYY-MM-DD format. Example: \"2026-03-01\""},{"schema":{"type":"string"},"in":"query","name":"endDate","required":true,"description":"End date in YYYY-MM-DD format. Example: \"2026-06-30\""},{"schema":{"type":"string"},"in":"query","name":"countryCode","required":true,"description":"ISO 3166-1 alpha-2 country code for the public holiday calendar. Example: \"GB\""}],"responses":{"200":{"description":"The number of business days between two dates, with weekend and public-holiday counts broken out and the matched holidays listed.","content":{"application/json":{"schema":{"type":"object","description":"The number of business days between two dates, with weekend and public-holiday counts broken out and the matched holidays listed.","properties":{"result":{"type":"object","description":"The business-day count and its breakdown.","properties":{"businessDays":{"type":"number","description":"Total days minus weekend days minus public holidays that fall on a weekday. Example: 81"},"totalDays":{"type":"number","description":"Total calendar days from startDate to endDate, inclusive. Example: 122"},"weekendDays":{"type":"number","description":"Number of Saturdays and Sundays in the range. Example: 35"},"publicHolidays":{"type":"number","description":"Number of public holidays that fall on a weekday in the range. Example: 6"},"holidayList":{"type":"array","description":"The public holidays (weekday-falling only) excluded from the business-day count.","items":{"type":"object","properties":{"date":{"type":"string","description":"Holiday date, YYYY-MM-DD. Example: \"2026-03-17\""},"name":{"type":"string","description":"English holiday name. Example: \"Saint Patrick's Day\""},"localName":{"type":"string","description":"Holiday name in the local language. Example: \"Saint Patrick's Day\""}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"GbBusinessDays":{"summary":"Business days between 1 March and 30 June 2026 in the UK","value":{"result":{"businessDays":81,"totalDays":122,"weekendDays":35,"publicHolidays":6,"holidayList":[{"date":"2026-03-17","name":"Saint Patrick's Day","localName":"Saint Patrick's Day"},{"date":"2026-04-03","name":"Good Friday","localName":"Good Friday"},{"date":"2026-04-06","name":"Easter Monday","localName":"Easter Monday"},{"date":"2026-05-04","name":"Early May Bank Holiday","localName":"Early May Bank Holiday"},{"date":"2026-05-25","name":"Spring Bank Holiday","localName":"Spring Bank Holiday"},{"date":"2026-06-15","name":"World Cup Bank Holiday","localName":"World Cup Bank Holiday"}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/compound-interest":{"get":{"summary":"Calculate compound interest growth over time, with an optional regular contribution added at each compounding period.","tags":["Finance"],"description":"Calculate compound interest growth over time, with an optional regular contribution added at each compounding period. Use this when a user wants to project savings or investment growth, including the effect of regular deposits. Returns the final amount, total interest earned, total contributions, effective annual rate, and a year-by-year balance schedule. Example: \"How much will $10,000 grow to in 20 years at 7% annual interest, compounded monthly, with $200 added each month?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"principal","required":true,"description":"Starting amount. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"annualRate","required":true,"description":"Nominal annual interest rate as a percentage, e.g. 5 for 5%. Example: 7"},{"schema":{"type":"string"},"in":"query","name":"years","required":true,"description":"Number of years to compound over. Example: 20"},{"schema":{"type":"string","enum":["daily","weekly","monthly","quarterly","annually"]},"in":"query","name":"compoundingFrequency","required":true,"description":"How often interest compounds. Example: \"monthly\""},{"schema":{"type":"string"},"in":"query","name":"contributionAmount","required":false,"description":"Amount contributed at each compounding period (same frequency as compoundingFrequency), added before that period's interest. Defaults to 0. Example: 200"}],"responses":{"200":{"description":"The final compounded amount, interest earned, contributions, and effective annual rate, with a year-by-year balance schedule.","content":{"application/json":{"schema":{"type":"object","description":"The final compounded amount, interest earned, contributions, and effective annual rate, with a year-by-year balance schedule.","properties":{"result":{"type":"object","description":"Compound interest results.","properties":{"finalAmount":{"type":"number","description":"Balance at the end of the period. Example: 145180.47"},"totalInterest":{"type":"number","description":"Total interest earned over the period. Example: 87180.47"},"totalContributions":{"type":"number","description":"Sum of all contributions made over the period. Example: 48000"},"effectiveAnnualRate":{"type":"number","description":"Effective annual rate accounting for compounding frequency, as a percentage. Example: 7.23"},"schedule":{"type":"array","description":"Year-by-year balance, interest earned, and contributions to date.","items":{"type":"object","properties":{"year":{"type":"number","description":"Year number. Example: 1"},"balance":{"type":"number","description":"Balance at year end. Example: 13215.88"},"interestEarned":{"type":"number","description":"Interest earned during this year. Example: 815.88"},"contributionsToDate":{"type":"number","description":"Cumulative contributions through this year. Example: 2400"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"TwentyYearMonthly":{"summary":"$10,000 at 7% for 20 years, compounded monthly, with $200/month contributions (schedule trimmed to first 3 and last 2 of 20 years)","value":{"result":{"finalAmount":145180.47,"totalInterest":87180.47,"totalContributions":48000,"effectiveAnnualRate":7.23,"schedule":[{"year":1,"balance":13215.88,"interestEarned":815.88,"contributionsToDate":2400},{"year":2,"balance":16664.23,"interestEarned":1048.35,"contributionsToDate":4800},{"year":3,"balance":20361.86,"interestEarned":1297.63,"contributionsToDate":7200},{"year":19,"balance":133068,"interestEarned":8895.89,"contributionsToDate":45600},{"year":20,"balance":145180.47,"interestEarned":9712.47,"contributionsToDate":48000}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/mortgage":{"get":{"summary":"Calculate a fixed-rate mortgage.","tags":["Finance"],"description":"Calculate a fixed-rate mortgage. Use this when a user wants to know their monthly payment, total interest, or full amortization schedule for a home loan. Returns monthly payment, total payment, total interest, loan amount, and a year-by-year amortization schedule. Example: \"What is the monthly payment on a $400,000 home with an $80,000 down payment at 6.5% over 30 years?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"homePrice","required":true,"description":"Total price of the home. Example: 400000"},{"schema":{"type":"string"},"in":"query","name":"downPayment","required":true,"description":"Down payment amount. Example: 80000"},{"schema":{"type":"string"},"in":"query","name":"annualRate","required":true,"description":"Annual interest rate as a percentage, e.g. 6 for 6%. Example: 6.5"},{"schema":{"type":"string"},"in":"query","name":"termYears","required":true,"description":"Loan term in years, e.g. 30. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"currency","required":false,"description":"ISO currency code, defaults to 'USD'. Example: \"USD\""}],"responses":{"200":{"description":"Monthly payment, total interest, and loan amount for a fixed-rate mortgage, with a year-by-year amortization schedule.","content":{"application/json":{"schema":{"type":"object","description":"Monthly payment, total interest, and loan amount for a fixed-rate mortgage, with a year-by-year amortization schedule.","properties":{"result":{"type":"object","description":"Mortgage calculation results.","properties":{"monthlyPayment":{"type":"number","description":"Fixed monthly payment. Example: 2022.62"},"totalPayment":{"type":"number","description":"Total of all payments over the loan term. Example: 728142.36"},"totalInterest":{"type":"number","description":"Total interest paid over the loan term. Example: 408142.36"},"loanAmount":{"type":"number","description":"Loan principal (home price minus down payment). Example: 320000"},"currency":{"type":"string","description":"ISO currency code used. Example: \"USD\""},"schedule":{"type":"array","description":"Year-by-year principal, interest, and remaining balance.","items":{"type":"object","properties":{"year":{"type":"number","description":"Year number. Example: 1"},"principal":{"type":"number","description":"Principal paid during this year. Example: 3576.72"},"interest":{"type":"number","description":"Interest paid during this year. Example: 20694.69"},"balance":{"type":"number","description":"Remaining loan balance at year end. Example: 316423.28"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FourHundredKHome":{"summary":"$400,000 home, $80,000 down payment, 6.5% over 30 years (schedule trimmed to first 3 and last 2 of 30 years)","value":{"result":{"monthlyPayment":2022.62,"totalPayment":728142.36,"totalInterest":408142.36,"loanAmount":320000,"currency":"USD","schedule":[{"year":1,"principal":3576.72,"interest":20694.69,"balance":316423.28},{"year":2,"principal":3816.26,"interest":20455.15,"balance":312607.02},{"year":3,"principal":4071.84,"interest":20199.57,"balance":308535.17},{"year":29,"principal":21966.86,"interest":2304.55,"balance":23438.03},{"year":30,"principal":23438.03,"interest":833.39,"balance":0}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/salary":{"get":{"summary":"Convert a salary at any pay period into its hourly, daily, weekly, biweekly, monthly and annual equivalents.","tags":["Income & Wealth"],"description":"Convert a salary at any pay period into its hourly, daily, weekly, biweekly, monthly and annual equivalents. Use this when a user has a pay figure in one period and wants to see it in others — comparing a job offer's hourly rate to an annual salary, for example. Example: \"What is $85,000 a year as an hourly rate?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"salary","required":true,"description":"The pay amount. Example: 85000"},{"schema":{"type":"string","enum":["hourly","daily","weekly","monthly","annual"]},"in":"query","name":"period","required":true,"description":"The period the salary figure is quoted in. Example: \"annual\""},{"schema":{"type":"string"},"in":"query","name":"hoursPerWeek","required":false,"description":"Hours worked per week, defaults to 40. Example: 40"}],"responses":{"200":{"description":"The pay amount converted into its hourly, daily, weekly, biweekly, monthly and annual equivalents.","content":{"application/json":{"schema":{"type":"object","description":"The pay amount converted into its hourly, daily, weekly, biweekly, monthly and annual equivalents.","properties":{"result":{"type":"object","description":"The salary breakdown by pay period. The period originally supplied is listed first; all six are always present.","properties":{"hourly":{"type":"number","description":"Equivalent hourly rate. Example: 40.87"},"daily":{"type":"number","description":"Equivalent daily rate. Example: 326.92"},"weekly":{"type":"number","description":"Equivalent weekly rate. Example: 1634.62"},"biweekly":{"type":"number","description":"Equivalent biweekly rate. Example: 3269.23"},"monthly":{"type":"number","description":"Equivalent monthly rate. Example: 7083.33"},"annual":{"type":"number","description":"Equivalent annual rate. Example: 85000"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"AnnualEightyFiveThousand":{"summary":"Convert an $85,000 annual salary into other pay periods","value":{"result":{"annual":85000,"hourly":40.87,"daily":326.92,"weekly":1634.62,"biweekly":3269.23,"monthly":7083.33},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/vat":{"get":{"summary":"Add VAT/sales tax onto a net amount, or extract it out of a gross amount.","tags":["Finance"],"description":"Add VAT/sales tax onto a net amount, or extract it out of a gross amount. Use this when a user needs to compute a price including or excluding tax. Example: \"What is $100 plus 20% VAT?\" or \"How much VAT is included in a $120 gross price at 20%?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"amount","required":true,"description":"The amount to calculate from — a net amount when direction is 'add', a gross amount when direction is 'extract'. Example: 100"},{"schema":{"type":"string"},"in":"query","name":"rate","required":true,"description":"Tax rate as a percentage, e.g. 20 for 20%. Example: 20"},{"schema":{"type":"string","enum":["add","extract"]},"in":"query","name":"direction","required":true,"description":"'add' to add tax onto a net amount, 'extract' to pull tax out of a gross amount. Example: \"add\""}],"responses":{"200":{"description":"The net, tax, and gross breakdown for the requested amount and direction.","content":{"application/json":{"schema":{"type":"object","description":"The net, tax, and gross breakdown for the requested amount and direction.","properties":{"result":{"type":"object","description":"VAT/sales tax breakdown. Field order depends on direction — when adding tax, gross appears first as the headline answer; when extracting, net appears first.","properties":{"net":{"type":"number","description":"Amount excluding tax. Example: 100"},"tax":{"type":"number","description":"Tax amount. Example: 20"},"gross":{"type":"number","description":"Amount including tax. Example: 120"},"rate":{"type":"number","description":"Tax rate used, as a percentage, echoed from the input. Example: 20"},"direction":{"type":"string","enum":["add","extract"],"description":"Direction used, echoed from the input. Example: \"add\""}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"AddTwentyPercent":{"summary":"Add 20% VAT onto a $100 net amount","value":{"result":{"gross":120,"tax":20,"net":100,"rate":20,"direction":"add"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/invoice":{"post":{"summary":"Calculate an itemized invoice from line items.","tags":["Finance"],"description":"Calculate an itemized invoice from line items. Use this when a user wants to generate invoice totals — per-line net/tax/gross amounts plus the subtotal, total tax, and grand total — from a list of items, quantities, and tax rates. Example: \"Invoice 5 hours of consulting at $150/hour and 2 licenses at $50 each, both taxed at 20%.\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lineItems":{"type":"array","description":"The invoice line items. Example: [{\"description\": \"Consulting\", \"quantity\": 5, \"unitPrice\": 150, \"taxRate\": 20}]","items":{"type":"object","properties":{"description":{"type":"string","description":"What the line item is. Example: \"Consulting\""},"quantity":{"type":"number","description":"Quantity. Example: 5"},"unitPrice":{"type":"number","description":"Price per unit, before tax. Example: 150"},"taxRate":{"type":"number","description":"Tax rate for this line as a percentage, e.g. 20 for 20%. Example: 20"}},"required":["description","quantity","unitPrice","taxRate"]}},"currency":{"type":"string","description":"ISO currency code, defaults to 'USD'. Example: \"USD\""}},"required":["lineItems"]}}}},"responses":{"200":{"description":"The invoice totals, with a per-line breakdown of net, tax, and gross amounts.","content":{"application/json":{"schema":{"type":"object","description":"The invoice totals, with a per-line breakdown of net, tax, and gross amounts.","properties":{"result":{"type":"object","description":"Invoice calculation results.","properties":{"grandTotal":{"type":"number","description":"Sum of all line gross amounts. Example: 1020"},"subtotal":{"type":"number","description":"Sum of all line net amounts, before tax. Example: 850"},"totalTax":{"type":"number","description":"Sum of all line tax amounts. Example: 170"},"currency":{"type":"string","description":"ISO currency code used. Example: \"USD\""},"lines":{"type":"array","description":"Computed breakdown for each line item.","items":{"type":"object","properties":{"description":{"type":"string","description":"What the line item is. Example: \"Consulting\""},"quantity":{"type":"number","description":"Quantity. Example: 5"},"unitPrice":{"type":"number","description":"Price per unit, before tax. Example: 150"},"taxRate":{"type":"number","description":"Tax rate for this line, as a percentage. Example: 20"},"lineNet":{"type":"number","description":"Net amount for this line (quantity × unitPrice). Example: 750"},"lineTax":{"type":"number","description":"Tax amount for this line. Example: 150"},"lineGross":{"type":"number","description":"Gross amount for this line (net + tax). Example: 900"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"ConsultingAndLicenses":{"summary":"5 hours of consulting at $150/hour and 2 licenses at $50 each, both taxed at 20%","value":{"result":{"grandTotal":1020,"subtotal":850,"totalTax":170,"currency":"USD","lines":[{"description":"Consulting","quantity":5,"unitPrice":150,"taxRate":20,"lineNet":750,"lineTax":150,"lineGross":900},{"description":"Software License","quantity":2,"unitPrice":50,"taxRate":20,"lineNet":100,"lineTax":20,"lineGross":120}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/late-payment-interest":{"get":{"summary":"Calculate EU or UK statutory late-payment interest and fixed recovery compensation.","tags":["Finance"],"description":"Calculates statutory interest on overdue commercial invoices under EU Directive 2011/7/EU or the UK Late Payment of Commercial Debts Act 1998. Handles rate changes mid-period by segmenting the overdue period. Returns interest, fixed recovery compensation, and a full calculation audit trail. Use when a creditor wants to charge statutory interest on a late invoice. Example: \"An invoice for €5,000 was due 2026-07-15 but paid 2026-08-10 in Czechia — what interest and compensation can I claim?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"creditorJurisdiction","required":true,"description":"ISO 3166-1 alpha-2 country code of the creditor (determines which statutory rate applies). Example: \"CZ\", \"GB\", \"DE\""},{"schema":{"type":"string","enum":["business","public_authority"]},"in":"query","name":"debtorType","required":true,"description":"Whether the debtor is a private business or a public authority."},{"schema":{"type":"string"},"in":"query","name":"invoiceAmount","required":true,"description":"Net invoice amount (before tax) on which interest is calculated. Example: \"5000\""},{"schema":{"type":"string"},"in":"query","name":"currency","required":true,"description":"ISO 4217 currency code of the invoice. Example: \"EUR\", \"GBP\", \"CZK\""},{"schema":{"type":"string"},"in":"query","name":"invoiceDate","required":true,"description":"Date the invoice was issued, YYYY-MM-DD. Example: \"2026-07-01\""},{"schema":{"type":"string"},"in":"query","name":"dueDate","required":true,"description":"Contractual payment due date, YYYY-MM-DD. Interest accrues from the day after this date. Example: \"2026-07-15\""},{"schema":{"type":"string"},"in":"query","name":"paymentDate","required":true,"description":"Actual payment date (YYYY-MM-DD), or today's date if still unpaid. Example: \"2026-08-10\""},{"schema":{"type":"string"},"in":"query","name":"contractualRatePct","required":false,"description":"Optional contractual interest rate (% per annum). Only used if higher than the statutory rate. Example: \"15\""}],"responses":{"200":{"description":"Late-payment interest calculation with period breakdown and provenance.","content":{"application/json":{"schema":{"type":"object","description":"Late-payment interest calculation with period breakdown and provenance.","properties":{"result":{"type":"object","properties":{"overdueDays":{"type":"integer","description":"Total number of calendar days the invoice was overdue."},"periods":{"type":"array","description":"Interest broken down by statutory rate period. Multiple entries when rates changed during the overdue window.","items":{"type":"object","properties":{"from":{"type":"string","description":"Period start date YYYY-MM-DD."},"to":{"type":"string","description":"Period end date YYYY-MM-DD."},"ratePct":{"type":"number","description":"Annual rate applied in this period."},"days":{"type":"integer","description":"Number of days in this period."},"interest":{"type":"number","description":"Interest accrued in this period."}}}},"totalInterest":{"type":"number","description":"Total interest accrued across all periods."},"recoveryCompensation":{"type":"number","description":"Fixed recovery compensation amount."},"recoveryCompensationCurrency":{"type":"string","description":"Currency of the recovery compensation (EUR or GBP)."},"totalClaimable":{"type":"number","description":"Total claimable (interest + compensation where same currency)."},"rateUsed":{"type":"string","enum":["statutory","contractual"],"description":"Whether the statutory or contractual rate was applied."},"currentStatutoryRatePct":{"type":"number","description":"Current statutory rate for this jurisdiction."},"currency":{"type":"string","description":"Invoice currency."}}},"jurisdiction":{"type":"string","description":"ISO 3166-1 alpha-2 jurisdiction used."},"ruleset_version":{"type":"string","description":"Rate dataset version, e.g. eu-late-payments-2026-h2."},"effective_date":{"type":"string","description":"Due date from which interest accrues."},"sources":{"type":"array","items":{"type":"string"},"description":"Official source URLs."},"calculation_steps":{"type":"array","items":{"type":"string"},"description":"Human-readable audit trail of the calculation."},"warnings":{"type":"array","items":{"type":"string"},"description":"Any warnings about data availability or rate overrides."},"refreshed_at":{"type":"string","description":"ISO timestamp of last data refresh."},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"CzechiaOverdueExample":{"summary":"€5,000 invoice 26 days overdue in Czechia","value":{"result":{"overdueDays":26,"periods":[{"from":"2026-07-16","to":"2026-08-10","ratePct":11.75,"days":26,"interest":41.85}],"totalInterest":41.85,"recoveryCompensation":70,"recoveryCompensationCurrency":"EUR","totalClaimable":111.85,"rateUsed":"statutory","currentStatutoryRatePct":11.75,"currency":"EUR"},"jurisdiction":"CZ","ruleset_version":"eu-late-payments-2026-h2","effective_date":"2026-07-15","sources":["https://europa.eu/youreurope/business/finance-and-tax/making-receiving-payments/late-payment/index_en.htm"],"calculation_steps":["Overdue period: 2026-07-15 to 2026-08-10 = 26 days","Period 2026-07-16–2026-08-10: 26 days × 11.75% / 365 × 5000 EUR = 41.85 EUR","Total interest: 41.85 EUR","Fixed recovery compensation: 70.00 EUR (invoice amount: 5000 EUR)"],"warnings":[],"refreshed_at":"2026-08-18T03:00:00.000Z"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/invoice-interest":{"get":{"summary":"Calculate statutory interest owed on an overdue invoice.","tags":["Finance"],"description":"Simplified late-payment interest calculator for B2B overdue invoices. Returns total interest, fixed recovery compensation, and a calculation breakdown under EU Directive 2011/7/EU or the UK Late Payment of Commercial Debts Act. Assumes a business (not public-authority) debtor. If paymentDate is omitted, today's date is used (invoice still unpaid). Use /v1/late-payment-interest for public-authority debtors or contractual rate overrides. Example: \"An invoice for £2,500 was due 2026-07-01 in the UK — how much interest can I charge today?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"jurisdiction","required":true,"description":"ISO 3166-1 alpha-2 country code of the creditor. Determines the statutory rate. Example: \"GB\", \"DE\", \"FR\", \"IT\""},{"schema":{"type":"string"},"in":"query","name":"invoiceAmount","required":true,"description":"Net invoice amount (before tax) on which interest is calculated. Example: \"2500\""},{"schema":{"type":"string"},"in":"query","name":"currency","required":true,"description":"ISO 4217 currency code of the invoice. Example: \"GBP\", \"EUR\""},{"schema":{"type":"string"},"in":"query","name":"dueDate","required":true,"description":"Contractual payment due date, YYYY-MM-DD. Interest accrues from the day after. Example: \"2026-07-01\""},{"schema":{"type":"string"},"in":"query","name":"paymentDate","required":false,"description":"Actual or expected payment date, YYYY-MM-DD. Defaults to today if omitted. Example: \"2026-08-20\""}],"responses":{"200":{"description":"Statutory interest and recovery compensation on the overdue invoice.","content":{"application/json":{"schema":{"type":"object","description":"Statutory interest and recovery compensation on the overdue invoice.","additionalProperties":true}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/price-indexation":{"get":{"summary":"Inflation-index a value using Eurostat HICP monthly data.","tags":["Business Finance"],"description":"Indexes a contract or historical value between two periods using the Eurostat Harmonised Index of Consumer Prices (HICP). Covers EU/EEA member states plus the UK, CP00 (all items, base 2015=100), monthly data from 2010. basePeriod and targetPeriod use YYYY-MM format. Use for contract escalation clauses, lease reviews, inflation-adjusted valuations, legal damages, and real purchasing power comparisons. Example: \"What is €10,000 from January 2015 worth in Germany as of June 2025?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"baseValue","required":true,"description":"Original contract/amount value to index. Must be a positive number. Example: \"10000\""},{"schema":{"type":"string"},"in":"query","name":"basePeriod","required":true,"description":"Base period, YYYY-MM. Example: \"2015-01\""},{"schema":{"type":"string"},"in":"query","name":"targetPeriod","required":true,"description":"Target period, YYYY-MM. Example: \"2025-06\""},{"schema":{"type":"string"},"in":"query","name":"geo","required":true,"description":"ISO 3166-1 alpha-2 country code. Example: \"DE\", \"FR\", \"GB\""},{"schema":{"type":"string"},"in":"query","name":"coicop","required":false,"description":"COICOP classification code. Default: \"CP00\" (all items)."},{"schema":{"type":"string","enum":["json","csv"]},"in":"query","name":"format","required":false,"description":"Response format. Default: json."}],"responses":{"200":{"description":"Indexed value with a full calculation audit trail and provenance.","content":{"application/json":{"schema":{"type":"object","description":"Indexed value with a full calculation audit trail and provenance.","properties":{"result":{"type":"object","properties":{"indexedValue":{"type":"number","description":"baseValue scaled by the ratio of targetIndex to baseIndex."},"absoluteChange":{"type":"number","description":"indexedValue minus baseValue."},"changePct":{"type":"number","description":"Percentage change between the base and target index."},"baseIndex":{"type":"number","description":"HICP index at basePeriod."},"targetIndex":{"type":"number","description":"HICP index at targetPeriod."},"months":{"type":"integer","description":"Signed month difference between basePeriod and targetPeriod."},"geo":{"type":"string"},"geo_name":{"type":"string"},"coicop":{"type":"string"},"coicop_label":{"type":"string"},"basePeriod":{"type":"string"},"targetPeriod":{"type":"string"}}},"jurisdiction":{"type":"string"},"effective_date":{"type":"string"},"ruleset_version":{"type":"string","description":"e.g. \"Eurostat HICP CP00 (2015=100)\""},"sources":{"type":"array","items":{"type":"string"}},"refreshed_at":{"type":"string","description":"Most recent period available in the dataset for this geo/coicop."},"calculation_steps":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"GermanyExample":{"summary":"€10,000 from January 2015 indexed to June 2025 in Germany","value":{"result":{"indexedValue":12345.67,"absoluteChange":2345.67,"changePct":23.46,"baseIndex":100,"targetIndex":123.46,"months":125,"geo":"DE","geo_name":"Germany","coicop":"CP00","coicop_label":"All items","basePeriod":"2015-01","targetPeriod":"2025-06"},"jurisdiction":"Germany","effective_date":"2025-06","ruleset_version":"Eurostat HICP CP00 (2015=100)","sources":["https://ec.europa.eu/eurostat/databrowser/view/prc_hicp_midx/default/table"],"refreshed_at":"2025-12","calculation_steps":["Base period: 2015-01 — HICP index 100","Target period: 2025-06 — HICP index 123.46","Indexation factor: 123.46 ÷ 100 = 1.23 (+23.46%)","Indexed value: 10000 × 1.23 = 12345.67"],"warnings":[]}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/rent-vs-buy":{"get":{"summary":"Compare buying a home with a mortgage against renting and investing the difference.","tags":["Finance"],"description":"Compare buying a home with a mortgage against renting and investing the difference. Use this when a user is deciding whether to buy or rent and wants to see which leaves them better off financially over time. Returns a break-even year and a year-by-year net worth schedule for both scenarios. Does not model property tax, insurance, maintenance, or home appreciation, since none of those are inputs. Example: \"Is it better to buy a $400,000 home or rent for $2,000/month and invest the difference over 10 years?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"homePrice","required":true,"description":"Total price of the home"},{"schema":{"type":"string"},"in":"query","name":"downPayment","required":true,"description":"Down payment amount"},{"schema":{"type":"string"},"in":"query","name":"mortgageRate","required":true,"description":"Annual mortgage interest rate as a percentage"},{"schema":{"type":"string"},"in":"query","name":"termYears","required":true,"description":"Mortgage term in years"},{"schema":{"type":"string"},"in":"query","name":"monthlyRent","required":true,"description":"Monthly rent for the equivalent rental"},{"schema":{"type":"string"},"in":"query","name":"annualRentIncrease","required":true,"description":"Annual rent increase as a percentage"},{"schema":{"type":"string"},"in":"query","name":"investmentReturnRate","required":true,"description":"Annual return the renter earns investing the down payment and any monthly savings, as a percentage"},{"schema":{"type":"string"},"in":"query","name":"years","required":true,"description":"How many years to compare over"}],"responses":{"200":{"description":"Net worth difference between buying and renting at the comparison horizon, break-even year, and a year-by-year net worth schedule.","content":{"application/json":{"schema":{"type":"object","description":"Net worth difference between buying and renting at the comparison horizon, break-even year, and a year-by-year net worth schedule.","properties":{"result":{"type":"object","description":"Rent-vs-buy comparison results.","properties":{"netWorthDifference":{"type":"number","description":"Buyer net worth minus renter net worth at the comparison horizon; positive favors buying. Example: 8035.76"},"breakEvenYear":{"type":["null","number"],"description":"First year buying's net worth catches up to renting's, or null if it never does within the horizon. Example: 9"},"totalCostToBuy":{"type":"number","description":"Cumulative cash spent buying through the comparison horizon. Example: 322714.4"},"totalCostToRent":{"type":"number","description":"Cumulative cash spent renting through the comparison horizon. Example: 275133.1"},"schedule":{"type":"array","description":"Year-by-year cumulative costs and net worth under each scenario.","items":{"type":"object","properties":{"year":{"type":"number","description":"Year number. Example: 1"},"cumulativeCostToBuy":{"type":"number","description":"Cumulative cash spent buying through this year. Example: 104271.44"},"cumulativeCostToRent":{"type":"number","description":"Cumulative cash spent renting through this year. Example: 24000"},"buyerNetWorth":{"type":"number","description":"Buyer's home equity minus cash spent, through this year. Example: 83576.75"},"renterNetWorth":{"type":"number","description":"Renter's invested portfolio value through this year. Example: 86063.53"},"netWorthDifference":{"type":"number","description":"Buyer net worth minus renter net worth through this year. Example: -2486.78"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FourHundredKOverTenYears":{"summary":"$400,000 home vs $2,000/month rent, compared over 10 years","value":{"result":{"netWorthDifference":8035.76,"breakEvenYear":9,"totalCostToBuy":322714.4,"totalCostToRent":275133.1,"schedule":[{"year":1,"cumulativeCostToBuy":104271.44,"cumulativeCostToRent":24000,"buyerNetWorth":83576.75,"renterNetWorth":86063.53,"netWorthDifference":-2486.78},{"year":2,"cumulativeCostToBuy":128542.88,"cumulativeCostToRent":48720,"buyerNetWorth":87393.04,"renterNetWorth":91821.83,"netWorthDifference":-4428.79},{"year":3,"cumulativeCostToBuy":152814.32,"cumulativeCostToRent":74181.6,"buyerNetWorth":91464.92,"renterNetWorth":97230.54,"netWorthDifference":-5765.62},{"year":4,"cumulativeCostToBuy":177085.76,"cumulativeCostToRent":100407.05,"buyerNetWorth":95809.5,"renterNetWorth":102241.41,"netWorthDifference":-6431.92},{"year":5,"cumulativeCostToBuy":201357.2,"cumulativeCostToRent":127419.26,"buyerNetWorth":100445.04,"renterNetWorth":106802.01,"netWorthDifference":-6356.98},{"year":6,"cumulativeCostToBuy":225628.64,"cumulativeCostToRent":155241.84,"buyerNetWorth":105391.03,"renterNetWorth":110855.43,"netWorthDifference":-5464.4},{"year":7,"cumulativeCostToBuy":249900.08,"cumulativeCostToRent":183899.09,"buyerNetWorth":110668.26,"renterNetWorth":114339.87,"netWorthDifference":-3671.61},{"year":8,"cumulativeCostToBuy":274171.52,"cumulativeCostToRent":213416.07,"buyerNetWorth":116298.92,"renterNetWorth":117188.37,"netWorthDifference":-889.45},{"year":9,"cumulativeCostToBuy":298442.96,"cumulativeCostToRent":243818.55,"buyerNetWorth":122306.68,"renterNetWorth":119328.31,"netWorthDifference":2978.37},{"year":10,"cumulativeCostToBuy":322714.4,"cumulativeCostToRent":275133.1,"buyerNetWorth":128716.79,"renterNetWorth":120681.02,"netWorthDifference":8035.76}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/currency":{"get":{"summary":"Convert an amount from one currency to another using live exchange rates.","tags":["Finance"],"description":"Convert an amount from one currency to another using live exchange rates. Use this when a user needs an up-to-date currency conversion. Returns the converted amount and the exchange rate used. Example: \"Convert 500 USD to EUR.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"amount","required":true,"description":"Amount to convert. Example: 500"},{"schema":{"type":"string"},"in":"query","name":"from","required":true,"description":"ISO 4217 currency code to convert from. Example: \"USD\""},{"schema":{"type":"string"},"in":"query","name":"to","required":true,"description":"ISO 4217 currency code to convert to. Example: \"EUR\""}],"responses":{"200":{"description":"The converted amount and the live exchange rate used.","content":{"application/json":{"schema":{"type":"object","description":"The converted amount and the live exchange rate used.","properties":{"result":{"type":"object","description":"The conversion result.","properties":{"convertedAmount":{"type":"number","description":"The amount converted into the target currency. Example: 432.83"},"rate":{"type":"number","description":"The exchange rate applied (1 unit of \"from\" in \"to\"). Example: 0.865666"},"from":{"type":"string","description":"The source currency code, uppercased. Example: \"USD\""},"to":{"type":"string","description":"The target currency code, uppercased. Example: \"EUR\""},"amount":{"type":"number","description":"The original amount that was converted. Example: 500"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"cached":{"type":"boolean","description":"Whether the exchange rate came from cache rather than a live fetch."},"source":{"type":"string","description":"Where the rate came from. Example: \"exchangerate-api\""},"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}},"examples":{"UsdToEur":{"summary":"Convert 500 USD to EUR at the live rate","value":{"result":{"convertedAmount":432.83,"rate":0.865666,"from":"USD","to":"EUR","amount":500},"meta":{"cached":false,"source":"exchangerate-api","computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/npv":{"post":{"summary":"Calculate net present value (NPV), internal rate of return (IRR), and payback period for a series of cash flows.","tags":["Finance"],"description":"Calculate net present value (NPV), internal rate of return (IRR), and payback period for a series of cash flows. Use this when a user is evaluating whether a project or investment is worth its upfront cost given expected future cash flows. Example: \"What is the NPV of a $50,000 investment returning $15,000 a year for 5 years at a 10% discount rate?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"initialInvestment":{"type":"number","description":"Upfront investment (positive number). Example: 50000"},"cashFlows":{"type":"array","items":{"type":"number"},"description":"Cash flow for each period, starting at period 1. Example: [15000, 15000, 15000, 15000, 15000]"},"discountRate":{"type":"number","description":"Discount rate as a percentage, e.g. 10 for 10%. Example: 10"}},"required":["initialInvestment","cashFlows","discountRate"]}}}},"responses":{"200":{"description":"Net present value, internal rate of return, and payback period for the cash flow series, with a per-period breakdown.","content":{"application/json":{"schema":{"type":"object","description":"Net present value, internal rate of return, and payback period for the cash flow series, with a per-period breakdown.","properties":{"result":{"type":"object","description":"NPV calculation results.","properties":{"npv":{"type":"number","description":"Net present value at the given discount rate. Example: 6861.8"},"irr":{"type":["null","number"],"description":"Internal rate of return, as a percentage; null if no real root exists in a plausible range. Example: 15.24"},"paybackPeriod":{"type":["null","number"],"description":"Fractional number of periods to recoup the initial investment; null if never recouped. Example: 3.33"},"schedule":{"type":"array","description":"Per-period cash flow, discounted cash flow, and cumulative cash flow.","items":{"type":"object","properties":{"period":{"type":"number","description":"Period number, starting at 1. Example: 1"},"cashFlow":{"type":"number","description":"Undiscounted cash flow for this period. Example: 15000"},"discountedCashFlow":{"type":"number","description":"Present value of this period's cash flow. Example: 13636.36"},"cumulativeCashFlow":{"type":"number","description":"Running total of undiscounted cash flows through this period. Example: 15000"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FiftyKInvestment":{"summary":"$50,000 investment returning $15,000/year for 5 years at a 10% discount rate","value":{"result":{"npv":6861.8,"irr":15.24,"paybackPeriod":3.33,"schedule":[{"period":1,"cashFlow":15000,"discountedCashFlow":13636.36,"cumulativeCashFlow":15000},{"period":2,"cashFlow":15000,"discountedCashFlow":12396.69,"cumulativeCashFlow":30000},{"period":3,"cashFlow":15000,"discountedCashFlow":11269.72,"cumulativeCashFlow":45000},{"period":4,"cashFlow":15000,"discountedCashFlow":10245.2,"cumulativeCashFlow":60000},{"period":5,"cashFlow":15000,"discountedCashFlow":9313.82,"cumulativeCashFlow":75000}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/bond-price":{"get":{"summary":"Price a fixed-rate bond from its face value, coupon rate, years to maturity, and market yield.","tags":["Finance"],"description":"Price a fixed-rate bond from its face value, coupon rate, years to maturity, and market yield. Use this when a user wants to know what a bond is worth given current market yields, or wants its duration to gauge interest-rate sensitivity. Returns the bond price, Macaulay duration, and yield to maturity. Example: \"What is the price of a 10-year, $1,000 face value bond with a 5% coupon rate if the market yield is 6%?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"faceValue","required":true,"description":"Face (par) value of the bond. Example: 1000"},{"schema":{"type":"string"},"in":"query","name":"couponRate","required":true,"description":"Annual coupon rate as a percentage, e.g. 5 for 5%. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"yearsToMaturity","required":true,"description":"Years until the bond matures. Example: 10"},{"schema":{"type":"string"},"in":"query","name":"marketYield","required":true,"description":"Market yield (discount rate) as a percentage. Example: 6"}],"responses":{"200":{"description":"The bond's price, duration, and yield to maturity, with a year-by-year coupon/present-value schedule.","content":{"application/json":{"schema":{"type":"object","description":"The bond's price, duration, and yield to maturity, with a year-by-year coupon/present-value schedule.","properties":{"result":{"type":"object","description":"Bond pricing results.","properties":{"price":{"type":"number","description":"Present value (price) of the bond. Example: 926.4"},"duration":{"type":"number","description":"Macaulay duration, in years. Example: 8.02"},"yieldToMaturity":{"type":"number","description":"Yield to maturity solved numerically from the price, as a percentage. Example: 6"},"schedule":{"type":"array","description":"Per-year coupon payment and its present value.","items":{"type":"object","properties":{"year":{"type":"number","description":"Year of the cash flow. Example: 1"},"couponPayment":{"type":"number","description":"Coupon cash flow for this year (includes face value in the final year). Example: 50"},"presentValue":{"type":"number","description":"Present value of this year's cash flow. Example: 47.17"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"TenYearBond":{"summary":"Price a 10-year, $1,000 face value, 5% coupon bond at a 6% market yield","value":{"result":{"price":926.4,"duration":8.02,"yieldToMaturity":6,"schedule":[{"year":1,"couponPayment":50,"presentValue":47.17},{"year":2,"couponPayment":50,"presentValue":44.5},{"year":3,"couponPayment":50,"presentValue":41.98},{"year":4,"couponPayment":50,"presentValue":39.6},{"year":5,"couponPayment":50,"presentValue":37.36},{"year":6,"couponPayment":50,"presentValue":35.25},{"year":7,"couponPayment":50,"presentValue":33.25},{"year":8,"couponPayment":50,"presentValue":31.37},{"year":9,"couponPayment":50,"presentValue":29.59},{"year":10,"couponPayment":50,"presentValue":586.31}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/share-price":{"get":{"summary":"Estimate the intrinsic value of a dividend-paying stock using the Gordon Growth Model.","tags":["Finance"],"description":"Estimate the intrinsic value of a dividend-paying stock using the Gordon Growth Model. Use this when a user wants a fair-value estimate for a stable, dividend-paying stock based on its dividend and expected growth. Returns intrinsic value per share, with a sensitivity table varying the required return and growth rate. Example: \"What is the intrinsic value of a stock expected to pay a $2 dividend next year, with a 9% required return and 3% growth?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"nextYearDividend","required":true,"description":"Expected dividend per share next year (D1). Example: 2"},{"schema":{"type":"string"},"in":"query","name":"requiredReturn","required":true,"description":"Required rate of return as a percentage. Example: 9"},{"schema":{"type":"string"},"in":"query","name":"dividendGrowthRate","required":true,"description":"Expected long-run dividend growth rate as a percentage; must be less than requiredReturn. Example: 3"}],"responses":{"200":{"description":"The intrinsic share value from the Gordon Growth Model, with a sensitivity table across nearby required returns and growth rates.","content":{"application/json":{"schema":{"type":"object","description":"The intrinsic share value from the Gordon Growth Model, with a sensitivity table across nearby required returns and growth rates.","properties":{"result":{"type":"object","description":"Gordon Growth Model results.","properties":{"intrinsicValue":{"type":"number","description":"Estimated intrinsic value per share. Example: 33.33"},"requiredReturn":{"type":"number","description":"Required rate of return used, as a percentage, echoed from the input. Example: 9"},"dividendGrowthRate":{"type":"number","description":"Dividend growth rate used, as a percentage, echoed from the input. Example: 3"},"sensitivityTable":{"type":"array","description":"5x5 grid of prices across required returns and growth rates +/- 2 percentage points around the inputs.","items":{"type":"object","properties":{"requiredReturn":{"type":"number","description":"Required return for this grid cell, as a percentage. Example: 7"},"growthRate":{"type":"number","description":"Growth rate for this grid cell, as a percentage. Example: 1"},"price":{"type":["null","number"],"description":"Implied price for this combination, or null when requiredReturn <= growthRate (the model is undefined there). Example: 33.33"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"TwoDollarDividend":{"summary":"$2 dividend next year, 9% required return, 3% growth","value":{"result":{"intrinsicValue":33.33,"requiredReturn":9,"dividendGrowthRate":3,"sensitivityTable":[{"requiredReturn":7,"growthRate":1,"price":33.33},{"requiredReturn":7,"growthRate":2,"price":40},{"requiredReturn":7,"growthRate":3,"price":50},{"requiredReturn":7,"growthRate":4,"price":66.67},{"requiredReturn":7,"growthRate":5,"price":100},{"requiredReturn":8,"growthRate":1,"price":28.57},{"requiredReturn":8,"growthRate":2,"price":33.33},{"requiredReturn":8,"growthRate":3,"price":40},{"requiredReturn":8,"growthRate":4,"price":50},{"requiredReturn":8,"growthRate":5,"price":66.67},{"requiredReturn":9,"growthRate":1,"price":25},{"requiredReturn":9,"growthRate":2,"price":28.57},{"requiredReturn":9,"growthRate":3,"price":33.33},{"requiredReturn":9,"growthRate":4,"price":40},{"requiredReturn":9,"growthRate":5,"price":50},{"requiredReturn":10,"growthRate":1,"price":22.22},{"requiredReturn":10,"growthRate":2,"price":25},{"requiredReturn":10,"growthRate":3,"price":28.57},{"requiredReturn":10,"growthRate":4,"price":33.33},{"requiredReturn":10,"growthRate":5,"price":40},{"requiredReturn":11,"growthRate":1,"price":20},{"requiredReturn":11,"growthRate":2,"price":22.22},{"requiredReturn":11,"growthRate":3,"price":25},{"requiredReturn":11,"growthRate":4,"price":28.57},{"requiredReturn":11,"growthRate":5,"price":33.33}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/income-tax":{"get":{"summary":"Calculate income tax owed for the US (federal, 2026 brackets) or UK (2026/27 bands, with personal allowance taper).","tags":["Finance"],"description":"Calculate income tax owed for the US (federal, 2026 brackets) or UK (2026/27 bands, with personal allowance taper). Use this when a user wants to know how much tax they owe, their effective and marginal rates, or a bracket-by-bracket breakdown. Example: \"How much US federal income tax is owed on a $95,000 salary filing single?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"income","required":true,"description":"Gross annual income. Example: 95000"},{"schema":{"type":"string","enum":["US","UK"]},"in":"query","name":"country","required":true,"description":"Tax jurisdiction. Example: \"US\""},{"schema":{"type":"string","enum":["single","marriedFilingJointly"]},"in":"query","name":"filingStatus","required":false,"description":"Required when country is \"US\"; not applicable to \"UK\". Example: \"single\""}],"responses":{"200":{"description":"Tax owed with a bracket-by-bracket breakdown.","content":{"application/json":{"schema":{"type":"object","description":"Tax owed with a bracket-by-bracket breakdown.","properties":{"result":{"type":"object","description":"The tax computation.","properties":{"taxOwed":{"type":"number","description":"Total tax owed. Example: 15612"},"effectiveRate":{"type":"number","description":"Tax owed as a percentage of taxable income."},"marginalRate":{"type":"number","description":"The tax rate applied to the last dollar earned."},"taxableIncome":{"type":"number","description":"Income after any applicable allowance/deduction (US bracket tables already bake the standard deduction into the band thresholds, so this equals gross income for US; for UK it's income minus the tapered personal allowance)."},"personalAllowance":{"type":["null","number"],"description":"The UK personal allowance applied (tapered above the threshold), or null for US."},"breakdown":{"type":"array","description":"One entry per tax band the income passed through.","items":{"type":"object","properties":{"rate":{"type":"number","description":"The band's tax rate, as a percentage."},"bandStart":{"type":"number","description":"The band's lower bound."},"bandEnd":{"type":["null","number"],"description":"The band's upper bound, or null for the top open-ended band."},"taxableInBand":{"type":"number","description":"Amount of income taxed within this band."},"taxInBand":{"type":"number","description":"Tax owed within this band."}}}},"country":{"type":"string","enum":["US","UK"],"description":"The tax jurisdiction used."},"currency":{"type":"string","description":"The currency of all monetary fields. Example: \"USD\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsSingle95k":{"summary":"US federal tax on a $95,000 single filer","value":{"result":{"taxOwed":15612,"effectiveRate":16.43,"marginalRate":22,"taxableIncome":95000,"personalAllowance":null,"breakdown":[{"rate":10,"bandStart":0,"bandEnd":12400,"taxableInBand":12400,"taxInBand":1240},{"rate":12,"bandStart":12400,"bandEnd":50400,"taxableInBand":38000,"taxInBand":4560},{"rate":22,"bandStart":50400,"bandEnd":105700,"taxableInBand":44600,"taxInBand":9812}],"country":"US","currency":"USD"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/inflation-adjusted-return":{"get":{"summary":"Calculate the inflation-adjusted (real) return on an investment.","tags":["Finance"],"description":"Calculate the inflation-adjusted (real) return on an investment. Use this when a user wants to know what their investment returns are actually worth after inflation, not just the nominal number. Returns real return, real and nominal future value of $1000, and purchasing power lost to inflation over a period of years. Example: \"What is the real return on a 7% investment if inflation is 3% over 15 years?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"nominalReturn","required":true,"description":"Nominal annual return as a percentage, e.g. 7 for 7%. Example: 7"},{"schema":{"type":"string"},"in":"query","name":"inflationRate","required":true,"description":"Annual inflation rate as a percentage, e.g. 3 for 3%. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"years","required":true,"description":"Time period in years. Example: 15"}],"responses":{"200":{"description":"The inflation-adjusted real return, and the real vs nominal future value of $1000 over the period.","content":{"application/json":{"schema":{"type":"object","description":"The inflation-adjusted real return, and the real vs nominal future value of $1000 over the period.","properties":{"result":{"type":"object","description":"Inflation-adjusted return results.","properties":{"realReturn":{"type":"number","description":"Inflation-adjusted annual return, as a percentage. Example: 3.88"},"realValueOf1000":{"type":"number","description":"What $1000 grows to in today's purchasing power. Example: 1770.92"},"nominalValueOf1000":{"type":"number","description":"What $1000 grows to in nominal (undeflated) dollars. Example: 2759.03"},"purchasingPowerLost":{"type":"number","description":"Nominal value minus real value — the purchasing power inflation erodes. Example: 988.11"},"years":{"type":"number","description":"Time period in years, echoed from the input. Example: 15"}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"SevenPercentThreeInflation":{"summary":"7% nominal return, 3% inflation, over 15 years","value":{"result":{"realReturn":3.88,"realValueOf1000":1770.92,"nominalValueOf1000":2759.03,"purchasingPowerLost":988.11,"years":15},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/break-even":{"get":{"summary":"Calculate the break-even point for a product.","tags":["Business Finance"],"description":"Calculate the break-even point for a product. Use this when a user wants to know how many units they need to sell to cover their costs, or how much sales cushion they currently have above break-even. Returns break-even units, break-even revenue, contribution margin, and margin of safety if current sales volume is provided. Example: \"How many units do I need to sell to break even with $10,000 in fixed costs, a $15 cost per unit, and a $25 selling price?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"fixedCosts","required":true,"description":"Total fixed costs for the period. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"variableCostPerUnit","required":true,"description":"Variable cost to produce/sell one unit. Example: 15"},{"schema":{"type":"string"},"in":"query","name":"sellingPricePerUnit","required":true,"description":"Selling price of one unit. Example: 25"},{"schema":{"type":"string"},"in":"query","name":"currentSalesVolume","required":false,"description":"Optional current sales volume in units, used to compute margin of safety. Example: 800"}],"responses":{"200":{"description":"Break-even units, break-even revenue, contribution margin, and margin of safety if currentSalesVolume was supplied.","content":{"application/json":{"schema":{"type":"object","description":"Break-even units, break-even revenue, contribution margin, and margin of safety if currentSalesVolume was supplied.","properties":{"result":{"type":"object","description":"The break-even result.","properties":{"breakEvenUnits":{"type":"number","description":"Units needed to cover fixed costs, rounded up. Example: 1000"},"breakEvenRevenue":{"type":"number","description":"Revenue at the break-even unit count. Example: 25000"},"contributionMargin":{"type":"number","description":"Selling price minus variable cost per unit. Example: 10"},"contributionMarginRatio":{"type":"number","description":"Contribution margin as a percentage of selling price. Example: 40"},"marginOfSafetyUnits":{"type":["null","number"],"description":"Current sales volume minus break-even units. Null if currentSalesVolume was not supplied. Example: -200"},"marginOfSafetyPercent":{"type":["null","number"],"description":"Margin of safety as a percentage of current sales volume. Null if currentSalesVolume was not supplied. Example: -25"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"10kFixedCosts":{"summary":"Break-even for $10,000 fixed costs, $15 variable cost, $25 selling price, 800 units sold","value":{"result":{"breakEvenUnits":1000,"breakEvenRevenue":25000,"contributionMargin":10,"contributionMarginRatio":40,"marginOfSafetyUnits":-200,"marginOfSafetyPercent":-25},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/loan-comparison":{"post":{"summary":"Compare two loans side by side.","tags":["Finance"],"description":"Compare two loans side by side. Use this when a user has two loan offers and wants to know which is cheaper overall, not just which has the lower rate or payment. Returns monthly payment, total interest, total cost, and a full amortization schedule for each, plus which loan is cheaper overall. Example: \"Compare a $20,000 loan at 6% over 5 years vs the same amount at 5.5% over 6 years.\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"loanA":{"type":"object","properties":{"principal":{"type":"number","description":"Loan principal amount. Example: 20000"},"annualRate":{"type":"number","description":"Annual interest rate as a percentage, e.g. 6 for 6%. Example: 6"},"termMonths":{"type":"number","description":"Loan term in months. Example: 60"},"label":{"type":"string","description":"Optional display label for this loan. Example: \"Bank A\""}},"required":["principal","annualRate","termMonths"]},"loanB":{"type":"object","properties":{"principal":{"type":"number","description":"Loan principal amount. Example: 20000"},"annualRate":{"type":"number","description":"Annual interest rate as a percentage, e.g. 6 for 6%. Example: 6"},"termMonths":{"type":"number","description":"Loan term in months. Example: 60"},"label":{"type":"string","description":"Optional display label for this loan. Example: \"Bank A\""}},"required":["principal","annualRate","termMonths"]}},"required":["loanA","loanB"]}}}},"responses":{"200":{"description":"Side-by-side loan comparison, with each loan's full amortization schedule and the differences between them.","content":{"application/json":{"schema":{"type":"object","description":"Side-by-side loan comparison, with each loan's full amortization schedule and the differences between them.","properties":{"result":{"type":"object","description":"Loan comparison results.","properties":{"loanA":{"type":"object","description":"Computed results for loan A.","properties":{"label":{"type":"string","description":"Display label for this loan. Example: \"Bank A\""},"monthlyPayment":{"type":"number","description":"Monthly payment. Example: 386.66"},"principal":{"type":"number","description":"Loan principal, echoed from the input. Example: 20000"},"annualRate":{"type":"number","description":"Annual interest rate, percent, echoed from the input. Example: 6"},"termMonths":{"type":"number","description":"Loan term in months, echoed from the input. Example: 60"},"totalInterest":{"type":"number","description":"Total interest paid over the life of the loan. Example: 3199.36"},"totalCost":{"type":"number","description":"Total of all payments over the life of the loan. Example: 23199.36"},"schedule":{"type":"array","description":"Month-by-month amortization schedule.","items":{"type":"object","properties":{"month":{"type":"number","description":"Month number. Example: 1"},"principal":{"type":"number","description":"Principal portion of this month's payment. Example: 286.66"},"interest":{"type":"number","description":"Interest portion of this month's payment. Example: 100"},"balance":{"type":"number","description":"Remaining loan balance after this payment. Example: 19713.34"}}}}}},"loanB":{"type":"object","description":"Computed results for loan B (same shape as loanA).","properties":{"label":{"type":"string","description":"Display label for this loan. Example: \"Bank B\""},"monthlyPayment":{"type":"number","description":"Monthly payment. Example: 326.76"},"principal":{"type":"number","description":"Loan principal, echoed from the input. Example: 20000"},"annualRate":{"type":"number","description":"Annual interest rate, percent, echoed from the input. Example: 5.5"},"termMonths":{"type":"number","description":"Loan term in months, echoed from the input. Example: 72"},"totalInterest":{"type":"number","description":"Total interest paid over the life of the loan. Example: 3526.56"},"totalCost":{"type":"number","description":"Total of all payments over the life of the loan. Example: 23526.56"},"schedule":{"type":"array","description":"Month-by-month amortization schedule.","items":{"type":"object","properties":{"month":{"type":"number","description":"Month number. Example: 1"},"principal":{"type":"number","description":"Principal portion of this month's payment. Example: 235.09"},"interest":{"type":"number","description":"Interest portion of this month's payment. Example: 91.67"},"balance":{"type":"number","description":"Remaining loan balance after this payment. Example: 19764.91"}}}}}},"monthlyPaymentDifference":{"type":"number","description":"loanA's monthly payment minus loanB's. Example: 59.9"},"totalInterestDifference":{"type":"number","description":"loanA's total interest minus loanB's. Example: -327.2"},"totalCostDifference":{"type":"number","description":"loanA's total cost minus loanB's. Example: -327.2"},"cheaperLoan":{"type":"string","enum":["A","B","tie"],"description":"Which loan has the lower total cost. Example: \"A\""}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"TwentyKAt6vs5_5":{"summary":"$20,000 at 6% over 5 years vs 5.5% over 6 years (each schedule trimmed to first 3 and last 2 months)","value":{"result":{"loanA":{"label":"Bank A","monthlyPayment":386.66,"principal":20000,"annualRate":6,"termMonths":60,"totalInterest":3199.36,"totalCost":23199.36,"schedule":[{"month":1,"principal":286.66,"interest":100,"balance":19713.34},{"month":2,"principal":288.09,"interest":98.57,"balance":19425.25},{"month":3,"principal":289.53,"interest":97.13,"balance":19135.72},{"month":59,"principal":382.82,"interest":3.84,"balance":384.73},{"month":60,"principal":384.73,"interest":1.92,"balance":0}]},"loanB":{"label":"Bank B","monthlyPayment":326.76,"principal":20000,"annualRate":5.5,"termMonths":72,"totalInterest":3526.56,"totalCost":23526.56,"schedule":[{"month":1,"principal":235.09,"interest":91.67,"balance":19764.91},{"month":2,"principal":236.17,"interest":90.59,"balance":19528.74},{"month":3,"principal":237.25,"interest":89.51,"balance":19291.49},{"month":71,"principal":323.78,"interest":2.97,"balance":325.27},{"month":72,"principal":325.27,"interest":1.49,"balance":0}]},"monthlyPaymentDifference":59.9,"totalInterestDifference":-327.2,"totalCostDifference":-327.2,"cheaperLoan":"A"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/child-height":{"get":{"summary":"Predict a child's adult height using the mid-parental height formula, and optionally compute their current growth percentile against WHO height-for-age reference data.","tags":["Health & Life"],"description":"Predict a child's adult height using the mid-parental height formula, and optionally compute their current growth percentile against WHO height-for-age reference data. Use this when a parent asks how tall their child might grow to be, or how their child's current height compares to other children the same age. Returns a predicted adult height with a 95% range, and (if current age and height are given) a growth percentile. Example: \"How tall will my daughter be as an adult if her father is 180cm and mother is 165cm tall?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"fatherHeightCm","required":true,"description":"Father's height in cm. Example: 180"},{"schema":{"type":"string"},"in":"query","name":"motherHeightCm","required":true,"description":"Mother's height in cm. Example: 165"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"childSex","required":true,"description":"Child's sex. Example: \"F\""},{"schema":{"type":"string"},"in":"query","name":"childCurrentAgeYears","required":false,"description":"Optional: child's current age in years (2-19), for a growth percentile. Example: 8"},{"schema":{"type":"string"},"in":"query","name":"childCurrentHeightCm","required":false,"description":"Optional: child's current height in cm, required alongside childCurrentAgeYears. Example: 128"}],"responses":{"200":{"description":"Predicted adult height with a 95% range, and (if current age and height were given) a growth percentile vs WHO reference data.","content":{"application/json":{"schema":{"type":"object","description":"Predicted adult height with a 95% range, and (if current age and height were given) a growth percentile vs WHO reference data.","properties":{"result":{"type":"object","description":"The height prediction result.","properties":{"predictedAdultHeightCm":{"type":"number","description":"Predicted adult height in cm, from the mid-parental height formula. Example: 166"},"rangeLowCm":{"type":"number","description":"Low end of the 95% predicted range, in cm. Example: 156"},"rangeHighCm":{"type":"number","description":"High end of the 95% predicted range, in cm. Example: 176"},"growthPercentile":{"type":["null","number"],"description":"Current height percentile vs WHO height-for-age reference data, or null if childCurrentAgeYears/childCurrentHeightCm were not given. Example: 59.8"},"referenceMeanCm":{"type":["null","number"],"description":"WHO reference mean height for the child's age/sex, in cm, or null if not computed. Example: 126.56"},"referenceSdCm":{"type":["null","number"],"description":"WHO reference standard deviation for the child's age/sex, in cm, or null if not computed. Example: 5.8"}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"DaughterFatherOneEightyMotherOneSixtyFive":{"summary":"Father 180cm, mother 165cm, daughter currently 8 years old and 128cm","value":{"result":{"predictedAdultHeightCm":166,"rangeLowCm":156,"rangeHighCm":176,"growthPercentile":59.8,"referenceMeanCm":126.56,"referenceSdCm":5.8},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/confidence-interval":{"get":{"summary":"Calculate a confidence interval for a sample mean.","tags":["Science & Stats"],"description":"Calculate a confidence interval for a sample mean. Use this when a user has sample statistics and wants a range they can be confident the true population mean falls within. Returns interval bounds, margin of error, and a plain-English interpretation. Example: \"What is the 95% confidence interval for a sample mean of 50 with a standard deviation of 10 and a sample size of 40?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"sampleSize","required":true,"description":"Number of observations in the sample. Example: 40"},{"schema":{"type":"string"},"in":"query","name":"sampleMean","required":true,"description":"Sample mean. Example: 50"},{"schema":{"type":"string"},"in":"query","name":"standardDeviation","required":true,"description":"Sample (or known population) standard deviation. Example: 10"},{"schema":{"type":"string","enum":["90","95","99"]},"in":"query","name":"confidenceLevel","required":true,"description":"Confidence level as a percentage: 90, 95, or 99. Example: 95"}],"responses":{"200":{"description":"The confidence interval for a sample mean, with margin of error and standard error.","content":{"application/json":{"schema":{"type":"object","description":"The confidence interval for a sample mean, with margin of error and standard error.","properties":{"result":{"type":"object","description":"The confidence interval result.","properties":{"lowerBound":{"type":"number","description":"Lower bound of the confidence interval. Example: 46.9"},"upperBound":{"type":"number","description":"Upper bound of the confidence interval. Example: 53.1"},"marginOfError":{"type":"number","description":"Margin of error added/subtracted from the sample mean. Example: 3.1"},"standardError":{"type":"number","description":"Standard error of the mean. Example: 1.58"},"confidenceLevel":{"type":"number","description":"Confidence level used, as a percentage: 90, 95, or 99. Example: 95"},"interpretation":{"type":"string","description":"Plain-English summary of the interval."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"SampleMean50":{"summary":"95% CI for a sample mean of 50, sd 10, n=40","value":{"result":{"lowerBound":46.9,"upperBound":53.1,"marginOfError":3.1,"standardError":1.58,"confidenceLevel":95,"interpretation":"We are 95% confident that the true population mean lies between 46.9 and 53.1."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sample-size":{"get":{"summary":"Calculate the required sample size for a survey or study using Cochran's formula.","tags":["Science & Stats"],"description":"Calculate the required sample size for a survey or study using Cochran's formula. Use this when a user is designing a survey or experiment and needs to know how many respondents or subjects they need. Returns the required sample size, with finite population correction if a population size is given. Example: \"How many survey respondents do I need for a 95% confidence level and a 5% margin of error?\"","parameters":[{"schema":{"type":"string","enum":["90","95","99"]},"in":"query","name":"confidenceLevel","required":true,"description":"Confidence level as a percentage: 90, 95, or 99. Example: 95"},{"schema":{"type":"string"},"in":"query","name":"marginOfError","required":true,"description":"Desired margin of error as a percentage, e.g. 5 for ±5%. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"populationSize","required":false,"description":"Optional total population size; omit for an effectively infinite population. Example: 10000"}],"responses":{"200":{"description":"The required sample size for the given confidence level and margin of error, using Cochran's formula.","content":{"application/json":{"schema":{"type":"object","description":"The required sample size for the given confidence level and margin of error, using Cochran's formula.","properties":{"result":{"type":"object","description":"The sample size result.","properties":{"requiredSampleSize":{"type":"number","description":"The required sample size, rounded up. Example: 385"},"unadjustedSampleSize":{"type":"number","description":"Sample size before finite population correction, rounded up. Example: 385"},"confidenceLevel":{"type":"number","description":"Confidence level used, as a percentage: 90, 95, or 99. Example: 95"},"marginOfError":{"type":"number","description":"Margin of error used, as a percentage. Example: 5"},"populationSize":{"type":["null","number"],"description":"Population size used for finite population correction, or null if omitted (infinite population assumed)."},"formula":{"type":"string","description":"The formula used to compute the sample size."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"InfinitePopulation95pct5pct":{"summary":"95% confidence, ±5% margin of error, infinite population","value":{"result":{"requiredSampleSize":385,"unadjustedSampleSize":385,"confidenceLevel":95,"marginOfError":5,"populationSize":null,"formula":"Cochran's formula for an infinite population: n = (z²·p·(1-p)) / e²"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ab-test":{"get":{"summary":"Test whether the difference between two A/B test variants is statistically significant using a two-proportion z-test.","tags":["Science & Stats"],"description":"Test whether the difference between two A/B test variants is statistically significant using a two-proportion z-test. Use this when a user has conversion data for two variants and wants to know if variant B actually beat variant A, or if the difference could just be noise. Returns p-value, significance at 95% confidence, relative uplift, and a recommended action. Example: \"Is a 13% conversion rate significantly better than 10%, with 1000 visitors in each group?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"visitorsA","required":true,"description":"Number of visitors/participants in variant A. Example: 1000"},{"schema":{"type":"string"},"in":"query","name":"conversionsA","required":true,"description":"Number of conversions in variant A. Example: 100"},{"schema":{"type":"string"},"in":"query","name":"visitorsB","required":true,"description":"Number of visitors/participants in variant B. Example: 1000"},{"schema":{"type":"string"},"in":"query","name":"conversionsB","required":true,"description":"Number of conversions in variant B. Example: 130"}],"responses":{"200":{"description":"Statistical significance test result for a two-variant A/B test.","content":{"application/json":{"schema":{"type":"object","description":"Statistical significance test result for a two-variant A/B test.","properties":{"result":{"type":"object","description":"The significance test result.","properties":{"pValue":{"type":"number","description":"Two-tailed p-value from the z-test. Example: 0.0355"},"isSignificant":{"type":"boolean","description":"Whether the difference is significant at 95% confidence (p < 0.05). Example: true"},"conversionRateA":{"type":"number","description":"Variant A conversion rate as a percentage. Example: 10"},"conversionRateB":{"type":"number","description":"Variant B conversion rate as a percentage. Example: 13"},"relativeUplift":{"type":"number","description":"Variant B's relative uplift over A, as a percentage. Example: 30"},"zScore":{"type":"number","description":"The z-statistic for the difference in proportions. Example: 2.1"},"confidenceLevel":{"type":"number","description":"Confidence level implied by the p-value, as a percentage. Example: 96.45"},"recommendedAction":{"type":"string","description":"Plain-English recommendation based on the result. Example: \"Variant B wins — roll it out.\""}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"VariantBWins":{"summary":"1000 visitors per variant, B converts better","value":{"result":{"pValue":0.0355,"isSignificant":true,"conversionRateA":10,"conversionRateB":13,"relativeUplift":30,"zScore":2.1,"confidenceLevel":96.45,"recommendedAction":"Variant B wins — roll it out."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/retirement-savings":{"get":{"summary":"Project a retirement savings pot forward and check its adequacy against a desired retirement income.","tags":["Finance"],"description":"Project a retirement savings pot forward and check its adequacy against a desired retirement income. Use this when a user wants to know if they're on track for retirement, or how much monthly income their savings will support. Returns projected pot at retirement, monthly income it generates under the 4% rule, surplus or shortfall, and how many years the pot will last. Example: \"Am I on track to retire at 65 with $3,000/month if I'm 35 now, have $50,000 saved, and contribute $800/month at 7% expected return?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age. Example: 35"},{"schema":{"type":"string"},"in":"query","name":"retirementAge","required":true,"description":"Planned retirement age. Example: 65"},{"schema":{"type":"string"},"in":"query","name":"currentSavings","required":true,"description":"Current retirement savings balance. Example: 50000"},{"schema":{"type":"string"},"in":"query","name":"monthlyContribution","required":true,"description":"Monthly contribution amount. Example: 800"},{"schema":{"type":"string"},"in":"query","name":"expectedAnnualReturn","required":true,"description":"Expected annual investment return as a percentage, e.g. 7 for 7%. Example: 7"},{"schema":{"type":"string"},"in":"query","name":"desiredMonthlyIncome","required":true,"description":"Desired monthly income during retirement. Example: 3000"}],"responses":{"200":{"description":"Projected retirement pot, the monthly income it supports, and whether savings will last through retirement.","content":{"application/json":{"schema":{"type":"object","description":"Projected retirement pot, the monthly income it supports, and whether savings will last through retirement.","properties":{"result":{"type":"object","description":"Retirement savings projection results.","properties":{"projectedPotAtRetirement":{"type":"number","description":"Projected total savings at retirement. Example: 1381801.67"},"monthlyIncomeFromPot":{"type":"number","description":"Monthly income the pot supports under the 4% withdrawal rule. Example: 4606.01"},"surplusOrShortfall":{"type":"number","description":"monthlyIncomeFromPot minus desiredMonthlyIncome; positive is a surplus. Example: 1606.01"},"yearsSavingsWillLast":{"type":["null","number"],"description":"Years the pot lasts while withdrawing desiredMonthlyIncome each month; null if it never runs out (within 100 years) or desiredMonthlyIncome is 0."},"yearsUntilRetirement":{"type":"number","description":"retirementAge minus currentAge. Example: 30"}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"RetireAt65":{"summary":"Age 35 now, retiring at 65, $50,000 saved, $800/month contributions at 7% return, wants $3,000/month income","value":{"result":{"projectedPotAtRetirement":1381801.67,"monthlyIncomeFromPot":4606.01,"surplusOrShortfall":1606.01,"yearsSavingsWillLast":null,"yearsUntilRetirement":30},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/longevity":{"get":{"summary":"Estimate life expectancy from a WHO country/sex baseline adjusted for lifestyle factors.","tags":["Health & Life"],"description":"Estimate life expectancy from a WHO country/sex baseline adjusted for lifestyle factors. Use this when a user wants a personalized life expectancy estimate that accounts for their habits, not just a national average. Returns estimated life expectancy, years vs country average, remaining years, and a per-factor impact breakdown. Population-level estimate only, not a medical prediction. Example: \"What's my life expectancy if I'm a 40-year-old non-smoking woman in the US with a BMI of 24, exercising 120 minutes a week?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Current age. Example: 40"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex. Example: \"F\""},{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"WHO country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"smoker","required":true,"description":"Whether the person currently smokes. Example: false"},{"schema":{"type":"string"},"in":"query","name":"bmi","required":true,"description":"Body mass index. Example: 24"},{"schema":{"type":"string"},"in":"query","name":"exerciseMinPerWeek","required":true,"description":"Minutes of exercise per week. Example: 120"},{"schema":{"type":"string","enum":["poor","fair","good","excellent"]},"in":"query","name":"diet","required":true,"description":"Overall diet quality. Example: \"good\""},{"schema":{"type":"string"},"in":"query","name":"alcoholUnitsPerWeek","required":true,"description":"Alcohol units consumed per week. Example: 4"},{"schema":{"type":"string"},"in":"query","name":"sleepHours","required":true,"description":"Average hours of sleep per night. Example: 7"},{"schema":{"type":"string","enum":["low","medium","high"]},"in":"query","name":"socialConnections","required":true,"description":"Strength of social connections. Example: \"medium\""},{"schema":{"type":"string"},"in":"query","name":"chronicConditions","required":true,"description":"Number of chronic conditions: 0, 1, or 2+. Example: 0"},{"schema":{"type":"string"},"in":"query","name":"familyHistoryOfLongevity","required":true,"description":"Whether close family members lived to an old age. Example: true"}],"responses":{"200":{"description":"Estimated life expectancy adjusted for lifestyle factors, with a per-factor breakdown vs a WHO country/sex baseline.","content":{"application/json":{"schema":{"type":"object","description":"Estimated life expectancy adjusted for lifestyle factors, with a per-factor breakdown vs a WHO country/sex baseline.","properties":{"result":{"type":"object","description":"The life expectancy estimate.","properties":{"estimatedLifeExpectancy":{"type":"number","description":"Estimated life expectancy in years. Example: 85.51"},"yearsVsCountryAverage":{"type":"number","description":"Total lifestyle adjustment vs the country average, in years. Example: 6.41"},"remainingYears":{"type":"number","description":"Estimated remaining years of life from the current age. Example: 45.51"},"countryAverage":{"type":"number","description":"WHO life expectancy baseline for the country and sex. Example: 79.1"},"factorBreakdown":{"type":"array","description":"Per-factor contribution to the life expectancy adjustment.","items":{"type":"object","properties":{"factor":{"type":"string","description":"Name of the lifestyle factor. Example: \"Exercise\""},"impactYears":{"type":"number","description":"Years contributed; positive extends, negative shortens life expectancy. Example: 1.8"}}}},"caveat":{"type":"string","description":"Disclaimer that this is a population-level estimate, not a medical prediction."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"FortyYearOldNonSmokingWomanUSA":{"summary":"40-year-old non-smoking woman in the US, BMI 24, 120 min/week exercise, good diet","value":{"result":{"estimatedLifeExpectancy":85.51,"yearsVsCountryAverage":6.41,"remainingYears":45.51,"countryAverage":79.1,"factorBreakdown":[{"factor":"Smoking","impactYears":0},{"factor":"BMI","impactYears":0},{"factor":"Exercise","impactYears":1.8},{"factor":"Diet quality","impactYears":1.75},{"factor":"Alcohol","impactYears":-0.64},{"factor":"Sleep","impactYears":0.5},{"factor":"Social connections","impactYears":0},{"factor":"Chronic conditions","impactYears":0},{"factor":"Family history of longevity","impactYears":3}],"caveat":"Population-level estimate only — not a medical prediction."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/birthday-paradox":{"get":{"summary":"Calculate the probability that at least two people in a group share a birthday — the birthday paradox.","tags":["Science & Stats"],"description":"Calculate the probability that at least two people in a group share a birthday — the birthday paradox. Use this when a user asks how likely a shared birthday (or any shared-attribute collision) is in a group of a given size, e.g. for a probability lesson or a hash-collision intuition check. Returns the probability, 1-in-N odds, and a curve of probability vs group size from 2 to 70. Example: \"What's the probability that two people share a birthday in a group of 30?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"groupSize","required":true,"description":"Number of people in the group (2-366). Example: 30"}],"responses":{"200":{"description":"The probability that at least two people in the group share a birthday, plus a curve across group sizes 2-70.","content":{"application/json":{"schema":{"type":"object","description":"The probability that at least two people in the group share a birthday, plus a curve across group sizes 2-70.","properties":{"result":{"type":"object","description":"The birthday paradox result.","properties":{"probabilityPercent":{"type":"number","description":"Probability at least two people share a birthday, as a percentage. Example: 70.63"},"oddsOneInN":{"type":"number","description":"Same probability expressed as 1-in-N odds. Example: 1.42"},"groupSize":{"type":"number","description":"The group size that was evaluated. Example: 30"},"interpretation":{"type":"string","description":"Plain-English summary of the result."},"curve":{"type":"array","description":"Probability of a shared birthday for every group size from 2 to 70.","items":{"type":"object","properties":{"groupSize":{"type":"number","description":"Group size for this curve point."},"probabilityPercent":{"type":"number","description":"Probability of a shared birthday at this group size, as a percentage."}}}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"GroupOf30":{"summary":"Probability of a shared birthday in a group of 30","value":{"result":{"probabilityPercent":70.63,"oddsOneInN":1.42,"groupSize":30,"interpretation":"In a group of 30 people, there's a 70.63% chance at least two share a birthday.","curve":[{"groupSize":2,"probabilityPercent":0.27},{"groupSize":3,"probabilityPercent":0.82},{"groupSize":4,"probabilityPercent":1.64},{"groupSize":5,"probabilityPercent":2.71},{"groupSize":6,"probabilityPercent":4.05},{"groupSize":7,"probabilityPercent":5.62},{"groupSize":8,"probabilityPercent":7.43},{"groupSize":9,"probabilityPercent":9.46},{"groupSize":10,"probabilityPercent":11.69},{"groupSize":11,"probabilityPercent":14.11},{"groupSize":12,"probabilityPercent":16.7},{"groupSize":13,"probabilityPercent":19.44},{"groupSize":14,"probabilityPercent":22.31},{"groupSize":15,"probabilityPercent":25.29},{"groupSize":16,"probabilityPercent":28.36},{"groupSize":17,"probabilityPercent":31.5},{"groupSize":18,"probabilityPercent":34.69},{"groupSize":19,"probabilityPercent":37.91},{"groupSize":20,"probabilityPercent":41.14},{"groupSize":21,"probabilityPercent":44.37},{"groupSize":22,"probabilityPercent":47.57},{"groupSize":23,"probabilityPercent":50.73},{"groupSize":24,"probabilityPercent":53.83},{"groupSize":25,"probabilityPercent":56.87},{"groupSize":26,"probabilityPercent":59.82},{"groupSize":27,"probabilityPercent":62.69},{"groupSize":28,"probabilityPercent":65.45},{"groupSize":29,"probabilityPercent":68.1},{"groupSize":30,"probabilityPercent":70.63},{"groupSize":31,"probabilityPercent":73.05},{"groupSize":32,"probabilityPercent":75.33},{"groupSize":33,"probabilityPercent":77.5},{"groupSize":34,"probabilityPercent":79.53},{"groupSize":35,"probabilityPercent":81.44},{"groupSize":36,"probabilityPercent":83.22},{"groupSize":37,"probabilityPercent":84.87},{"groupSize":38,"probabilityPercent":86.41},{"groupSize":39,"probabilityPercent":87.82},{"groupSize":40,"probabilityPercent":89.12},{"groupSize":41,"probabilityPercent":90.32},{"groupSize":42,"probabilityPercent":91.4},{"groupSize":43,"probabilityPercent":92.39},{"groupSize":44,"probabilityPercent":93.29},{"groupSize":45,"probabilityPercent":94.1},{"groupSize":46,"probabilityPercent":94.83},{"groupSize":47,"probabilityPercent":95.48},{"groupSize":48,"probabilityPercent":96.06},{"groupSize":49,"probabilityPercent":96.58},{"groupSize":50,"probabilityPercent":97.04},{"groupSize":51,"probabilityPercent":97.44},{"groupSize":52,"probabilityPercent":97.8},{"groupSize":53,"probabilityPercent":98.11},{"groupSize":54,"probabilityPercent":98.39},{"groupSize":55,"probabilityPercent":98.63},{"groupSize":56,"probabilityPercent":98.83},{"groupSize":57,"probabilityPercent":99.01},{"groupSize":58,"probabilityPercent":99.17},{"groupSize":59,"probabilityPercent":99.3},{"groupSize":60,"probabilityPercent":99.41},{"groupSize":61,"probabilityPercent":99.51},{"groupSize":62,"probabilityPercent":99.59},{"groupSize":63,"probabilityPercent":99.66},{"groupSize":64,"probabilityPercent":99.72},{"groupSize":65,"probabilityPercent":99.77},{"groupSize":66,"probabilityPercent":99.81},{"groupSize":67,"probabilityPercent":99.84},{"groupSize":68,"probabilityPercent":99.87},{"groupSize":69,"probabilityPercent":99.9},{"groupSize":70,"probabilityPercent":99.92}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/poker-hand":{"get":{"summary":"Get the exact probability of being dealt a given 5-card poker hand from a standard 52-card deck.","tags":["Science & Stats"],"description":"Get the exact probability of being dealt a given 5-card poker hand from a standard 52-card deck. Use this when a user wants to know how rare a poker hand is, or wants to compare hand rarity. Returns ways to make it, probability, 1-in-N odds, rarity rank, and a comparison table of all 10 hand types. Example: \"What are the odds of being dealt a full house?\"","parameters":[{"schema":{"type":"string","enum":["Royal Flush","Straight Flush","Four of a Kind","Full House","Flush","Straight","Three of a Kind","Two Pair","One Pair","High Card"]},"in":"query","name":"handType","required":true,"description":"The poker hand type to look up. Example: \"Full House\""}],"responses":{"200":{"description":"Exact probability of the requested poker hand, plus a comparison table of all 10 hand types.","content":{"application/json":{"schema":{"type":"object","description":"Exact probability of the requested poker hand, plus a comparison table of all 10 hand types.","properties":{"result":{"type":"object","description":"The poker hand probability result.","properties":{"probabilityPercent":{"type":"number","description":"Probability of this hand, as a percentage. Example: 0.14"},"oddsOneInN":{"type":"number","description":"Same probability expressed as 1-in-N odds. Example: 694"},"waysToMake":{"type":"number","description":"Number of 5-card combinations that make this hand. Example: 3744"},"probability":{"type":"number","description":"Raw probability (0-1). Example: 0.001441"},"rank":{"type":"number","description":"Rarity rank, 1 = rarest, 10 = most common. Example: 4"},"handType":{"type":"string","description":"The hand type looked up. Example: \"Full House\""},"allHands":{"type":"array","description":"All 10 poker hand types with their stats, for comparison.","items":{"type":"object","properties":{"handType":{"type":"string","description":"The hand type name."},"rank":{"type":"number","description":"Rarity rank, 1 = rarest, 10 = most common."},"waysToMake":{"type":"number","description":"Number of 5-card combinations that make this hand."},"probability":{"type":"number","description":"Raw probability (0-1)."},"probabilityPercent":{"type":"number","description":"Probability as a percentage."},"oddsOneInN":{"type":"number","description":"Probability expressed as 1-in-N odds."}}}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"FullHouse":{"summary":"Odds of a Full House","value":{"result":{"probabilityPercent":0.14,"oddsOneInN":694,"waysToMake":3744,"probability":0.001441,"rank":4,"handType":"Full House","allHands":[{"handType":"Royal Flush","rank":1,"waysToMake":4,"probability":0.000002,"probabilityPercent":0,"oddsOneInN":649740},{"handType":"Straight Flush","rank":2,"waysToMake":36,"probability":0.000014,"probabilityPercent":0,"oddsOneInN":72193},{"handType":"Four of a Kind","rank":3,"waysToMake":624,"probability":0.00024,"probabilityPercent":0.02,"oddsOneInN":4165},{"handType":"Full House","rank":4,"waysToMake":3744,"probability":0.001441,"probabilityPercent":0.14,"oddsOneInN":694},{"handType":"Flush","rank":5,"waysToMake":5108,"probability":0.001965,"probabilityPercent":0.2,"oddsOneInN":509},{"handType":"Straight","rank":6,"waysToMake":10200,"probability":0.003925,"probabilityPercent":0.39,"oddsOneInN":255},{"handType":"Three of a Kind","rank":7,"waysToMake":54912,"probability":0.021128,"probabilityPercent":2.11,"oddsOneInN":47},{"handType":"Two Pair","rank":8,"waysToMake":123552,"probability":0.047539,"probabilityPercent":4.75,"oddsOneInN":21},{"handType":"One Pair","rank":9,"waysToMake":1098240,"probability":0.422569,"probabilityPercent":42.26,"oddsOneInN":2},{"handType":"High Card","rank":10,"waysToMake":1302540,"probability":0.501177,"probabilityPercent":50.12,"oddsOneInN":2}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/poker-hand-equity":{"get":{"summary":"Calculate Texas Hold'em hand equity given hole cards and known community cards.","tags":["Science & Stats"],"description":"Given two hole cards and 0–5 community cards, returns the probability of ending up with each poker hand type (Royal Flush through High Card), plus the best hand made so far once 5+ cards are known. Use this when a user wants to know their odds of making a given hand in Texas Hold'em, not just the fixed rarity of a 5-card deal. Uses full enumeration when 2 or more community cards are known (exact); Monte Carlo sampling of 100,000 runouts otherwise (pre-flop or flop-less-one). Example: \"What are my odds of a flush with Ace-King of hearts and a King-Queen-Ten of hearts on the flop?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"holeCards","required":true,"description":"Comma-separated pair of hole cards in rank+suit notation. Ranks: A K Q J T 9 8 7 6 5 4 3 2. Suits: s (spades) h (hearts) d (diamonds) c (clubs). Example: \"As,Kh\""},{"schema":{"type":"string"},"in":"query","name":"communityCards","required":false,"description":"Optional comma-separated community cards, 0–5, same notation as holeCards. Omit or leave empty for pre-flop. Example: \"Qs,Jc,Th\""}],"responses":{"200":{"description":"Probability of each hand type over all possible board completions, plus the current best hand.","content":{"application/json":{"schema":{"type":"object","description":"Probability of each hand type over all possible board completions, plus the current best hand.","properties":{"result":{"type":"object","properties":{"equity":{"type":"array","description":"All 10 hand types with their probability, strongest (Royal Flush) first.","items":{"type":"object","properties":{"handType":{"type":"string","description":"The hand type name."},"probability":{"type":"number","description":"Raw probability (0-1)."},"probabilityPercent":{"type":"number","description":"Probability as a percentage, rounded to 2dp."},"rank":{"type":"number","description":"Rarity rank, 1 = rarest (Royal Flush), 10 = most common (High Card)."}}}},"bestCurrentHand":{"type":["null","string"],"description":"The best 5-card hand already made from known cards, once 5 or more cards are known (hole + community); null otherwise."},"isComplete":{"type":"boolean","description":"True when all 5 community cards are known — the board is set and equity is a single exact outcome."},"method":{"type":"string","enum":["exact","monte-carlo"],"description":"Whether equity was computed by full enumeration (\"exact\") or Monte Carlo sampling (\"monte-carlo\")."},"samplesUsed":{"type":"number","description":"Total combinations enumerated (exact) or samples drawn (Monte Carlo)."}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/lifetime-event":{"get":{"summary":"Estimate the probability of experiencing 10 notable life events (car accident injury, house fire, lightning strike, winning a lottery prize, tax audit, twins, cancer diagnosis, reaching age 100, identity fraud, plane crash) over a lifetime and over the next 10 years.","tags":["Science & Stats"],"description":"Estimate the probability of experiencing 10 notable life events (car accident injury, house fire, lightning strike, winning a lottery prize, tax audit, twins, cancer diagnosis, reaching age 100, identity fraud, plane crash) over a lifetime and over the next 10 years. Use this when a user is curious how likely rare or notable life events are for someone their age. Returns probabilities using actuarial base rates, ranked from most to least likely. Example: \"What are the odds I'll experience a house fire or win the lottery in my lifetime, if I'm 30 and live in the US?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age (0-99). Example: 30"},{"schema":{"type":"string","enum":["US","UK"]},"in":"query","name":"country","required":true,"description":"Country whose base rates to use. Example: \"US\""}],"responses":{"200":{"description":"Estimated lifetime and next-10-year probabilities for 10 notable life events, ranked most to least likely.","content":{"application/json":{"schema":{"type":"object","description":"Estimated lifetime and next-10-year probabilities for 10 notable life events, ranked most to least likely.","properties":{"result":{"type":"object","description":"The lifetime-event result.","properties":{"country":{"type":"string","description":"Country whose base rates were used. Example: \"US\""},"currentAge":{"type":"number","description":"Current age used for the calculation. Example: 30"},"events":{"type":"array","description":"The 10 life events, ranked from most to least likely over a lifetime.","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier for the event. Example: \"house-fire\""},"label":{"type":"string","description":"Human-readable event label."},"lifetimeProbabilityPercent":{"type":"number","description":"Probability of experiencing the event over the remaining lifetime, as a percentage."},"oddsOneInN":{"type":"number","description":"Same lifetime probability expressed as 1-in-N odds."},"next10YearProbabilityPercent":{"type":"number","description":"Probability of experiencing the event within the next 10 years, as a percentage."},"source":{"type":"string","description":"Citation for the base rate used."}}}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"Age30US":{"summary":"30-year-old in the US","value":{"result":{"country":"US","currentAge":30,"events":[{"id":"lottery-prize","label":"Winning any lottery prize (if playing weekly)","lifetimeProbabilityPercent":100,"oddsOneInN":1,"next10YearProbabilityPercent":100,"source":"Powerball official overall odds of winning any prize (1 in 24.9 per ticket), assuming one ticket/week"},{"id":"identity-theft","label":"Falling victim to identity fraud","lifetimeProbabilityPercent":99.97,"oddsOneInN":1,"next10YearProbabilityPercent":83.08,"source":"Javelin Strategy & Research, 2022 Identity Fraud Study (42M US adults affected in 2021)"},{"id":"car-accident-injury","label":"Being injured in a car accident","lifetimeProbabilityPercent":28.57,"oddsOneInN":4,"next10YearProbabilityPercent":6.99,"source":"NHTSA Traffic Safety Facts (2.42M people injured in motor vehicle crashes, 2024)"},{"id":"cancer-diagnosis","label":"Being diagnosed with cancer","lifetimeProbabilityPercent":21.23,"oddsOneInN":5,"next10YearProbabilityPercent":5.01,"source":"American Cancer Society, lifetime risk of any cancer diagnosis (2021-2023 data, ~39.2%)"},{"id":"irs-audit","label":"Being audited by the tax authority","lifetimeProbabilityPercent":18.5,"oddsOneInN":5,"next10YearProbabilityPercent":4.31,"source":"IRS Data Book / GAO-22-104960 (individual return examination rate, ~0.44%/year)"},{"id":"house-fire","label":"Having a house fire","lifetimeProbabilityPercent":13.29,"oddsOneInN":8,"next10YearProbabilityPercent":3.03,"source":"NFPA, home structure fires (roughly 1 in 326 households per year, 2012-2016 average)"},{"id":"twins","label":"Having twins","lifetimeProbabilityPercent":3.01,"oddsOneInN":33,"next10YearProbabilityPercent":3.01,"source":"CDC NCHS, twin birth rate (30.1 per 1,000 births, 2024)"},{"id":"reaching-100","label":"Reaching age 100","lifetimeProbabilityPercent":2.41,"oddsOneInN":42,"next10YearProbabilityPercent":0.35,"source":"Social Security Administration cohort life tables (newborn, ~3.5%)"},{"id":"plane-crash-fatality","label":"Dying in a plane crash","lifetimeProbabilityPercent":0.01,"oddsOneInN":19509,"next10YearProbabilityPercent":0,"source":"National Safety Council, odds of dying (aviation accident, lifetime odds 1 in 11,756)"},{"id":"lightning-strike","label":"Being struck by lightning","lifetimeProbabilityPercent":0,"oddsOneInN":26337,"next10YearProbabilityPercent":0,"source":"National Weather Service (odds of being struck in a given year: 1 in 1,222,000)"}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/due-date":{"get":{"summary":"Estimate a pregnancy due date from the last menstrual period using Naegele's rule (LMP + 280 days).","tags":["Dates & Time"],"description":"Estimate a pregnancy due date from the last menstrual period using Naegele's rule (LMP + 280 days). Use this when a user asks when a baby is due, how far along a pregnancy is, or wants key pregnancy milestone dates. Returns the estimated due date, current week, trimester, days remaining, and key milestone dates. Estimates only — not medical advice. Example: \"If my last period started on 1 January 2026, when is my due date?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"lastMenstrualPeriod","required":true,"description":"Date of the last menstrual period, YYYY-MM-DD. Example: \"2026-01-01\""}],"responses":{"200":{"description":"The estimated due date, current week/trimester, days remaining, and key pregnancy milestone dates.","content":{"application/json":{"schema":{"type":"object","description":"The estimated due date, current week/trimester, days remaining, and key pregnancy milestone dates.","properties":{"result":{"type":"object","description":"The pregnancy timeline estimate.","properties":{"estimatedDueDate":{"type":"string","description":"Estimated due date, YYYY-MM-DD (LMP + 280 days). Example: \"2026-10-08\""},"currentWeek":{"type":"number","description":"Completed weeks of pregnancy as of today. Example: 31"},"currentDay":{"type":"number","description":"Extra days into the current week (0-6). Example: 2"},"trimester":{"type":"number","description":"Current trimester: 1, 2 or 3. Example: 3"},"daysRemaining":{"type":"number","description":"Days from today until the estimated due date. Example: 61"},"milestones":{"type":"array","description":"Key pregnancy milestone dates, from first heartbeat scan through post-term.","items":{"type":"object","properties":{"week":{"type":"number","description":"Pregnancy week the milestone falls in. Example: 8"},"date":{"type":"string","description":"Calendar date of the milestone, YYYY-MM-DD. Example: \"2026-02-26\""},"label":{"type":"string","description":"Milestone description. Example: \"First heartbeat scan\""}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"LmpJan2026":{"summary":"Due date estimate from a 1 January 2026 last menstrual period","value":{"result":{"estimatedDueDate":"2026-10-08","currentWeek":31,"currentDay":2,"trimester":3,"daysRemaining":61,"milestones":[{"week":8,"date":"2026-02-26","label":"First heartbeat scan"},{"week":12,"date":"2026-03-26","label":"Nuchal translucency scan"},{"week":20,"date":"2026-05-21","label":"Anomaly scan"},{"week":28,"date":"2026-07-16","label":"Third trimester begins"},{"week":37,"date":"2026-09-17","label":"Full term"},{"week":40,"date":"2026-10-08","label":"Due date"},{"week":42,"date":"2026-10-22","label":"Post-term"}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/bayes-theorem":{"get":{"summary":"Apply Bayes' theorem to find the posterior probability of a condition given a positive test result.","tags":["Science & Stats"],"description":"Apply Bayes' theorem to find the posterior probability of a condition given a positive test result. Use this when a user asks how likely a diagnosis, spam classification, or fraud flag really is after a positive test, given the test's known accuracy and how rare the condition is. Returns the posterior probability (PPV), NPV, and a 2x2 confusion matrix for a hypothetical 10,000-person population. Example: \"If a disease affects 1% of people and a test is 95% sensitive and 90% specific, how likely is a positive result to be a true positive?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"priorPercent","required":true,"description":"Prior probability as a percentage — e.g. prevalence of a condition in the population. Example: 1"},{"schema":{"type":"string"},"in":"query","name":"sensitivityPercent","required":true,"description":"Sensitivity as a percentage (true positive rate). Example: 95"},{"schema":{"type":"string"},"in":"query","name":"specificityPercent","required":true,"description":"Specificity as a percentage (true negative rate). Example: 90"}],"responses":{"200":{"description":"The posterior probability of the condition given a positive test, plus a hypothetical-population confusion matrix.","content":{"application/json":{"schema":{"type":"object","description":"The posterior probability of the condition given a positive test, plus a hypothetical-population confusion matrix.","properties":{"result":{"type":"object","description":"The Bayesian result.","properties":{"posteriorProbabilityPercent":{"type":"number","description":"Probability the condition is actually present, given a positive test (PPV). Example: 8.76"},"positivePredictiveValuePercent":{"type":"number","description":"Same value as posteriorProbabilityPercent, named for clarity. Example: 8.76"},"negativePredictiveValuePercent":{"type":"number","description":"Probability the condition is truly absent, given a negative test. Example: 99.94"},"confusionMatrix":{"type":"object","description":"Expected outcome counts for a hypothetical population of 10,000.","properties":{"truePositives":{"type":"number","description":"Expected true positives. Example: 95"},"falseNegatives":{"type":"number","description":"Expected false negatives. Example: 5"},"falsePositives":{"type":"number","description":"Expected false positives. Example: 990"},"trueNegatives":{"type":"number","description":"Expected true negatives. Example: 8910"},"population":{"type":"number","description":"Size of the hypothetical population. Example: 10000"}}},"interpretation":{"type":"string","description":"Plain-English summary of the posterior probability."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"DiseaseTest":{"summary":"1% prior, 95% sensitivity, 90% specificity","value":{"result":{"posteriorProbabilityPercent":8.76,"positivePredictiveValuePercent":8.76,"negativePredictiveValuePercent":99.94,"confusionMatrix":{"truePositives":95,"falseNegatives":5,"falsePositives":990,"trueNegatives":8910,"population":10000},"interpretation":"If you test positive, there's a 8.76% chance you actually have the condition."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/force-mass-acceleration":{"get":{"summary":"Apply Newton's second law (F = ma) to solve for whichever of force, mass, or acceleration is missing.","tags":["Science & Stats"],"description":"Apply Newton's second law (F = ma) to solve for whichever of force, mass, or acceleration is missing. Use this when a user has two of the three quantities and wants the third. Provide exactly two of force, mass, and acceleration. Example: \"What force is needed to accelerate a 10kg mass at 5 m/s²?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"force","required":false,"description":"Force in newtons (N) — omit to solve for this. Example: 50"},{"schema":{"type":"string"},"in":"query","name":"mass","required":false,"description":"Mass in kilograms (kg) — omit to solve for this. Example: 10"},{"schema":{"type":"string"},"in":"query","name":"acceleration","required":false,"description":"Acceleration in m/s² — omit to solve for this. Example: 5"}],"responses":{"200":{"description":"The solved-for quantity from Newton's second law (F = ma), plus the other two known values and a worked example.","content":{"application/json":{"schema":{"type":"object","description":"The solved-for quantity from Newton's second law (F = ma), plus the other two known values and a worked example.","properties":{"result":{"type":"object","description":"The force/mass/acceleration result.","properties":{"force":{"type":"number","description":"Force in newtons (N). Example: 50"},"mass":{"type":"number","description":"Mass in kilograms (kg). Example: 10"},"acceleration":{"type":"number","description":"Acceleration in m/s². Example: 5"},"solvedFor":{"type":"string","description":"Which variable was solved for. Example: \"force\""},"formula":{"type":"string","description":"The formula used. Example: \"F = m × a\""},"workedExample":{"type":"string","description":"A worked-example string showing the substituted formula."},"realWorldContext":{"type":"string","description":"A relatable real-world comparison for the resulting force."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"SolveForForce":{"summary":"10kg mass at 5 m/s² — solve for force","value":{"result":{"force":50,"mass":10,"acceleration":5,"solvedFor":"force","formula":"F = m × a","workedExample":"F = m × a = 10 kg × 5 m/s² = 50 N","realWorldContext":"That's equivalent to the force needed to accelerate a 70kg person at 0.71 m/s²."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ohms-law":{"get":{"summary":"Apply Ohm's law (V = IR) to solve for whichever of voltage, current, or resistance is missing.","tags":["Science & Stats"],"description":"Apply Ohm's law (V = IR) to solve for whichever of voltage, current, or resistance is missing. Use this when a user has two of the three electrical quantities and wants the third, plus power dissipated. Provide exactly two of voltage, current, and resistance. Example: \"What is the current if a circuit has 12 volts and 4 ohms of resistance?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"voltage","required":false,"description":"Voltage in volts (V) — omit to solve for this. Example: 12"},{"schema":{"type":"string"},"in":"query","name":"current","required":false,"description":"Current in amps (A) — omit to solve for this. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"resistance","required":false,"description":"Resistance in ohms (Ω) — omit to solve for this. Example: 4"}],"responses":{"200":{"description":"The solved-for quantity from Ohm's law, plus the other two known values and power dissipated.","content":{"application/json":{"schema":{"type":"object","description":"The solved-for quantity from Ohm's law, plus the other two known values and power dissipated.","properties":{"result":{"type":"object","description":"The Ohm's law result.","properties":{"voltage":{"type":"number","description":"Voltage in volts (V). Example: 12"},"current":{"type":"number","description":"Current in amps (A). Example: 3"},"resistance":{"type":"number","description":"Resistance in ohms (Ω). Example: 4"},"power":{"type":"number","description":"Power dissipated, in watts (W). Example: 36"},"solvedFor":{"type":"string","description":"Which variable was solved for. Example: \"current\""},"formula":{"type":"string","description":"The formula used to solve for the missing variable. Example: \"I = V / R\""},"relationships":{"type":"array","description":"All four Ohm's law / power relationships, for reference.","items":{"type":"string"}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"VoltageAndResistance":{"summary":"12V, 4Ω known — solve for current","value":{"result":{"voltage":12,"current":3,"resistance":4,"power":36,"solvedFor":"current","formula":"I = V / R","relationships":["V = I × R","I = V / R","R = V / I","P = I × V"]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/electrical-power":{"get":{"summary":"Calculate electrical power (P = IV = I²R = V²/R) from any known pair of voltage, current, and resistance.","tags":["Science & Stats"],"description":"Calculate electrical power (P = IV = I²R = V²/R) from any known pair of voltage, current, and resistance. Use this when a user knows two electrical quantities for a circuit and wants power (and the missing third quantity). Returns power plus all four variables. Example: \"What is the power if a circuit has 12 volts and 2 amps?\"","parameters":[{"schema":{"type":"string","enum":["VI","VR","IR"]},"in":"query","name":"knownPair","required":true,"description":"Which pair of variables is known. Example: \"VI\""},{"schema":{"type":"string"},"in":"query","name":"voltage","required":false,"description":"Voltage in volts (V) — required for \"VI\" and \"VR\". Example: 12"},{"schema":{"type":"string"},"in":"query","name":"current","required":false,"description":"Current in amps (A) — required for \"VI\" and \"IR\". Example: 2"},{"schema":{"type":"string"},"in":"query","name":"resistance","required":false,"description":"Resistance in ohms (Ω) — required for \"VR\" and \"IR\". Example: 6"}],"responses":{"200":{"description":"Electrical power computed from the known pair of variables, plus all four quantities.","content":{"application/json":{"schema":{"type":"object","description":"Electrical power computed from the known pair of variables, plus all four quantities.","properties":{"result":{"type":"object","description":"The electrical power result.","properties":{"power":{"type":"number","description":"Power in watts (W). Example: 24"},"voltage":{"type":"number","description":"Voltage in volts (V). Example: 12"},"current":{"type":"number","description":"Current in amps (A). Example: 2"},"resistance":{"type":"number","description":"Resistance in ohms (Ω). Example: 6"},"formula":{"type":"string","description":"The formula used to compute power. Example: \"P = I × V\""}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"VoltageAndCurrent":{"summary":"12V, 2A known — solve for power and resistance","value":{"result":{"power":24,"voltage":12,"current":2,"resistance":6,"formula":"P = I × V"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/projectile-motion":{"get":{"summary":"Calculate projectile motion (idealized, no air resistance).","tags":["Science & Stats"],"description":"Calculate projectile motion (idealized, no air resistance). Use this when a user wants the range, height, or flight time of a launched object — a classic physics problem. Returns maximum range, maximum height, time of flight, and velocity components, plus a sampled trajectory curve. Example: \"How far does a projectile travel if launched at 20 m/s at a 45 degree angle?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"initialVelocity","required":true,"description":"Launch speed in m/s. Example: 20"},{"schema":{"type":"string"},"in":"query","name":"launchAngle","required":true,"description":"Launch angle in degrees, 0-90. Example: 45"},{"schema":{"type":"string"},"in":"query","name":"initialHeight","required":false,"description":"Launch height in metres, defaults to 0. Example: 0"}],"responses":{"200":{"description":"Range, height, flight time, and velocity components for an idealized projectile, plus a sampled trajectory curve.","content":{"application/json":{"schema":{"type":"object","description":"Range, height, flight time, and velocity components for an idealized projectile, plus a sampled trajectory curve.","properties":{"result":{"type":"object","description":"The projectile motion result.","properties":{"maxRange":{"type":"number","description":"Horizontal distance travelled, in metres. Example: 40.77"},"maxHeight":{"type":"number","description":"Maximum height reached, in metres. Example: 10.19"},"timeOfFlight":{"type":"number","description":"Total flight time, in seconds. Example: 2.88"},"horizontalVelocity":{"type":"number","description":"Horizontal velocity component, in m/s. Example: 14.14"},"verticalVelocity":{"type":"number","description":"Initial vertical velocity component, in m/s. Example: 14.14"},"trajectory":{"type":"array","description":"41 sampled (x, y) points along the flight path, in metres.","items":{"type":"object","properties":{"x":{"type":"number","description":"Horizontal distance at this sample point, in metres."},"y":{"type":"number","description":"Height at this sample point, in metres."}}}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"Launch20msAt45deg":{"summary":"Launched at 20 m/s at a 45 degree angle","value":{"result":{"maxRange":40.77,"maxHeight":10.19,"timeOfFlight":2.88,"horizontalVelocity":14.14,"verticalVelocity":14.14,"trajectory":[{"x":0,"y":0},{"x":1.02,"y":0.99},{"x":2.04,"y":1.94},{"x":3.06,"y":2.83},{"x":4.08,"y":3.67},{"x":5.1,"y":4.46},{"x":6.12,"y":5.2},{"x":7.14,"y":5.89},{"x":8.15,"y":6.52},{"x":9.17,"y":7.11},{"x":10.19,"y":7.65},{"x":11.21,"y":8.13},{"x":12.23,"y":8.56},{"x":13.25,"y":8.94},{"x":14.27,"y":9.28},{"x":15.29,"y":9.56},{"x":16.31,"y":9.79},{"x":17.33,"y":9.96},{"x":18.35,"y":10.09},{"x":19.37,"y":10.17},{"x":20.39,"y":10.19},{"x":21.41,"y":10.17},{"x":22.43,"y":10.09},{"x":23.45,"y":9.96},{"x":24.46,"y":9.79},{"x":25.48,"y":9.56},{"x":26.5,"y":9.28},{"x":27.52,"y":8.94},{"x":28.54,"y":8.56},{"x":29.56,"y":8.13},{"x":30.58,"y":7.65},{"x":31.6,"y":7.11},{"x":32.62,"y":6.52},{"x":33.64,"y":5.89},{"x":34.66,"y":5.2},{"x":35.68,"y":4.46},{"x":36.7,"y":3.67},{"x":37.72,"y":2.83},{"x":38.74,"y":1.94},{"x":39.76,"y":0.99},{"x":40.77,"y":0}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/home-electricity":{"post":{"summary":"Estimate home electricity consumption and cost from a list of appliances.","tags":["Global"],"description":"Estimate home electricity consumption and cost from a list of appliances. Use this when a user wants to know what their appliances cost to run, or wants to compare usage scenarios. Returns daily/monthly/annual kWh and cost, plus a per-appliance breakdown. Known appliance ids (with default wattage): fridge (150W), washingMachine (2000W), dishwasher (1800W), tv (100W), desktopPc (300W), laptop (65W), evCharger (7400W), electricOven (2200W), microwave (1000W), kettle (3000W), lighting (10W). Unknown ids are accepted if a watts value is provided. Example: \"What does it cost to run a fridge and 3 hours of TV a day at 0.28 per kWh?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appliances":{"type":"array","description":"List of appliances in use. Example: [{\"id\": \"fridge\", \"hoursPerDay\": 24}, {\"id\": \"tv\", \"hoursPerDay\": 3}]","items":{"type":"object","properties":{"id":{"type":"string","description":"Appliance id — a known id, or any custom string if watts is provided. Example: \"fridge\""},"watts":{"type":"number","description":"Wattage override; required for unknown ids. Example: 150"},"quantity":{"type":"number","description":"Number of units (e.g. rooms for lighting), defaults to 1. Example: 1"},"hoursPerDay":{"type":"number","description":"Hours per day this appliance runs (0-24). Example: 24"}},"required":["id","hoursPerDay"]}},"tariff":{"type":"number","description":"Price per kWh in your local currency's main unit, e.g. 0.28 for 28p/kWh. Example: 0.28"}},"required":["appliances","tariff"]}}}},"responses":{"200":{"description":"Daily/monthly/annual electricity consumption and cost, with a per-appliance breakdown sorted by highest annual usage first.","content":{"application/json":{"schema":{"type":"object","description":"Daily/monthly/annual electricity consumption and cost, with a per-appliance breakdown sorted by highest annual usage first.","properties":{"result":{"type":"object","description":"The home electricity result.","properties":{"dailyKwh":{"type":"number","description":"Total daily consumption in kWh. Example: 3.9"},"monthlyKwh":{"type":"number","description":"Total monthly consumption in kWh. Example: 117"},"annualKwh":{"type":"number","description":"Total annual consumption in kWh. Example: 1423.5"},"dailyCost":{"type":"number","description":"Total daily cost at the given tariff. Example: 1.09"},"monthlyCost":{"type":"number","description":"Total monthly cost at the given tariff. Example: 32.76"},"annualCost":{"type":"number","description":"Total annual cost at the given tariff. Example: 398.58"},"highestConsumptionAppliance":{"type":"string","description":"Label of the appliance with the highest annual consumption. Null if appliances was empty. Example: \"Fridge\""},"breakdown":{"type":"array","description":"Per-appliance consumption and cost, sorted by highest annual kWh first.","items":{"type":"object","properties":{"id":{"type":"string","description":"Appliance id as given in the request. Example: \"fridge\""},"label":{"type":"string","description":"Human-readable appliance label. Example: \"Fridge\""},"watts":{"type":"number","description":"Wattage used for this appliance (given or default). Example: 150"},"quantity":{"type":"number","description":"Number of units. Example: 1"},"hoursPerDay":{"type":"number","description":"Hours per day this appliance runs. Example: 24"},"dailyKwh":{"type":"number","description":"Daily consumption in kWh for this appliance. Example: 3.6"},"monthlyKwh":{"type":"number","description":"Monthly consumption in kWh for this appliance. Example: 108"},"annualKwh":{"type":"number","description":"Annual consumption in kWh for this appliance. Example: 1314"},"dailyCost":{"type":"number","description":"Daily cost for this appliance. Example: 1.01"},"monthlyCost":{"type":"number","description":"Monthly cost for this appliance. Example: 30.24"},"annualCost":{"type":"number","description":"Annual cost for this appliance. Example: 367.92"}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}},"examples":{"FridgeAndTv":{"summary":"Cost to run a fridge and 3 hours of TV a day at 0.28 per kWh","value":{"result":{"dailyKwh":3.9,"monthlyKwh":117,"annualKwh":1423.5,"dailyCost":1.09,"monthlyCost":32.76,"annualCost":398.58,"highestConsumptionAppliance":"Fridge","breakdown":[{"id":"fridge","label":"Fridge","watts":150,"quantity":1,"hoursPerDay":24,"dailyKwh":3.6,"monthlyKwh":108,"annualKwh":1314,"dailyCost":1.01,"monthlyCost":30.24,"annualCost":367.92},{"id":"tv","label":"TV","watts":100,"quantity":1,"hoursPerDay":3,"dailyKwh":0.3,"monthlyKwh":9,"annualKwh":109.5,"dailyCost":0.08,"monthlyCost":2.52,"annualCost":30.66}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/solar-savings":{"get":{"summary":"Estimate solar panel generation and savings from roof area and country.","tags":["Global"],"description":"Estimate solar panel generation and savings from roof area and country. Use this when a user is considering installing solar panels and wants to know potential savings and payback period. Returns annual generation, bill saving, export earnings, and simple payback period. Example: \"What would 30 m² of solar panels save on a $1,500 annual electricity bill in the UK?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"roofArea","required":true,"description":"Available roof area in m². Example: 30"},{"schema":{"type":"string","enum":["GB","DE","FR","ES","US","AU","IT","PT","GR","NL","BE","IE","SE","NO","DK","PL","CH","AT","CA","MX","BR","IN","CN","JP","KR","AE","SA","ZA","EG","MA"]},"in":"query","name":"countryCode","required":true,"description":"ISO country code — determines average daily peak sun hours. Example: \"GB\""},{"schema":{"type":"string"},"in":"query","name":"panelEfficiency","required":false,"description":"Panel efficiency as a percentage, defaults to 20. Example: 20"},{"schema":{"type":"string"},"in":"query","name":"currentAnnualBill","required":true,"description":"Current annual electricity bill. Example: 1500"},{"schema":{"type":"string"},"in":"query","name":"exportTariff","required":false,"description":"Price per kWh for exported excess generation, defaults to 0.15. Example: 0.15"},{"schema":{"type":"string"},"in":"query","name":"importTariff","required":false,"description":"Price per kWh used to value self-consumed generation, defaults to 0.28. Example: 0.28"}],"responses":{"200":{"description":"Estimated solar panel generation, bill saving, export earnings, and simple payback period.","content":{"application/json":{"schema":{"type":"object","description":"Estimated solar panel generation, bill saving, export earnings, and simple payback period.","properties":{"result":{"type":"object","description":"The solar savings result.","properties":{"annualGenerationKwh":{"type":"number","description":"Estimated annual generation in kWh. Example: 6132"},"estimatedBillSaving":{"type":"number","description":"Estimated annual saving on the electricity bill from self-consumed generation. Example: 858.48"},"estimatedExportEarnings":{"type":"number","description":"Estimated annual earnings from exporting excess generation. Example: 459.9"},"totalAnnualBenefit":{"type":"number","description":"estimatedBillSaving plus estimatedExportEarnings. Example: 1318.38"},"paybackYears":{"type":"number","description":"Simple payback period in years for the installed cost. Null if there's no annual benefit. Example: 5.46"},"systemSizeKwp":{"type":"number","description":"Estimated system size in kWp. Example: 6"},"installedCost":{"type":"number","description":"Estimated installed cost of the system. Example: 7200"},"country":{"type":"string","description":"Full country name for countryCode. Example: \"United Kingdom\""},"sunHoursPerDay":{"type":"number","description":"Average daily peak sun hours used for this country. Example: 2.8"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}},"examples":{"30sqmUK":{"summary":"30 m² of solar panels on a $1,500 annual electricity bill in the UK","value":{"result":{"annualGenerationKwh":6132,"estimatedBillSaving":858.48,"estimatedExportEarnings":459.9,"totalAnnualBenefit":1318.38,"paybackYears":5.46,"systemSizeKwp":6,"installedCost":7200,"country":"United Kingdom","sunHoursPerDay":2.8},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ev-vs-petrol":{"get":{"summary":"Compare annual and 5-year running costs of an EV vs a petrol/diesel car.","tags":["Global"],"description":"Compare annual and 5-year running costs of an EV vs a petrol/diesel car. Use this when a user is deciding whether an EV is worth the extra upfront cost, given their driving habits. Returns fuel cost, annual saving, break-even year for the EV purchase premium, and CO2 saved per year. Example: \"Is an EV worth it if I drive 12,000 miles a year and the EV costs $5,000 more upfront?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"annualDistance","required":true,"description":"Annual distance driven. Example: 12000"},{"schema":{"type":"string","enum":["miles","km"]},"in":"query","name":"distanceUnit","required":false,"description":"Unit for annualDistance, defaults to \"miles\". Example: \"miles\""},{"schema":{"type":"string"},"in":"query","name":"petrolPricePerLitre","required":false,"description":"Petrol/diesel price per litre, defaults to 1.45. Example: 1.45"},{"schema":{"type":"string"},"in":"query","name":"electricityPricePerKwh","required":false,"description":"Electricity price per kWh, defaults to 0.28. Example: 0.28"},{"schema":{"type":"string"},"in":"query","name":"petrolMpg","required":false,"description":"Petrol car fuel efficiency in mpg (imperial gallon), defaults to 40. Example: 40"},{"schema":{"type":"string"},"in":"query","name":"evMilesPerKwh","required":false,"description":"EV efficiency in miles per kWh, defaults to 3.5. Example: 3.5"},{"schema":{"type":"string"},"in":"query","name":"evPurchasePremium","required":false,"description":"EV purchase premium over an equivalent petrol car, defaults to 5000. Example: 5000"},{"schema":{"type":"string"},"in":"query","name":"gridIntensity","required":false,"description":"Grid carbon intensity in gCO2/kWh, defaults to 233 (UK average). Example: 233"}],"responses":{"200":{"description":"Annual and 5-year running cost comparison between an EV and a petrol/diesel car, with break-even year and CO2 saved.","content":{"application/json":{"schema":{"type":"object","description":"Annual and 5-year running cost comparison between an EV and a petrol/diesel car, with break-even year and CO2 saved.","properties":{"result":{"type":"object","description":"The EV vs petrol comparison result.","properties":{"annualSaving":{"type":"number","description":"Annual fuel cost saving from driving the EV instead of petrol. Example: 1017.55"},"petrolAnnualCost":{"type":"number","description":"Annual fuel cost for the petrol/diesel car. Example: 1977.55"},"evAnnualCost":{"type":"number","description":"Annual electricity cost for the EV. Example: 960"},"petrol5YearCost":{"type":"number","description":"Total 5-year fuel cost for the petrol/diesel car. Example: 9887.75"},"ev5YearCost":{"type":"number","description":"Total 5-year cost for the EV, including the purchase premium. Example: 9800"},"breakEvenYear":{"type":"number","description":"Years until the EV purchase premium is paid back by fuel savings. Null if the EV never saves money. Example: 4.91"},"co2SavedPerYear":{"type":"number","description":"kg CO2 saved per year by driving the EV instead of petrol. Example: 2351.58"},"annualDistanceMiles":{"type":"number","description":"annualDistance normalized to miles. Example: 12000"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}},"examples":{"12000MilesPerYear":{"summary":"EV vs petrol for 12,000 miles/year with a $5,000 EV premium","value":{"result":{"annualSaving":1017.55,"petrolAnnualCost":1977.55,"evAnnualCost":960,"petrol5YearCost":9887.75,"ev5YearCost":9800,"breakEvenYear":4.91,"co2SavedPerYear":2351.58,"annualDistanceMiles":12000},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/generator-size":{"post":{"summary":"Recommend a generator size from a list of appliances to power, accounting for motor starting surge and a 20% safety margin.","tags":["Global"],"description":"Recommend a generator size from a list of appliances to power, accounting for motor starting surge and a 20% safety margin. Use this when a user is buying a generator (for home backup or a job site) and wants to know what wattage covers their appliance list. Returns the recommended generator size in watts. Known appliance ids (starting/running watts): fridge (1200W start / 150W run), airConditioner (4800W start / 1500W run), sumpPump (2100W start / 800W run), wellPump (3000W start / 1000W run), microwave (1000W start / 1000W run), lights (60W start / 60W run), tv (300W start / 300W run), electricHeater (1500W start / 1500W run). Example: \"What size generator do I need to run a fridge and a sump pump?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appliances":{"type":"array","description":"List of appliances to power. Example: [{\"id\": \"fridge\", \"quantity\": 1}, {\"id\": \"sumpPump\", \"quantity\": 1}]","items":{"type":"object","properties":{"id":{"type":"string","enum":["fridge","airConditioner","sumpPump","wellPump","microwave","lights","tv","electricHeater"],"description":"Appliance id from the known list above."},"quantity":{"type":"number","description":"Number of units, defaults to 1. Example: 1"}},"required":["id"]}}},"required":["appliances"]}}}},"responses":{"200":{"description":"A recommended generator size in watts, covering peak starting surge plus a 20% safety margin.","content":{"application/json":{"schema":{"type":"object","description":"A recommended generator size in watts, covering peak starting surge plus a 20% safety margin.","properties":{"result":{"type":"object","description":"The generator sizing result.","properties":{"recommendedGeneratorWatts":{"type":"number","description":"Recommended generator size in watts, including the 20% safety margin. Example: 2700"},"totalStartingWatts":{"type":"number","description":"Peak starting watts across the appliance list (worst-case single motor start on top of all other appliances running). Example: 2250"},"totalRunningWatts":{"type":"number","description":"Combined steady-state running watts of all appliances. Example: 950"},"tier":{"type":"string","description":"Recommended generator tier. Example: \"portable\"","enum":["portable","mid-range","standby"]},"tierDescription":{"type":"string","description":"Human-readable description of the recommended tier."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}},"examples":{"FridgeAndSumpPump":{"summary":"Generator size for a fridge and a sump pump","value":{"result":{"recommendedGeneratorWatts":2700,"totalStartingWatts":2250,"totalRunningWatts":950,"tier":"portable","tierDescription":"A portable generator (up to ~5,000W) should cover this load."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/paint-coverage":{"get":{"summary":"Calculate paint needed for a room.","tags":["Science & Stats"],"description":"Calculate paint needed for a room. Use this when a user is planning to paint a room and wants to know how much paint to buy and what it will cost. Returns paintable wall area (excluding doors/windows), litres needed, tins to buy at standard sizes, and estimated cost. Example: \"How much paint do I need for a 4m x 5m room with 2.4m ceilings?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"roomLength","required":true,"description":"Room length in metres. Example: 4"},{"schema":{"type":"string"},"in":"query","name":"roomWidth","required":true,"description":"Room width in metres. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"roomHeight","required":true,"description":"Room height in metres. Example: 2.4"},{"schema":{"type":"string"},"in":"query","name":"coats","required":false,"description":"Number of coats, defaults to 2. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"doors","required":false,"description":"Number of doors to exclude, defaults to 1. Example: 1"},{"schema":{"type":"string"},"in":"query","name":"windows","required":false,"description":"Number of windows to exclude, defaults to 2. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"pricePerLitre","required":false,"description":"Price per litre of paint, defaults to 4. Example: 4"}],"responses":{"200":{"description":"Paint needed for a room, with tin sizes to buy and estimated cost.","content":{"application/json":{"schema":{"type":"object","description":"Paint needed for a room, with tin sizes to buy and estimated cost.","properties":{"result":{"type":"object","description":"The paint coverage result.","properties":{"paintableArea":{"type":"number","description":"Wall area after excluding doors/windows, in m². Example: 38.6"},"litresNeeded":{"type":"number","description":"Litres of paint needed for all coats. Example: 6.43"},"tins":{"type":"array","description":"Tins to buy, by size.","items":{"type":"object","properties":{"size":{"type":"number","description":"Tin size in litres."},"quantity":{"type":"number","description":"Number of tins of this size."}}}},"totalTins":{"type":"number","description":"Total number of tins to buy. Example: 1"},"totalLitresPurchased":{"type":"number","description":"Total litres purchased across all tins. Example: 10"},"estimatedCost":{"type":"number","description":"Estimated total cost. Example: 40"},"wallArea":{"type":"number","description":"Total wall area before excluding doors/windows, in m². Example: 43.2"}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"Room4x5Height2_4":{"summary":"4m x 5m room, 2.4m ceilings, default coats/doors/windows","value":{"result":{"paintableArea":38.6,"litresNeeded":6.43,"tins":[{"size":10,"quantity":1}],"totalTins":1,"totalLitresPurchased":10,"estimatedCost":40,"wallArea":43.2},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/flooring-tiling":{"get":{"summary":"Calculate flooring or tiling materials needed for a room.","tags":["Science & Stats"],"description":"Calculate flooring or tiling materials needed for a room. Use this when a user is planning a flooring or tiling project and wants to know how many tiles/boards to buy and what it will cost. Returns room area, area with waste allowance, units (tiles/boards) needed, and total cost. Example: \"How many tiles do I need for a 4m x 5m room using 0.3m x 0.3m tiles?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"roomLength","required":true,"description":"Room length in metres. Example: 4"},{"schema":{"type":"string"},"in":"query","name":"roomWidth","required":true,"description":"Room width in metres. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"unitLength","required":true,"description":"Tile or board length in metres. Example: 0.3"},{"schema":{"type":"string"},"in":"query","name":"unitWidth","required":true,"description":"Tile or board width in metres. Example: 0.3"},{"schema":{"type":"string"},"in":"query","name":"wastePercent","required":false,"description":"Waste allowance as a percentage, defaults to 10. Example: 10"},{"schema":{"type":"string"},"in":"query","name":"costPerM2","required":false,"description":"Cost per square metre, defaults to 25. Example: 25"}],"responses":{"200":{"description":"Flooring/tiling materials needed for a room, including waste allowance and cost.","content":{"application/json":{"schema":{"type":"object","description":"Flooring/tiling materials needed for a room, including waste allowance and cost.","properties":{"result":{"type":"object","description":"The flooring/tiling result.","properties":{"roomArea":{"type":"number","description":"Room area in m². Example: 20"},"areaWithWaste":{"type":"number","description":"Room area including the waste allowance, in m². Example: 22"},"unitsNeeded":{"type":"number","description":"Number of tiles/boards needed. Example: 245"},"totalCost":{"type":"number","description":"Total estimated cost. Example: 550"},"costPerM2":{"type":"number","description":"Cost per square metre used. Example: 25"}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"Room4x5Tile0_3":{"summary":"4m x 5m room, 0.3m x 0.3m tiles","value":{"result":{"roomArea":20,"areaWithWaste":22,"unitsNeeded":245,"totalCost":550,"costPerM2":25},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/concrete-volume":{"get":{"summary":"Calculate the concrete volume needed for a slab, column, or footing.","tags":["Science & Stats"],"description":"Calculate the concrete volume needed for a slab, column, or footing. Use this when a user is planning a concrete pour and wants to know how much material and cement to order, and what it might cost. Returns volume in m³, bags of cement needed (25kg bags, 1:2:3 mix), and estimated ready-mix cost. Example: \"How much concrete do I need for a 5m x 4m slab that's 0.15m deep?\"","parameters":[{"schema":{"type":"string","enum":["slab","column","footing"]},"in":"query","name":"shape","required":true,"description":"Shape of the concrete pour. Example: \"slab\""},{"schema":{"type":"string"},"in":"query","name":"length","required":false,"description":"Length in metres — required for slab/footing. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"width","required":false,"description":"Width in metres — required for slab/footing. Example: 4"},{"schema":{"type":"string"},"in":"query","name":"depth","required":false,"description":"Depth in metres — required for slab/footing. Example: 0.15"},{"schema":{"type":"string"},"in":"query","name":"diameter","required":false,"description":"Diameter in metres — required for column. Example: 0.4"},{"schema":{"type":"string"},"in":"query","name":"height","required":false,"description":"Height in metres — required for column. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"readyMixCostPerM3","required":false,"description":"Ready-mix concrete cost per m³, defaults to 120. Example: 120"}],"responses":{"200":{"description":"The concrete volume needed, along with cement bags and estimated ready-mix cost.","content":{"application/json":{"schema":{"type":"object","description":"The concrete volume needed, along with cement bags and estimated ready-mix cost.","properties":{"result":{"type":"object","description":"The concrete volume result.","properties":{"volume":{"type":"number","description":"Concrete volume in m³. Example: 3"},"bagsOfCement":{"type":"number","description":"25kg bags of cement needed, 1:2:3 mix ratio. Example: 21"},"estimatedReadyMixCost":{"type":"number","description":"Estimated cost of ready-mix concrete. Example: 360"},"shape":{"type":"string","description":"The shape that was calculated. Example: \"slab\""}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when the result was computed."}}}}},"examples":{"Slab5x4x0_15":{"summary":"5m x 4m slab, 0.15m deep","value":{"result":{"volume":3,"bagsOfCement":21,"estimatedReadyMixCost":360,"shape":"slab"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/calorie-burn":{"get":{"summary":"Estimate calories burned during a physical activity using published MET values.","tags":["Health & Life"],"description":"Estimate calories burned during a physical activity using published MET values. Use this when a user wants to know how many calories a workout or activity burned, or wants to translate that into food/drink equivalents. Returns kcal burned, plus equivalents in common food/drink items and minutes of walking. Example: \"How many calories does 45 minutes of running burn for someone who weighs 75kg?\"","parameters":[{"schema":{"type":"string","enum":["running","cycling","swimming","walking","hiit","weightlifting","yoga","rowing","football","tennis","hiking"]},"in":"query","name":"activity","required":true,"description":"Activity type — see the enum for supported values. Example: \"running\""},{"schema":{"type":"string"},"in":"query","name":"durationMinutes","required":true,"description":"Duration of the activity in minutes. Example: 45"},{"schema":{"type":"string"},"in":"query","name":"bodyWeightKg","required":true,"description":"Body weight in kilograms. Example: 75"}],"responses":{"200":{"description":"Calories burned during the activity, plus common food/drink and walking equivalents.","content":{"application/json":{"schema":{"type":"object","description":"Calories burned during the activity, plus common food/drink and walking equivalents.","properties":{"result":{"type":"object","description":"The calorie burn estimate.","properties":{"kcalBurned":{"type":"number","description":"Kilocalories burned. Example: 551.25"},"marsBarsEquivalent":{"type":"number","description":"Equivalent number of Mars bars (230 kcal each). Example: 2.4"},"pizzaSlicesEquivalent":{"type":"number","description":"Equivalent number of pizza slices (285 kcal each). Example: 1.93"},"beersEquivalent":{"type":"number","description":"Equivalent number of pints of beer (215 kcal each). Example: 2.56"},"walkMinutesEquivalent":{"type":"number","description":"Minutes of walking that would burn the same calories. Example: 126"},"thirtyMinuteWalksEquivalent":{"type":"number","description":"Number of 30-minute walks that would burn the same calories. Example: 4.2"},"met":{"type":"number","description":"Metabolic Equivalent of Task value used for the activity. Example: 9.8"}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FortyFiveMinRunning75kg":{"summary":"45 minutes of running, 75kg body weight","value":{"result":{"kcalBurned":551.25,"marsBarsEquivalent":2.4,"pizzaSlicesEquivalent":1.93,"beersEquivalent":2.56,"walkMinutesEquivalent":126,"thirtyMinuteWalksEquivalent":4.2,"met":9.8},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/bmi":{"get":{"summary":"Calculate BMI, healthy weight range, BMR and daily calorie needs (TDEE).","tags":["Health & Life"],"description":"Calculate Body Mass Index with WHO category, the healthy weight range for the given height, Basal Metabolic Rate (Mifflin-St Jeor equation), and Total Daily Energy Expenditure across 5 activity levels. Use this when a user wants to know their BMI, a healthy weight target, or daily calorie needs. Screening tool only, not diagnostic. Example: \"What's my BMI and daily calorie needs — I'm a 35-year-old man, 180cm, 80kg, moderately active?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"weightKg","required":true,"description":"Body weight in kilograms. Example: 80"},{"schema":{"type":"string"},"in":"query","name":"heightCm","required":true,"description":"Height in centimeters. Example: 180"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex, used for the Mifflin-St Jeor BMR formula. Example: \"M\""},{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years. Example: 35"},{"schema":{"type":"string","enum":["sedentary","light","moderate","active","very-active"]},"in":"query","name":"activityLevel","required":false,"description":"Activity level, used for the TDEE table (all 5 levels are always returned regardless of this value). Defaults to \"sedentary\". Example: \"moderate\""}],"responses":{"200":{"description":"BMI, WHO category, healthy weight range, BMR, and TDEE across all 5 activity levels.","content":{"application/json":{"schema":{"type":"object","description":"BMI, WHO category, healthy weight range, BMR, and TDEE across all 5 activity levels.","properties":{"result":{"type":"object","description":"The BMI and energy-needs result.","properties":{"bmi":{"type":"number","description":"Body Mass Index. Example: 24.7"},"category":{"type":"string","description":"WHO BMI category key. Example: \"normal\"","enum":["underweight","normal","overweight","obese-1","obese-2","obese-3"]},"categoryLabel":{"type":"string","description":"Human-readable category label. Example: \"Healthy weight\""},"weightDeltaKg":{"type":"number","description":"kg to lose (negative) or gain (positive) to enter the healthy BMI range; 0 if already in it. Example: 0"},"healthyMinKg":{"type":"number","description":"Lower bound of the healthy weight range for this height, in kg. Example: 59.9"},"healthyMaxKg":{"type":"number","description":"Upper bound of the healthy weight range for this height, in kg. Example: 80.7"},"bmr":{"type":"number","description":"Basal Metabolic Rate via Mifflin-St Jeor, kcal/day. Example: 1755"},"tdee":{"type":"array","description":"Total Daily Energy Expenditure at each of the 5 activity levels.","items":{"type":"object","properties":{"level":{"type":"string","description":"Activity level key. Example: \"moderate\"","enum":["sedentary","light","moderate","active","very-active"]},"label":{"type":"string","description":"Human-readable activity level label."},"tdee":{"type":"number","description":"Total Daily Energy Expenditure at this activity level, kcal/day."}}}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"EightyKgOneEightyCm":{"summary":"35-year-old man, 80kg, 180cm, moderately active","value":{"result":{"bmi":24.7,"category":"normal","categoryLabel":"Healthy weight","weightDeltaKg":0,"healthyMinKg":59.9,"healthyMaxKg":80.7,"bmr":1755,"tdee":[{"level":"sedentary","label":"Sedentary (desk job, little or no exercise)","tdee":2106},{"level":"light","label":"Lightly active (1–3 days/week)","tdee":2413},{"level":"moderate","label":"Moderately active (3–5 days/week)","tdee":2720},{"level":"active","label":"Very active (6–7 days/week)","tdee":3027},{"level":"very-active","label":"Extra active (physical job + daily training)","tdee":3335}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/unit-converter":{"get":{"summary":"Convert a value between two units within a measurement category.","tags":["Science & Stats"],"description":"Convert a value between any two units within a category. Covers 12 categories: length, mass, volume, temperature, area, speed, pressure, energy, power, data storage, time, and fuel economy. Use this when a user asks to convert a measurement — e.g. miles to kilometres, Fahrenheit to Celsius, gallons to litres, or megabytes to gigabytes. Returns the converted value with full unit names and symbols. Example: \"Convert 5 miles to kilometres\" or \"What is 100°F in Celsius?\"","parameters":[{"schema":{"type":"string","enum":["length","mass","volume","temperature","area","speed","pressure","energy","power","data","time","fuel-economy"]},"in":"query","name":"category","required":true,"description":"The measurement category. Example: \"length\""},{"schema":{"type":"string"},"in":"query","name":"from","required":true,"description":"Unit key to convert from. Example: \"mi\""},{"schema":{"type":"string"},"in":"query","name":"to","required":true,"description":"Unit key to convert to. Example: \"km\""},{"schema":{"type":"string"},"in":"query","name":"value","required":true,"description":"The numeric value to convert. Example: 5"}],"responses":{"200":{"description":"The converted value between two units, with full unit names and symbols for both sides of the conversion.","content":{"application/json":{"schema":{"type":"object","description":"The converted value between two units, with full unit names and symbols for both sides of the conversion.","properties":{"result":{"type":"number","description":"The converted value. Example: 3.28084"},"from":{"type":"object","description":"The unit converted from.","properties":{"unit":{"type":"string","description":"Unit key. Example: \"m\""},"symbol":{"type":"string","description":"Display symbol. Example: \"m\""},"name":{"type":"string","description":"Full unit name. Example: \"Metre\""}}},"to":{"type":"object","description":"The unit converted to.","properties":{"unit":{"type":"string","description":"Unit key. Example: \"ft\""},"symbol":{"type":"string","description":"Display symbol. Example: \"ft\""},"name":{"type":"string","description":"Full unit name. Example: \"Foot\""}}},"category":{"type":"string","description":"The human-readable category name. Example: \"Length\""}}},"examples":{"MetresToFeet":{"summary":"Convert 1 metre to feet","value":{"result":3.28084,"from":{"unit":"m","symbol":"m","name":"Metre"},"to":{"unit":"ft","symbol":"ft","name":"Foot"},"category":"Length"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/safe-withdrawal-rate":{"get":{"summary":"Calculate a safe withdrawal rate via Monte Carlo simulation.","tags":["Finance"],"description":"Calculate a safe withdrawal rate via Monte Carlo simulation. Use this when someone wants to know if their retirement spending is sustainable, or what spending rate gives a high probability their portfolio survives. Returns the current withdrawal rate, the probability of success across simulated market scenarios, the maximum withdrawal rate achieving at least 95% success, and a year-by-year p10/p50/p90 portfolio value chart. Example: \"Is a $1,000,000 portfolio safe to withdraw $40,000/year from for 30 years with a 60% stock allocation?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"portfolioValue","required":true,"description":"Total portfolio value in dollars. Example: 1000000"},{"schema":{"type":"string"},"in":"query","name":"annualSpend","required":true,"description":"Annual withdrawal amount in dollars. Example: 40000"},{"schema":{"type":"string"},"in":"query","name":"retirementYears","required":true,"description":"Duration of retirement in years, 10-60. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"stockAllocationPct","required":true,"description":"Percentage of portfolio in stocks, 0-100; rest in bonds. Example: 60"},{"schema":{"type":"string"},"in":"query","name":"inflationRatePct","required":false,"description":"Annual inflation rate as a percentage, defaults to 3.0. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"simulationCount","required":false,"description":"Number of Monte Carlo simulations to run, defaults to 1000. Example: 1000"}],"responses":{"200":{"description":"The safe withdrawal rate analysis, including success probability and a year-by-year percentile chart.","content":{"application/json":{"schema":{"type":"object","description":"The safe withdrawal rate analysis, including success probability and a year-by-year percentile chart.","properties":{"result":{"type":"object","properties":{"currentWithdrawalRate":{"type":"number","description":"Annual spend as a percentage of portfolio value. Example: 4"},"successProbability":{"type":"number","description":"Percentage of simulations where the portfolio was not depleted by the end. Example: 92.3"},"safeWithdrawalRate":{"type":"number","description":"Maximum withdrawal rate achieving at least 95% success, to 2dp. Example: 3.45"},"safeAnnualSpend":{"type":"number","description":"Dollar amount corresponding to safeWithdrawalRate. Example: 34500"},"medianPortfolioAtEnd":{"type":"number","description":"Median simulated portfolio value at the end of the horizon. Example: 850000"},"yearOfDepletionP10":{"type":["null","number"],"description":"First year the 10th-percentile portfolio value reaches zero, null if it never does. Example: 22"},"chartData":{"type":"array","description":"Portfolio value percentiles at 5-year intervals.","items":{"type":"object","properties":{"year":{"type":"number"},"p10":{"type":"number"},"p50":{"type":"number"},"p90":{"type":"number"}}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/monte-carlo-retirement":{"get":{"summary":"Simulate retirement portfolio growth with Monte Carlo scenarios.","tags":["Finance"],"description":"Simulate retirement portfolio growth with Monte Carlo scenarios. Use this when someone wants to see the range of possible outcomes for their savings and contributions between now and retirement, not just a single average projection. Returns p10/p50/p90 portfolio values at retirement, probability of exceeding $500K/$1M/$2M, total contributions vs investment growth, and a year-by-year chart. Example: \"If I'm 30 with $50,000 saved, contributing $1,000/month, retiring at 65 with 80% stocks, what's my likely portfolio range?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age, 18-70. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"retirementAge","required":true,"description":"Target retirement age, greater than currentAge, up to 80. Example: 65"},{"schema":{"type":"string"},"in":"query","name":"currentSavings","required":true,"description":"Amount already saved, in dollars. Example: 50000"},{"schema":{"type":"string"},"in":"query","name":"monthlyContribution","required":true,"description":"Amount added per month, in dollars. Example: 1000"},{"schema":{"type":"string"},"in":"query","name":"stockAllocationPct","required":true,"description":"Percentage of portfolio in stocks, 0-100; rest in bonds. Example: 80"},{"schema":{"type":"string"},"in":"query","name":"inflationRatePct","required":false,"description":"Annual inflation rate as a percentage, defaults to 3.0. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"simulationCount","required":false,"description":"Number of Monte Carlo simulations to run, defaults to 1000. Example: 1000"}],"responses":{"200":{"description":"Simulated retirement portfolio outcomes, including percentile projections and milestone probabilities.","content":{"application/json":{"schema":{"type":"object","description":"Simulated retirement portfolio outcomes, including percentile projections and milestone probabilities.","properties":{"result":{"type":"object","properties":{"yearsToRetirement":{"type":"number","description":"Years between currentAge and retirementAge. Example: 35"},"p10AtRetirement":{"type":"number","description":"10th percentile simulated portfolio value at retirement. Example: 850000"},"p50AtRetirement":{"type":"number","description":"Median simulated portfolio value at retirement. Example: 1450000"},"p90AtRetirement":{"type":"number","description":"90th percentile simulated portfolio value at retirement. Example: 2400000"},"probabilityAbove500k":{"type":"number","description":"Percentage of simulations ending above $500,000. Example: 96.4"},"probabilityAbove1m":{"type":"number","description":"Percentage of simulations ending above $1,000,000. Example: 71.2"},"probabilityAbove2m":{"type":"number","description":"Percentage of simulations ending above $2,000,000. Example: 22.5"},"totalContributions":{"type":"number","description":"Total contributed over the accumulation period. Example: 420000"},"medianInvestmentGrowth":{"type":"number","description":"Median simulated portfolio minus starting savings and total contributions. Example: 980000"},"chartData":{"type":"array","description":"Portfolio value percentiles for every age from currentAge to retirementAge.","items":{"type":"object","properties":{"age":{"type":"number"},"p10":{"type":"number"},"p50":{"type":"number"},"p90":{"type":"number"}}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/tax-loss-harvesting":{"post":{"summary":"Calculate tax savings from harvesting investment losses.","tags":["Finance"],"description":"Calculate tax savings from harvesting investment losses. Use this when someone wants to know which positions to sell for a tax loss, how much tax they would save, how much of the IRS $3,000 ordinary income offset they can use, and how much loss carries forward to next year. Example: \"I have a position down $5,000 held long-term and one up $2,000 held short-term — what should I harvest, and what does it save me at a 32% ordinary rate and 15% long-term rate?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"positions":{"type":"array","description":"The investment positions to evaluate, 1-20 items. Example: [{\"name\":\"ACME Corp\",\"currentValue\":8000,\"costBasis\":13000,\"holdingPeriod\":\"long\"}]","items":{"type":"object","properties":{"name":{"type":"string","description":"Label for this position. Example: \"ACME Corp\""},"currentValue":{"type":"number","description":"Current market value in dollars. Example: 8000"},"costBasis":{"type":"number","description":"Original purchase price in dollars. Example: 13000"},"holdingPeriod":{"type":"string","enum":["short","long"],"description":"\"short\" if held under 1 year, \"long\" otherwise. Example: \"long\""}},"required":["name","currentValue","costBasis","holdingPeriod"]}},"ordinaryIncomeTaxRatePct":{"type":"number","description":"Combined federal + state marginal ordinary income tax rate, 0-50. Example: 32"},"longTermCapGainsRatePct":{"type":"number","description":"Long-term capital gains tax rate: 0, 15, or 20. Example: 15"},"capitalGainsCarryforward":{"type":"number","description":"Existing loss carryforward from prior years, in dollars, defaults to 0. Example: 0"},"capitalGainsIncomeThisYear":{"type":"number","description":"Realised capital gains from elsewhere this year, in dollars, defaults to 0. Example: 0"}},"required":["positions","ordinaryIncomeTaxRatePct","longTermCapGainsRatePct"]}}}},"responses":{"200":{"description":"Per-position harvest recommendations and the resulting tax savings.","content":{"application/json":{"schema":{"type":"object","description":"Per-position harvest recommendations and the resulting tax savings.","properties":{"result":{"type":"object","properties":{"positions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"gainLoss":{"type":"number","description":"Negative means a loss. Example: -5000"},"taxIfSold":{"type":"number","description":"Negative means tax saved, positive means tax owed. Example: -750"},"holdingPeriod":{"type":"string","enum":["short","long"]},"recommendation":{"type":"string","enum":["harvest","hold","review"]}}}},"totalUnrealisedLosses":{"type":"number","description":"Sum of losses across all loss positions. Example: 5000"},"totalUnrealisedGains":{"type":"number","description":"Sum of gains across all gain positions. Example: 2000"},"taxSavingFromHarvesting":{"type":"number","description":"Total tax saved by harvesting all loss positions. Example: 750"},"gainsOffsetByLosses":{"type":"number","description":"Amount of this-year gains neutralised by harvested losses. Example: 0"},"ordinaryIncomeOffset":{"type":"number","description":"Loss applied against ordinary income, capped at the $3,000 IRS annual limit. Example: 3000"},"ordinaryIncomeTaxSaving":{"type":"number","description":"Tax saved from the ordinary income offset. Example: 960"},"newCarryforward":{"type":"number","description":"Losses not used this year, carried to future years. Example: 2000"},"netTaxSavingThisYear":{"type":"number","description":"Total tax saving realised this year. Example: 960"},"washSaleWarning":{"type":"string"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/social-security-break-even":{"get":{"summary":"Find the Social Security claiming age break-even points.","tags":["Finance"],"description":"Find the Social Security claiming age break-even points. Use this when someone wants to know at what age delaying Social Security to 67 or 70 pays off compared to claiming at 62, based on their estimated monthly benefit at each age. Returns break-even ages between each pair of claiming strategies, lifetime totals to a given life expectancy, and the optimal claim age. Example: \"My estimated benefit is $1,800/month at 62, $2,600 at 67, and $3,300 at 70 — when does waiting pay off?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"monthlyBenefitAt62","required":true,"description":"Estimated monthly benefit if claimed at age 62. Example: 1800"},{"schema":{"type":"string"},"in":"query","name":"monthlyBenefitAt67","required":true,"description":"Estimated monthly benefit if claimed at full retirement age (67). Example: 2600"},{"schema":{"type":"string"},"in":"query","name":"monthlyBenefitAt70","required":true,"description":"Estimated monthly benefit if claimed at 70. Example: 3300"},{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age, 40-70. Example: 55"},{"schema":{"type":"string"},"in":"query","name":"lifeExpectancyAge","required":false,"description":"Assumed life expectancy age, 65-100, defaults to 85. Example: 85"}],"responses":{"200":{"description":"Break-even ages between claiming strategies, lifetime totals, and the optimal claim age.","content":{"application/json":{"schema":{"type":"object","description":"Break-even ages between claiming strategies, lifetime totals, and the optimal claim age.","properties":{"result":{"type":"object","properties":{"breakEvenAge_62vs67":{"type":["null","number"],"description":"Age at which claiming at 67 overtakes claiming at 62 cumulatively. Example: 78"},"breakEvenAge_62vs70":{"type":["null","number"],"description":"Age at which claiming at 70 overtakes claiming at 62 cumulatively. Example: 80"},"breakEvenAge_67vs70":{"type":["null","number"],"description":"Age at which claiming at 70 overtakes claiming at 67 cumulatively. Example: 82"},"lifetimeTotal62":{"type":"number","description":"Total benefits received by lifeExpectancyAge if claimed at 62. Example: 496800"},"lifetimeTotal67":{"type":"number","description":"Total benefits received by lifeExpectancyAge if claimed at 67. Example: 561600"},"lifetimeTotal70":{"type":"number","description":"Total benefits received by lifeExpectancyAge if claimed at 70. Example: 594000"},"optimalClaim":{"type":"string","enum":["62","67","70"],"description":"The claim age with the highest lifetime total. Example: \"70\""},"monthlyDifference_67vs62":{"type":"number","description":"Extra monthly benefit from waiting to 67 instead of 62. Example: 800"},"monthlyDifference_70vs67":{"type":"number","description":"Extra monthly benefit from waiting to 70 instead of 67. Example: 700"},"chartData":{"type":"array","description":"Cumulative benefits received under each claiming strategy, by age.","items":{"type":"object","properties":{"age":{"type":"number"},"cumulative62":{"type":"number"},"cumulative67":{"type":"number"},"cumulative70":{"type":"number"}}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/portfolio-rebalancing":{"post":{"summary":"Calculate trades needed to rebalance a portfolio to target allocations.","tags":["Finance"],"description":"Calculate trades needed to rebalance a portfolio to target allocations. Use this when someone wants to know exactly how much to buy or sell of each asset class to restore their target allocation, optionally deploying new cash. Example: \"My portfolio is 70% US stocks, 20% international, 10% bonds by value but I target 60/25/15 — what trades bring it back in line, and I also have $5,000 new cash to invest?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assets":{"type":"array","description":"The portfolio assets, 2-10 items. targetPct values must sum to 100. Example: [{\"asset\":\"US Stocks\",\"targetPct\":60,\"currentValue\":70000},{\"asset\":\"International\",\"targetPct\":25,\"currentValue\":20000},{\"asset\":\"Bonds\",\"targetPct\":15,\"currentValue\":10000}]","items":{"type":"object","properties":{"asset":{"type":"string","description":"Asset class label. Example: \"US Stocks\""},"targetPct":{"type":"number","description":"Target allocation percentage for this asset. Example: 60"},"currentValue":{"type":"number","description":"Current market value of this asset in dollars. Example: 70000"}},"required":["asset","targetPct","currentValue"]}},"cashToInvest":{"type":"number","description":"Additional cash to deploy alongside the rebalance, in dollars, defaults to 0. Example: 5000"},"driftThresholdPct":{"type":"number","description":"Percentage-point drift from target that flags an asset as needing rebalancing, defaults to 5. Example: 5"}},"required":["assets"]}}}},"responses":{"200":{"description":"Per-asset trade recommendations to restore the target allocation.","content":{"application/json":{"schema":{"type":"object","description":"Per-asset trade recommendations to restore the target allocation.","properties":{"result":{"type":"object","properties":{"totalPortfolioValue":{"type":"number","description":"Sum of current asset values, excluding new cash. Example: 100000"},"totalWithCash":{"type":"number","description":"Total portfolio value including cashToInvest. Example: 105000"},"trades":{"type":"array","items":{"type":"object","properties":{"asset":{"type":"string"},"currentValue":{"type":"number"},"currentPct":{"type":"number"},"targetPct":{"type":"number"},"driftPct":{"type":"number"},"action":{"type":"string","enum":["buy","sell","hold"]},"tradeAmount":{"type":"number","description":"Dollar amount to trade; positive means buy, negative means sell."},"targetValue":{"type":"number"},"absDrift":{"type":"number"},"outsideThreshold":{"type":"boolean"}}}},"rebalanceRequired":{"type":"boolean","description":"True if any asset is outside the drift threshold. Example: true"},"totalBuys":{"type":"number","description":"Sum of all positive trade amounts. Example: 8500"},"totalSells":{"type":"number","description":"Sum of all negative trade amounts, as a positive number. Example: 3500"},"largestDrift":{"type":"object","properties":{"asset":{"type":"string"},"driftPct":{"type":"number"}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/kelly-criterion":{"get":{"summary":"Calculate optimal position size using the Kelly Criterion.","tags":["Finance"],"description":"Calculate optimal position size using the Kelly Criterion. Use this when someone wants to know what fraction of their bankroll to bet or invest given a known win probability and payout, including the conservative half-Kelly recommendation. Example: \"If I win 55% of the time at 2:1 odds, what fraction of my bankroll should I bet?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"winProbabilityPct","required":true,"description":"Probability of winning, 0-100. Example: 55"},{"schema":{"type":"string"},"in":"query","name":"winMultiple","required":true,"description":"Dollars returned per dollar wagered on a win, e.g. 2.0 for 2:1 odds. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"lossMultiple","required":false,"description":"Dollars lost per dollar wagered on a loss, defaults to 1.0. Example: 1"},{"schema":{"type":"string"},"in":"query","name":"bankroll","required":false,"description":"Total capital in dollars; when provided, enables dollar-amount outputs. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"fractionMultiplier","required":false,"description":"Fraction of full Kelly to use for the custom output, 0.1-1.0, defaults to 0.5. Example: 0.5"}],"responses":{"200":{"description":"Optimal bet sizing fractions and expected value under the Kelly Criterion.","content":{"application/json":{"schema":{"type":"object","description":"Optimal bet sizing fractions and expected value under the Kelly Criterion.","properties":{"result":{"type":"object","properties":{"fullKellyFraction":{"type":"number","description":"Optimal fraction of bankroll per the Kelly formula. Example: 0.1"},"halfKellyFraction":{"type":"number","description":"Full Kelly fraction halved; the commonly recommended, less volatile sizing. Example: 0.05"},"customFraction":{"type":"number","description":"Full Kelly fraction scaled by fractionMultiplier. Example: 0.05"},"expectedLogGrowthPerBet":{"type":"number","description":"Expected geometric growth rate per bet at full Kelly. Example: 0.0025"},"breakEvenWinProbabilityPct":{"type":"number","description":"Minimum win probability for positive expected value. Example: 33.33"},"expectedValuePerBet":{"type":"number","description":"Expected value per dollar wagered; positive means +EV. Example: 0.65"},"dollarBetFull":{"type":["null","number"],"description":"Dollar bet at full Kelly, if bankroll was provided. Example: 1000"},"dollarBetHalf":{"type":["null","number"],"description":"Dollar bet at half Kelly, if bankroll was provided. Example: 500"},"dollarBetCustom":{"type":["null","number"],"description":"Dollar bet at the custom fraction, if bankroll was provided. Example: 500"},"recommendation":{"type":"string","description":"Human-readable sizing recommendation. Example: \"Half-Kelly: bet 5% of bankroll\""},"isPositiveEV":{"type":"boolean"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/diabetes-risk":{"get":{"summary":"Calculate the FINDRISC 10-year type 2 diabetes risk score.","tags":["Health & Life"],"description":"Calculate the FINDRISC 10-year type 2 diabetes risk score. Use this when someone wants a validated, WHO-adopted screening estimate of their probability of developing type 2 diabetes over the next 10 years, from simple self-reported measurements. Returns the FINDRISC score (0-26), a risk level, an estimated 10-year probability, and a per-item breakdown. Example: \"What is my diabetes risk if I am 50, BMI 29, waist 98cm, not very active, don't eat vegetables daily, on BP medication, no history of high blood glucose, and my mother had diabetes?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years. Example: 50"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex, used for the waist-circumference thresholds. Example: \"M\""},{"schema":{"type":"string"},"in":"query","name":"bmi","required":true,"description":"Body mass index in kg/m². Example: 29"},{"schema":{"type":"string"},"in":"query","name":"waistCircumferenceCm","required":true,"description":"Waist circumference in cm, measured at navel level. Example: 98"},{"schema":{"type":"string"},"in":"query","name":"physicallyActive","required":true,"description":"Whether you get at least 30 minutes of moderate activity daily. Example: false"},{"schema":{"type":"string"},"in":"query","name":"eatsVegetablesFruitsDailyOrMore","required":true,"description":"Whether you eat vegetables or fruit daily. Example: false"},{"schema":{"type":"string"},"in":"query","name":"onBloodPressureMedication","required":true,"description":"Whether you take blood pressure medication. Example: true"},{"schema":{"type":"string"},"in":"query","name":"historyOfHighBloodGlucose","required":true,"description":"Whether you were ever told your blood glucose was elevated, including gestational diabetes. Example: false"},{"schema":{"type":"string","enum":["none","distant","close"]},"in":"query","name":"familyHistoryDiabetes","required":true,"description":"\"close\" = parent/sibling/child, \"distant\" = grandparent/aunt/uncle/cousin. Example: \"close\""}],"responses":{"200":{"description":"FINDRISC score, risk level, estimated 10-year probability, and a per-item breakdown.","content":{"application/json":{"schema":{"type":"object","description":"FINDRISC score, risk level, estimated 10-year probability, and a per-item breakdown.","properties":{"result":{"type":"object","properties":{"score":{"type":"number","description":"FINDRISC integer score, 0-26. Example: 15"},"riskLevel":{"type":"string","enum":["low","slightly-elevated","moderate","high","very-high"],"description":"Example: \"high\""},"tenYearProbabilityPct":{"type":"number","description":"Validated approximate 10-year type 2 diabetes probability, as a percentage. Example: 33"},"interpretation":{"type":"string","description":"Plain-language summary of the result."},"breakdown":{"type":"array","description":"Per-item score contribution.","items":{"type":"object","properties":{"item":{"type":"string"},"score":{"type":"number"},"detail":{"type":"string"}}}},"recommendation":{"type":"string","description":"Suggested next step based on the risk level."}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/dementia-risk":{"get":{"summary":"Calculate the LIBRA dementia risk index across 12 modifiable lifestyle factors.","tags":["Health & Life"],"description":"Calculate the LIBRA (LIfestyle for BRAin health) dementia risk index across 12 modifiable lifestyle factors. Use this when someone wants to see how their lifestyle and health conditions affect dementia risk, and which changes would help most. Returns the LIBRA score, a risk category, an approximate percentile vs the population average, the top risk and protective factors, and a full factor breakdown. Every factor is modifiable. Example: \"I have hypertension and am physically inactive but eat a Mediterranean diet and stay socially engaged — what is my LIBRA dementia risk score?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"highBloodPressure","required":true,"description":"Diagnosed hypertension. Example: true"},{"schema":{"type":"string"},"in":"query","name":"obesity","required":true,"description":"BMI ≥ 30. Example: false"},{"schema":{"type":"string"},"in":"query","name":"depression","required":true,"description":"Diagnosed or treated depression. Example: false"},{"schema":{"type":"string"},"in":"query","name":"diabetes","required":true,"description":"Type 1 or Type 2 diabetes. Example: false"},{"schema":{"type":"string"},"in":"query","name":"highCholesterol","required":true,"description":"Untreated high cholesterol. Example: false"},{"schema":{"type":"string"},"in":"query","name":"heartDisease","required":true,"description":"Coronary artery disease / CHD. Example: false"},{"schema":{"type":"string"},"in":"query","name":"kidneyDisease","required":true,"description":"Chronic kidney disease / eGFR <60. Example: false"},{"schema":{"type":"string"},"in":"query","name":"smoking","required":true,"description":"Current smoker. Example: false"},{"schema":{"type":"string"},"in":"query","name":"physicalInactivity","required":true,"description":"No regular moderate activity. Example: true"},{"schema":{"type":"string"},"in":"query","name":"mediterraneanDietLow","required":true,"description":"Does NOT follow a Mediterranean-style diet. Example: false"},{"schema":{"type":"string"},"in":"query","name":"socialIsolation","required":true,"description":"Limited social engagement. Example: false"},{"schema":{"type":"string"},"in":"query","name":"lowCognitiveActivity","required":true,"description":"No mentally stimulating work or hobbies. Example: false"}],"responses":{"200":{"description":"LIBRA dementia risk score, category, and factor breakdown.","content":{"application/json":{"schema":{"type":"object","description":"LIBRA dementia risk score, category, and factor breakdown.","properties":{"result":{"type":"object","properties":{"libraScore":{"type":"number","description":"Sum of factor contributions, roughly -5.9 to +12.7. Example: 2.4"},"riskCategory":{"type":"string","enum":["low","moderate","elevated","high"]},"percentileVsAverage":{"type":"number","description":"Approximate percentile vs a population mean of 2.0. Example: 62"},"topRiskFactors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"weight":{"type":"number"},"present":{"type":"boolean"},"contribution":{"type":"number"}}}},"topProtectiveFactors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"weight":{"type":"number"},"present":{"type":"boolean"},"contribution":{"type":"number"}}}},"allFactors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"weight":{"type":"number"},"present":{"type":"boolean"},"contribution":{"type":"number"}}}},"modifiableScore":{"type":"number","description":"Same as libraScore — all 12 factors are modifiable."},"recommendation":{"type":"string"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/body-composition":{"get":{"summary":"Calculate body fat percentage, fat mass, and lean mass using the Deurenberg and US Navy methods.","tags":["Health & Life"],"description":"Calculate body fat percentage, fat mass, and lean mass using the Deurenberg (BMI-based) and US Navy (circumference-based) methods. Use this when someone wants a body composition estimate beyond BMI alone. Returns BMI, one or two body fat estimates depending on which measurements are supplied, and the preferred primary estimate. Example: \"What is my body fat percentage if I am a 35-year-old man, 180cm, 85kg, with a 90cm waist and 38cm neck?\"","parameters":[{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex. Example: \"M\""},{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years, 18-80. Example: 35"},{"schema":{"type":"string"},"in":"query","name":"heightCm","required":true,"description":"Height in cm. Example: 180"},{"schema":{"type":"string"},"in":"query","name":"weightKg","required":true,"description":"Weight in kg. Example: 85"},{"schema":{"type":"string"},"in":"query","name":"waistCm","required":false,"description":"Waist circumference in cm, horizontal at navel. Required for the US Navy method. Example: 90"},{"schema":{"type":"string"},"in":"query","name":"neckCm","required":false,"description":"Neck circumference in cm, below the larynx. Required for the US Navy method. Example: 38"},{"schema":{"type":"string"},"in":"query","name":"hipCm","required":false,"description":"Hip circumference in cm at the widest point. Required for women using the US Navy method. Example: 100"},{"schema":{"type":"string","enum":["deurenberg","us-navy","both"]},"in":"query","name":"method","required":false,"description":"Which method(s) to compute. Defaults to \"both\" if waist/neck (and hip for women) are provided, else \"deurenberg\". Example: \"both\""}],"responses":{"200":{"description":"BMI plus one or two body composition estimates.","content":{"application/json":{"schema":{"type":"object","description":"BMI plus one or two body composition estimates.","properties":{"result":{"type":"object","properties":{"bmi":{"type":"number","description":"Body mass index. Example: 26.2"},"estimates":{"type":"array","description":"One estimate per requested method.","items":{"type":"object","properties":{"method":{"type":"string"},"bodyFatPct":{"type":"number"},"fatMassKg":{"type":"number"},"leanMassKg":{"type":"number"},"category":{"type":"string"}}}},"primaryEstimate":{"type":"object","description":"The preferred estimate — US Navy if available, else Deurenberg.","properties":{"method":{"type":"string"},"bodyFatPct":{"type":"number"},"fatMassKg":{"type":"number"},"leanMassKg":{"type":"number"},"category":{"type":"string"}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/roas-calculator":{"get":{"summary":"Calculate ROAS, break-even ROAS, and profit from ad spend.","tags":["Business Finance"],"description":"Calculate return on ad spend (ROAS), break-even ROAS, and net profit from advertising. Use this when someone wants to know whether their ad spend is actually profitable, not just what revenue it generated. Returns ROAS, gross profit, net profit from ads, break-even ROAS, margin on ad spend, a profitability verdict, and an optional benchmark comparison against Google/Meta/TikTok/LinkedIn industry medians. Example: \"I spent $10,000 on Google Ads and made $35,000 in attributed revenue at a 60% gross margin — am I profitable?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"adSpend","required":true,"description":"Total ad spend in the period, in dollars. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"revenueFromAds","required":true,"description":"Total revenue attributed to those ads, in dollars. Example: 35000"},{"schema":{"type":"string"},"in":"query","name":"grossMarginPct","required":false,"description":"Gross margin as a percentage, 1-99, defaults to 50. Ignored if cogsAmount is provided. Example: 60"},{"schema":{"type":"string"},"in":"query","name":"cogsAmount","required":false,"description":"Cost of goods sold for the attributed revenue, in dollars — alternative to grossMarginPct. Example: 14000"},{"schema":{"type":"string","enum":["google","meta","tiktok","linkedin","other"]},"in":"query","name":"platform","required":false,"description":"Ad platform, for benchmark comparison. Example: \"google\""}],"responses":{"200":{"description":"ROAS, profitability, and an optional platform benchmark comparison.","content":{"application/json":{"schema":{"type":"object","description":"ROAS, profitability, and an optional platform benchmark comparison.","properties":{"result":{"type":"object","properties":{"roas":{"type":"number","description":"Revenue from ads divided by ad spend. Example: 3.5"},"grossProfit":{"type":"number","description":"Revenue from ads times gross margin %. Example: 21000"},"netProfitFromAds":{"type":"number","description":"Gross profit minus ad spend. Example: 11000"},"breakEvenRoas":{"type":"number","description":"Minimum ROAS to cover cost of goods: 100 / grossMarginPct. Example: 1.67"},"marginOnAdSpend":{"type":"number","description":"Net profit from ads as a percentage of ad spend (MoAS). Example: 110"},"profitability":{"type":"string","enum":["profitable","break-even","loss-making"]},"benchmark":{"type":["null","object"],"properties":{"platform":{"type":"string"},"medianRoas":{"type":"number"},"topQuartileRoas":{"type":"number"},"vsMedian":{"type":"number"},"percentile":{"type":"string","enum":["top-quartile","above-median","below-median"]}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/startup-survival":{"get":{"summary":"Estimate startup survival probability by industry, using BLS Business Employment Dynamics data.","tags":["Business Finance"],"description":"Estimate startup survival probability by industry sector, adjusted for funding status, business model, and traction signals. Use this when someone wants to know what fraction of businesses in their sector survive to Year 1, 3, 5, or 10 — a probability model based on real BLS cohort data, distinct from a cash-runway calculation. Returns baseline and adjusted survival rates, a forward-looking curve from Year 0 to 10, the modifiers applied, a key insight, and conditional survival (given years already survived). Example: \"What is the 5-year survival probability for a seed-funded SaaS startup with paying customers?\"","parameters":[{"schema":{"type":"string","enum":["agriculture","mining","construction","manufacturing","wholesale","retail","transportation","information","finance","real-estate","professional-services","healthcare","accommodation-food","saas-software","other"]},"in":"query","name":"industry","required":true,"description":"Industry sector. Example: \"saas-software\""},{"schema":{"type":"string"},"in":"query","name":"yearsAlreadyOperating","required":true,"description":"Years already operating, 0-9 (0 = not yet started / Year 0). Example: 0"},{"schema":{"type":"string","enum":["b2b","b2c","marketplace","saas","ecommerce","services"]},"in":"query","name":"businessModel","required":false,"description":"Optional — improves the estimate. Example: \"saas\""},{"schema":{"type":"string","enum":["bootstrapped","angel","seed","series-a-plus"]},"in":"query","name":"fundingStatus","required":false,"description":"Optional — improves the estimate. Example: \"seed\""},{"schema":{"type":"string"},"in":"query","name":"hasProductMarketFit","required":false,"description":"Optional, self-assessed. Example: true"},{"schema":{"type":"string"},"in":"query","name":"hasPayingCustomers","required":false,"description":"Optional — at least 1 paying customer. Example: true"}],"responses":{"200":{"description":"Baseline and adjusted survival probabilities, a forward-looking curve, and applied modifiers.","content":{"application/json":{"schema":{"type":"object","description":"Baseline and adjusted survival probabilities, a forward-looking curve, and applied modifiers.","properties":{"result":{"type":"object","properties":{"industryLabel":{"type":"string"},"baselineSurvival":{"type":"object","properties":{"yr1":{"type":"number"},"yr2":{"type":"number"},"yr3":{"type":"number"},"yr5":{"type":"number"},"yr10":{"type":"number"}}},"adjustedSurvival":{"type":"object","properties":{"yr1":{"type":"number"},"yr2":{"type":"number"},"yr3":{"type":"number"},"yr5":{"type":"number"},"yr10":{"type":"number"}}},"yearsAlreadyOperating":{"type":"number"},"forwardLook":{"type":"array","description":"Baseline vs adjusted survival, Year 0 through Year 10.","items":{"type":"object","properties":{"year":{"type":"number"},"baselinePct":{"type":"number"},"adjustedPct":{"type":"number"}}}},"modifiers":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"impact":{"type":"number"},"description":{"type":"string"}}}},"keyInsight":{"type":"string"},"conditionalSurvival":{"type":"object","description":"P(survive to year N | already survived to yearsAlreadyOperating). Null where N is not after yearsAlreadyOperating.","properties":{"yr1":{"type":["null","number"]},"yr2":{"type":["null","number"]},"yr3":{"type":["null","number"]},"yr5":{"type":["null","number"]},"yr10":{"type":["null","number"]}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/bls-bed-survival":{"get":{"summary":"BLS Business Employment Dynamics establishment survival rates by NAICS sector and cohort year.","tags":["Business Finance"],"description":"Returns real BLS BED establishment survival rates (year 1–5) for each 2-digit NAICS sector and opening-year cohort (1994–2024). Filter by NAICS code and/or cohort year. Use format=csv to download as a spreadsheet. NULLs indicate cohorts too recent to have a full 5-year window. Source: BLS Business Employment Dynamics, refreshed annually each November.","parameters":[{"schema":{"type":"string"},"in":"query","name":"naics","required":false,"description":"2-digit NAICS sector code (e.g. \"72\" for Accommodation & Food Services). Omit to return all sectors."},{"schema":{"type":"string"},"in":"query","name":"cohort_year","required":false,"description":"Opening-year cohort (1994–2024). Omit to return all years."},{"schema":{"type":"string","enum":["json","csv"]},"in":"query","name":"format","required":false,"description":"Response format. Default: json."}],"responses":{"200":{"description":"BLS BED survival rates. Each row is one NAICS × cohort-year combination.","content":{"application/json":{"schema":{"type":"object","description":"BLS BED survival rates. Each row is one NAICS × cohort-year combination.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"naics":{"type":"string","description":"2-digit NAICS code."},"naics_label":{"type":"string","description":"Human-readable sector name."},"cohort_year":{"type":"integer","description":"Year the establishments opened."},"year1_pct":{"type":["null","number"],"description":"Survival rate at 1 year (0–100). Null if data not yet available."},"year2_pct":{"type":["null","number"],"description":"Survival rate at 2 years."},"year3_pct":{"type":["null","number"],"description":"Survival rate at 3 years."},"year4_pct":{"type":["null","number"],"description":"Survival rate at 4 years."},"year5_pct":{"type":["null","number"],"description":"Survival rate at 5 years."}}}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Number of rows returned."},"source":{"type":"string","description":"Data source."},"computedAt":{"type":"string","description":"ISO 8601 timestamp."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/market-sizing":{"post":{"summary":"Calculate TAM, SAM, and SOM using a top-down or bottom-up method.","tags":["Business Finance"],"description":"Calculate Total Addressable Market (TAM), Serviceable Addressable Market (SAM), and Serviceable Obtainable Market (SOM) using a top-down or bottom-up method. Use this when someone wants to size a market opportunity for a pitch deck, business plan, or investment thesis. Returns TAM/SAM/SOM, implied market share, a multi-year SOM growth projection, a venture-scale assessment, VC threshold checks, and sanity-check warnings for aggressive assumptions. Example: \"My TAM is $5B, I can serve 10% of it (SAM), and I expect to capture 5% of that in year 1 (SOM), with 12% annual market growth over 5 years — what does that look like, and is it venture-scale?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["top-down","bottom-up"],"description":"Which sizing method to use. Example: \"top-down\""},"tamAmount":{"type":"number","description":"Top-down: Total Addressable Market in dollars. Example: 5000000000"},"samPct":{"type":"number","description":"Top-down: % of TAM that is your serviceable addressable market. Example: 10"},"somPct":{"type":"number","description":"Top-down: % of SAM you can realistically capture in Year 1. Example: 5"},"totalTargetCustomers":{"type":"number","description":"Bottom-up: total number of potential customers. Example: 500000"},"conversionRatePct":{"type":"number","description":"Bottom-up: % of target customers you expect to convert. Example: 2"},"averageRevenuePerCustomer":{"type":"number","description":"Bottom-up: average annual revenue per customer (ARPU), in dollars. Example: 1200"},"annualGrowthRatePct":{"type":"number","description":"Assumed annual market CAGR, defaults to 10. Example: 12"},"projectionYears":{"type":"number","description":"Years to project SOM growth, 1-10, defaults to 5. Example: 5"}},"required":["method"]}}}},"responses":{"200":{"description":"TAM, SAM, SOM, growth projection, and venture-scale assessment.","content":{"application/json":{"schema":{"type":"object","description":"TAM, SAM, SOM, growth projection, and venture-scale assessment.","properties":{"result":{"type":"object","properties":{"method":{"type":"string","enum":["top-down","bottom-up"]},"tam":{"type":"number","description":"Total Addressable Market, in dollars. Example: 5000000000"},"sam":{"type":"number","description":"Serviceable Addressable Market, in dollars. Example: 500000000"},"som":{"type":"number","description":"Serviceable Obtainable Market, in dollars. Example: 25000000"},"impliedMarketSharePct":{"type":"number","description":"SOM as a percentage of SAM. Example: 5"},"somGrowthProjection":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"som":{"type":"number"}}}},"vcScale":{"type":"string","enum":["venture-scale","growth-equity","lifestyle"]},"vcThresholds":{"type":"object","properties":{"tamVentureScale":{"type":"boolean","description":"TAM ≥ $1B"},"samVentureScale":{"type":"boolean","description":"SAM ≥ $100M"},"somYear3Adequate":{"type":"boolean","description":"Projected Year 3 SOM ≥ $10M"}}},"year5SOM":{"type":"number"},"year5SAM":{"type":"number"},"sanityChecks":{"type":"array","items":{"type":"string"}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/black-scholes":{"get":{"summary":"Price European call and put options using Black-Scholes-Merton.","tags":["Finance"],"description":"Price European call and put options using the Black-Scholes-Merton model, including all Greeks. Use this when someone needs a theoretical option price and its sensitivities (delta, gamma, vega, theta, rho) from spot price, strike, time to expiry, risk-free rate, and volatility. Example: \"Price a call and put with spot $100, strike $105, 6 months to expiry, 4.5% risk-free rate, and 20% volatility.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"spotPrice","required":true,"description":"Current price of the underlying asset. Example: 100"},{"schema":{"type":"string"},"in":"query","name":"strikePrice","required":true,"description":"Option strike price. Example: 105"},{"schema":{"type":"string"},"in":"query","name":"timeToExpiry","required":true,"description":"Years to expiry, up to 10. Example: 0.5"},{"schema":{"type":"string"},"in":"query","name":"riskFreeRate","required":true,"description":"Annual risk-free rate as a decimal, -0.1 to 0.3. Example: 0.045"},{"schema":{"type":"string"},"in":"query","name":"volatility","required":true,"description":"Annual volatility as a decimal, up to 5. Example: 0.2"}],"responses":{"200":{"description":"Call and put prices plus the full set of Greeks.","content":{"application/json":{"schema":{"type":"object","description":"Call and put prices plus the full set of Greeks.","properties":{"result":{"type":"object","properties":{"callPrice":{"type":"number"},"putPrice":{"type":"number"},"d1":{"type":"number"},"d2":{"type":"number"},"callDelta":{"type":"number"},"putDelta":{"type":"number"},"gamma":{"type":"number"},"vega":{"type":"number","description":"Per 1% change in volatility."},"callTheta":{"type":"number","description":"Per calendar day."},"putTheta":{"type":"number","description":"Per calendar day."},"callRho":{"type":"number","description":"Per 1% change in risk-free rate."},"putRho":{"type":"number","description":"Per 1% change in risk-free rate."}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/startup-valuation":{"post":{"summary":"Value a startup using DCF, revenue multiple, or the VC method.","tags":["Business Finance"],"description":"Value a startup using DCF, revenue multiple, or the VC method. Use this when someone wants a startup valuation with a recommended range, not just a single number. Returns the primary valuation, a ±20% recommended range, and supporting figures for whichever method was chosen. Example: \"Value a startup with $2M annual revenue at a 5x revenue multiple\" or \"What is the pre-money valuation if an investor puts in $500K targeting a 10x return, with projected exit revenue of $20M at a 4x exit multiple?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["dcf","revenue-multiple","vc-method"],"description":"Valuation method. Example: \"revenue-multiple\""},"cashFlows":{"type":"array","items":{"type":"number"},"description":"DCF: projected annual free cash flows, years 1-N. Example: [100000, 150000, 220000]"},"discountRate":{"type":"number","description":"DCF: discount rate as a decimal. Example: 0.15"},"terminalGrowthRate":{"type":"number","description":"DCF: terminal growth rate as a decimal. Example: 0.03"},"annualRevenue":{"type":"number","description":"Revenue multiple: current annual revenue. Example: 2000000"},"revenueMultiple":{"type":"number","description":"Revenue multiple: multiple to apply, e.g. 5 for 5x. Example: 5"},"investmentAmount":{"type":"number","description":"VC method: amount being invested. Example: 500000"},"targetReturnMultiple":{"type":"number","description":"VC method: target return multiple, e.g. 10 for 10x. Example: 10"},"projectedExitRevenue":{"type":"number","description":"VC method: projected revenue at exit. Example: 20000000"},"exitRevenueMultiple":{"type":"number","description":"VC method: industry exit revenue multiple. Example: 4"},"ownershipPercent":{"type":"number","description":"VC method: % being sold to investor, as a decimal, optional. Example: 0.2"}},"required":["method"]}}}},"responses":{"200":{"description":"Startup valuation with a recommended range.","content":{"application/json":{"schema":{"type":"object","description":"Startup valuation with a recommended range.","properties":{"result":{"type":"object","properties":{"method":{"type":"string","enum":["dcf","revenue-multiple","vc-method"]},"dcfValuation":{"type":["null","number"]},"revenueMultipleValuation":{"type":["null","number"]},"vcPreMoneyValuation":{"type":["null","number"]},"vcPostMoneyValuation":{"type":["null","number"]},"terminalValue":{"type":["null","number"]},"npvOfCashFlows":{"type":["null","number"]},"impliedExitValue":{"type":["null","number"]},"impliedOwnershipPercent":{"type":["null","number"]},"rangeMin":{"type":"number"},"rangeMax":{"type":"number"},"primaryValuation":{"type":"number"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/engagement-rate":{"get":{"summary":"Calculate social media engagement rate and compare against industry benchmarks.","tags":["Business Finance"],"description":"Calculate social media engagement rate and compare against 2025 industry benchmarks by platform and follower tier. Use this when someone wants to know if their post engagement is above or below the norm for their platform and audience size. Returns engagement rate, the benchmark for that platform/tier, and a performance rating. Example: \"I have 50,000 Instagram followers and got 1,200 likes, 80 comments, and 40 shares on a post — is that good?\"","parameters":[{"schema":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","twitter_x","facebook"]},"in":"query","name":"platform","required":true,"description":"Social media platform. Example: \"instagram\""},{"schema":{"type":"string"},"in":"query","name":"followers","required":true,"description":"Total follower count. Example: 50000"},{"schema":{"type":"string"},"in":"query","name":"likes","required":true,"description":"Total likes. Example: 1200"},{"schema":{"type":"string"},"in":"query","name":"comments","required":true,"description":"Total comments. Example: 80"},{"schema":{"type":"string"},"in":"query","name":"shares","required":true,"description":"Total shares, retweets, or reposts. Example: 40"},{"schema":{"type":"string"},"in":"query","name":"posts","required":false,"description":"Number of posts the interactions are spread across, defaults to 1. Example: 1"}],"responses":{"200":{"description":"Engagement rate compared against the platform/tier benchmark.","content":{"application/json":{"schema":{"type":"object","description":"Engagement rate compared against the platform/tier benchmark.","properties":{"result":{"type":"object","properties":{"platform":{"type":"string"},"followers":{"type":"number"},"tier":{"type":"string","enum":["nano","micro","mid","macro","mega"]},"tierLabel":{"type":"string"},"engagementRate":{"type":"number"},"benchmarkRate":{"type":"number"},"performanceRating":{"type":"string","enum":["below","at","above"]},"performanceLabel":{"type":"string"},"percentOfBenchmark":{"type":"number"},"totalInteractions":{"type":"number"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/influencer-roi":{"get":{"summary":"Estimate influencer marketing campaign ROI, ROAS, and cost per conversion.","tags":["Business Finance"],"description":"Estimate influencer marketing ROI, ROAS, cost per engagement, and cost per conversion from campaign spend and audience data. Use this when someone wants to know if an influencer campaign is likely to be profitable before committing spend. Example: \"A campaign costs $5,000 with an influencer who has 100,000 followers, 3% engagement rate, 1.5% conversion rate, and a $60 average order value — what's the expected ROI?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"campaignCost","required":true,"description":"Total campaign spend, including fees and production. Example: 5000"},{"schema":{"type":"string"},"in":"query","name":"followers","required":true,"description":"Influencer follower count. Example: 100000"},{"schema":{"type":"string"},"in":"query","name":"engagementRate","required":true,"description":"Engagement rate as a decimal, e.g. 0.03 for 3%. Example: 0.03"},{"schema":{"type":"string"},"in":"query","name":"conversionRate","required":true,"description":"% of engaged users expected to convert, as a decimal. Example: 0.015"},{"schema":{"type":"string"},"in":"query","name":"averageOrderValue","required":true,"description":"Average order value. Example: 60"},{"schema":{"type":"string"},"in":"query","name":"postCount","required":false,"description":"Number of posts in the campaign, defaults to 1. Example: 1"}],"responses":{"200":{"description":"Estimated funnel, ROI, and ROAS for the campaign.","content":{"application/json":{"schema":{"type":"object","description":"Estimated funnel, ROI, and ROAS for the campaign.","properties":{"result":{"type":"object","properties":{"estimatedReach":{"type":"number"},"estimatedEngagements":{"type":"number"},"estimatedConversions":{"type":"number"},"estimatedRevenue":{"type":"number"},"roi":{"type":"number"},"roas":{"type":"number"},"costPerEngagement":{"type":"number"},"costPerConversion":{"type":"number"},"breakEvenConversions":{"type":"number"},"isRoiPositive":{"type":"boolean"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/email-marketing-roi":{"get":{"summary":"Calculate email marketing campaign ROI, ROAS, and revenue per subscriber.","tags":["Business Finance"],"description":"Calculate email campaign ROI, ROAS, revenue per subscriber, and cost per conversion — with industry benchmark comparisons. Use this when someone wants to know if an email campaign is profitable and how its open/click rates compare to industry norms. Example: \"A list of 10,000 subscribers, campaign cost $200, 22% open rate, 3% click-through rate, 2% conversion rate, $50 average order value — what's the ROI?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"listSize","required":true,"description":"Total subscribers. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"campaignCost","required":true,"description":"Cost to send, including platform fee and copywriting. Example: 200"},{"schema":{"type":"string"},"in":"query","name":"openRate","required":true,"description":"Open rate as a decimal, 0-1. Example: 0.22"},{"schema":{"type":"string"},"in":"query","name":"clickThroughRate","required":true,"description":"% of opens that click, as a decimal, 0-1. Example: 0.03"},{"schema":{"type":"string"},"in":"query","name":"conversionRate","required":true,"description":"% of clicks that convert, as a decimal, 0-1. Example: 0.02"},{"schema":{"type":"string"},"in":"query","name":"averageOrderValue","required":true,"description":"Average order value. Example: 50"},{"schema":{"type":"string"},"in":"query","name":"campaignCount","required":false,"description":"Campaigns per period, defaults to 1. Example: 1"}],"responses":{"200":{"description":"Email campaign funnel, ROI, and benchmark comparison.","content":{"application/json":{"schema":{"type":"object","description":"Email campaign funnel, ROI, and benchmark comparison.","properties":{"result":{"type":"object","properties":{"opens":{"type":"number"},"clicks":{"type":"number"},"conversions":{"type":"number"},"revenue":{"type":"number"},"roi":{"type":"number"},"roas":{"type":"number"},"revenuePerSubscriber":{"type":"number"},"costPerConversion":{"type":["null","number"]},"breakEvenConversions":{"type":"number"},"isRoiPositive":{"type":"boolean"},"industryOpenRateBenchmark":{"type":"number"},"industryClickRateBenchmark":{"type":"number"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/diet-outcome":{"get":{"summary":"Estimate BMR, TDEE, and a projected weight-change timeline.","tags":["Health & Life"],"description":"Estimate BMR, TDEE, and projected weight change timeline using Mifflin-St Jeor and energy balance. Use this when someone wants to know how long it will take to reach a goal weight at a given calorie deficit or surplus. Example: \"I'm a 30-year-old woman, 70kg, 165cm, moderately active, want to reach 62kg with a 500 kcal/day deficit — how long will it take?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years, 18-100. Example: 30"},{"schema":{"type":"string","enum":["male","female"]},"in":"query","name":"sex","required":true,"description":"Biological sex, used for the Mifflin-St Jeor formula. Example: \"female\""},{"schema":{"type":"string"},"in":"query","name":"weightKg","required":true,"description":"Current weight in kg. Example: 70"},{"schema":{"type":"string"},"in":"query","name":"heightCm","required":true,"description":"Height in cm. Example: 165"},{"schema":{"type":"string","enum":["sedentary","light","moderate","active","very_active"]},"in":"query","name":"activityLevel","required":true,"description":"Activity level, used for the TDEE multiplier. Example: \"moderate\""},{"schema":{"type":"string"},"in":"query","name":"goalWeightKg","required":true,"description":"Target weight in kg. Example: 62"},{"schema":{"type":"string"},"in":"query","name":"dailyCalorieAdjustment","required":true,"description":"Daily calorie deficit (negative) or surplus (positive), -1000 to 1000. Example: -500"}],"responses":{"200":{"description":"BMR, TDEE, target calories, and a projected weight-change timeline.","content":{"application/json":{"schema":{"type":"object","description":"BMR, TDEE, target calories, and a projected weight-change timeline.","properties":{"result":{"type":"object","properties":{"bmr":{"type":"number","description":"Basal metabolic rate, kcal/day."},"tdee":{"type":"number","description":"Total daily energy expenditure, kcal/day."},"targetDailyCalories":{"type":"number"},"weeklyWeightChangeKg":{"type":"number"},"weeklyWeightChangeLb":{"type":"number"},"monthlyWeightChangeKg":{"type":"number"},"monthlyWeightChangeLb":{"type":"number"},"weightDeltaKg":{"type":"number"},"weeksToGoal":{"type":["null","number"]},"daysToGoal":{"type":["null","number"]},"estimatedGoalDate":{"type":["null","string"]},"category":{"type":"string","enum":["weight-loss","maintenance","weight-gain"]},"warningLowCalorie":{"type":"boolean"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/water-intake":{"get":{"summary":"Estimate recommended daily water intake based on body weight, activity level, and climate (EFSA/NHS-guideline-based).","tags":["Health & Life"],"description":"Estimate recommended daily water intake based on body weight, activity level, and climate (EFSA/NHS-guideline-based). Use this when a user wants to know how much water they should drink per day. Returns litres, glasses, bottles, and an hourly target. Example: \"How much water should I drink daily if I weigh 75kg, am moderately active, and live somewhere hot?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"bodyWeightKg","required":true,"description":"Body weight in kilograms. Example: 75"},{"schema":{"type":"string","enum":["sedentary","lightlyActive","moderatelyActive","veryActive"]},"in":"query","name":"activityLevel","required":true,"description":"Typical activity level. Example: \"moderatelyActive\""},{"schema":{"type":"string","enum":["temperate","hot","veryHot"]},"in":"query","name":"climate","required":true,"description":"Climate lived in. Example: \"hot\""}],"responses":{"200":{"description":"Recommended daily water intake in litres, glasses, bottles, and an hourly target.","content":{"application/json":{"schema":{"type":"object","description":"Recommended daily water intake in litres, glasses, bottles, and an hourly target.","properties":{"result":{"type":"object","description":"The water intake recommendation.","properties":{"dailyIntakeLitres":{"type":"number","description":"Recommended daily water intake in litres. Example: 3.47"},"glasses250ml":{"type":"number","description":"Equivalent number of 250ml glasses. Example: 13.86"},"bottles500ml":{"type":"number","description":"Equivalent number of 500ml bottles. Example: 6.93"},"hourlyTargetLitres":{"type":"number","description":"Recommended intake per waking hour, in litres (assumes 16 waking hours). Example: 0.22"}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"SeventyFiveKgModeratelyActiveHot":{"summary":"75kg body weight, moderately active, hot climate","value":{"result":{"dailyIntakeLitres":3.47,"glasses250ml":13.86,"bottles500ml":6.93,"hourlyTargetLitres":0.22},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sleep-cycle":{"get":{"summary":"Calculate optimal wake-up times from a bedtime, or recommended bedtimes from a wake time, aligned to 90-minute sleep cycles.","tags":["Health & Life"],"description":"Calculate optimal wake-up times from a bedtime, or recommended bedtimes from a wake time, aligned to 90-minute sleep cycles. Use this when a user wants to wake up feeling less groggy by timing sleep to complete cycles. Returns 4/5/6-cycle options. Example: \"If I go to bed at 11pm, what are the best times to wake up?\"","parameters":[{"schema":{"type":"string","enum":["wakeUp","bedtime"]},"in":"query","name":"mode","required":true,"description":"\"wakeUp\" to get wake times from a bedtime, \"bedtime\" to get bedtimes from a wake time. Example: \"wakeUp\""},{"schema":{"type":"string"},"in":"query","name":"time","required":true,"description":"HH:MM in 24-hour format — the bedtime (wakeUp mode) or desired wake time (bedtime mode). Example: \"23:00\""}],"responses":{"200":{"description":"Wake-up or bedtime options aligned to 90-minute sleep cycles, at 4/5/6 cycles.","content":{"application/json":{"schema":{"type":"object","description":"Wake-up or bedtime options aligned to 90-minute sleep cycles, at 4/5/6 cycles.","properties":{"result":{"type":"object","description":"The sleep cycle result.","properties":{"mode":{"type":"string","description":"The mode used for this calculation. Example: \"wakeUp\"","enum":["wakeUp","bedtime"]},"inputTime":{"type":"string","description":"The input time echoed back, HH:MM 24-hour. Example: \"23:00\""},"options":{"type":"array","description":"Wake-up times (wakeUp mode) or bedtimes (bedtime mode) for 4, 5, and 6 sleep cycles.","items":{"type":"object","properties":{"cycles":{"type":"number","description":"Number of 90-minute sleep cycles. Example: 5"},"time":{"type":"string","description":"Resulting time, HH:MM 24-hour. Example: \"06:44\""},"totalSleepDuration":{"type":"string","description":"Total sleep duration as text. Example: \"7h 44m\""},"totalSleepMinutes":{"type":"number","description":"Total sleep duration in minutes, including the 14-minute fall-asleep buffer. Example: 464"},"label":{"type":"string","description":"Descriptive label for this option.","enum":["minimum","recommended","optimal"]},"closestToEightHours":{"type":"boolean","description":"Whether this option is the closest to 8 hours of sleep among the three."}}}}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"BedtimeElevenPM":{"summary":"Wake-up times for an 11pm bedtime","value":{"result":{"mode":"wakeUp","inputTime":"23:00","options":[{"cycles":4,"time":"05:14","totalSleepDuration":"6h 14m","totalSleepMinutes":374,"label":"minimum","closestToEightHours":false},{"cycles":5,"time":"06:44","totalSleepDuration":"7h 44m","totalSleepMinutes":464,"label":"recommended","closestToEightHours":true},{"cycles":6,"time":"08:14","totalSleepDuration":"9h 14m","totalSleepMinutes":554,"label":"optimal","closestToEightHours":false}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/saas-revenue":{"get":{"summary":"Calculate core SaaS revenue metrics from customer count, ARPU, and churn.","tags":["Business Finance"],"description":"Calculate core SaaS revenue metrics from customer count, ARPU, and churn. Use this when a founder or analyst wants MRR, ARR, and a growth/churn-adjusted revenue projection for a subscription business. Returns MRR, ARR, a 12-month churn-adjusted revenue projection, customer LTV, and months to double revenue. Example: \"What are the SaaS metrics for a business with 500 customers at $60 ARPU and 4% monthly churn?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"customers","required":true,"description":"Number of customers. Example: 500"},{"schema":{"type":"string"},"in":"query","name":"arpu","required":true,"description":"Average revenue per user per month ($). Example: 60"},{"schema":{"type":"string"},"in":"query","name":"monthlyChurnRate","required":true,"description":"Monthly churn rate as a percentage. Example: 4"}],"responses":{"200":{"description":"MRR, ARR, customer LTV, months to double revenue, and a 12-month churn-adjusted MRR projection.","content":{"application/json":{"schema":{"type":"object","description":"MRR, ARR, customer LTV, months to double revenue, and a 12-month churn-adjusted MRR projection.","properties":{"result":{"type":"object","description":"The SaaS revenue metrics.","properties":{"mrr":{"type":"number","description":"Monthly recurring revenue (customers x ARPU). Example: 30000"},"arr":{"type":"number","description":"Annual recurring revenue (MRR x 12). Example: 360000"},"customerLtv":{"type":["null","number"],"description":"Customer lifetime value (ARPU / churn rate). Null if churn is 0. Example: 1500"},"monthsToDoubleRevenue":{"type":["null","number"],"description":"Months to double revenue if net growth matched the churn rate in reverse. Null if churn is 0. Example: 17.67"},"projection":{"type":"array","description":"12-month churn-adjusted MRR projection.","items":{"type":"object","properties":{"month":{"type":"number","description":"Month index, 1-12."},"mrr":{"type":"number","description":"Projected MRR for that month."}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"500CustomersAt4PercentChurn":{"summary":"SaaS metrics for 500 customers at $60 ARPU and 4% monthly churn","value":{"result":{"mrr":30000,"arr":360000,"customerLtv":1500,"monthsToDoubleRevenue":17.67,"projection":[{"month":1,"mrr":28800},{"month":2,"mrr":27648},{"month":3,"mrr":26542.08},{"month":4,"mrr":25480.4},{"month":5,"mrr":24461.18},{"month":6,"mrr":23482.73},{"month":7,"mrr":22543.42},{"month":8,"mrr":21641.69},{"month":9,"mrr":20776.02},{"month":10,"mrr":19944.98},{"month":11,"mrr":19147.18},{"month":12,"mrr":18381.29}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/freelance-rate":{"get":{"summary":"Calculate the minimum day rate and hourly rate a freelancer or contractor needs to charge to hit a desired annual take-home income, accounting for overheads and tax.","tags":["Business Finance"],"description":"Calculate the minimum day rate and hourly rate a freelancer or contractor needs to charge to hit a desired annual take-home income, accounting for overheads and tax. Use this when a user is setting freelance rates and wants to work backward from a target income. Returns the required day rate, hourly rate, and required annual gross revenue. Example: \"What day rate do I need to charge to take home $80,000 a year, working 45 weeks a year?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"desiredAnnualTakeHome","required":true,"description":"Desired annual take-home (post-tax) income. Example: 80000"},{"schema":{"type":"string"},"in":"query","name":"weeksPerYear","required":false,"description":"Weeks worked per year, defaults to 48. Example: 45"},{"schema":{"type":"string"},"in":"query","name":"billableHoursPerWeek","required":false,"description":"Billable hours per week, defaults to 30. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"annualOverheads","required":false,"description":"Annual business overheads, defaults to 2000. Example: 2000"},{"schema":{"type":"string"},"in":"query","name":"incomeTaxRate","required":false,"description":"Income tax rate as a percentage, defaults to 25. Example: 25"}],"responses":{"200":{"description":"The minimum day rate and hourly rate needed to hit a desired annual take-home income, plus the required gross revenue and billable time.","content":{"application/json":{"schema":{"type":"object","description":"The minimum day rate and hourly rate needed to hit a desired annual take-home income, plus the required gross revenue and billable time.","properties":{"result":{"type":"object","description":"The freelance rate result.","properties":{"requiredAnnualGrossRevenue":{"type":"number","description":"Gross revenue needed to cover tax and overheads and net the desired take-home. Example: 108666.67"},"minDayRate":{"type":"number","description":"Required gross revenue divided by billable days per year. Example: 643.95"},"minHourlyRate":{"type":"number","description":"Required gross revenue divided by billable hours per year. Example: 80.49"},"billableDaysPerYear":{"type":"number","description":"Billable hours per year divided by 8. Example: 168.75"},"billableHoursPerYear":{"type":"number","description":"Weeks per year x billable hours per week. Example: 1350"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"80kTakeHome":{"summary":"Rates needed for $80,000 take-home, working 45 weeks a year","value":{"result":{"requiredAnnualGrossRevenue":108666.67,"minDayRate":643.95,"minHourlyRate":80.49,"billableDaysPerYear":168.75,"billableHoursPerYear":1350},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/startup-runway":{"get":{"summary":"Calculate startup cash runway.","tags":["Business Finance"],"description":"Calculate startup cash runway. Use this when a founder wants to know how many months of cash they have left, with or without projected revenue growth. Returns months of runway with and without revenue growth, monthly revenue needed to break even, and a month-by-month cash balance series. Example: \"How many months of runway do we have with $500,000 in the bank, burning $80,000/month, with $20,000 in current monthly revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentCashBalance","required":true,"description":"Current cash balance. Example: 500000"},{"schema":{"type":"string"},"in":"query","name":"monthlyBurnRate","required":true,"description":"Gross monthly costs. Example: 80000"},{"schema":{"type":"string"},"in":"query","name":"currentMonthlyRevenue","required":true,"description":"Current monthly revenue. Example: 20000"},{"schema":{"type":"string"},"in":"query","name":"projectedMonthlyRevenueGrowth","required":false,"description":"Projected monthly revenue growth as a percentage, defaults to 0. Example: 5"}],"responses":{"200":{"description":"Months of cash runway with and without revenue growth, the monthly revenue needed to break even, and a month-by-month cash balance series.","content":{"application/json":{"schema":{"type":"object","description":"Months of cash runway with and without revenue growth, the monthly revenue needed to break even, and a month-by-month cash balance series.","properties":{"result":{"type":"object","description":"The runway result.","properties":{"monthsOfRunwayNoGrowth":{"type":["null","number"],"description":"Months of runway assuming flat revenue. Null if current revenue already covers burn. Example: 8.33"},"monthsOfRunwayWithGrowth":{"type":["null","number"],"description":"Month the cash balance hits zero under the projected growth rate, from the simulation. Null if cash never runs out within the simulated horizon. Example: 10"},"monthlyRevenueNeededToBreakEven":{"type":"number","description":"Monthly revenue needed to fully offset the monthly burn rate. Example: 80000"},"cashBalanceSeries":{"type":"array","description":"Month-by-month projected cash balance, capped at 36 months for charting.","items":{"type":"object","properties":{"month":{"type":"number","description":"Month index, starting at 0."},"cashBalance":{"type":"number","description":"Projected cash balance for that month, floored at 0."}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"500kCashBurning80kMonth":{"summary":"Runway for $500k cash, $80k/month burn, $20k revenue growing 5%/month","value":{"result":{"monthsOfRunwayNoGrowth":8.33,"monthsOfRunwayWithGrowth":10,"monthlyRevenueNeededToBreakEven":80000,"cashBalanceSeries":[{"month":0,"cashBalance":500000},{"month":1,"cashBalance":440000},{"month":2,"cashBalance":381000},{"month":3,"cashBalance":323050},{"month":4,"cashBalance":266202.5},{"month":5,"cashBalance":210512.63},{"month":6,"cashBalance":156038.26},{"month":7,"cashBalance":102840.17},{"month":8,"cashBalance":50982.18},{"month":9,"cashBalance":531.29},{"month":10,"cashBalance":0}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/customer-ltv":{"get":{"summary":"Calculate customer lifetime value (LTV) for a subscription or recurring-revenue business.","tags":["Business Finance"],"description":"Calculate customer lifetime value (LTV) for a subscription or recurring-revenue business. Use this when a user wants to know how much a typical customer is worth, and how that compares to what it costs to acquire them. Returns LTV, LTV:CAC ratio (if CAC supplied), payback period in months, and a health classification. Example: \"What is the customer LTV for a SaaS business with $50 ARPU, 80% gross margin, 5% monthly churn, and a $300 CAC?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"arpu","required":true,"description":"Average revenue per customer per month ($). Example: 50"},{"schema":{"type":"string"},"in":"query","name":"grossMarginPercent","required":true,"description":"Gross margin as a percentage. Example: 80"},{"schema":{"type":"string"},"in":"query","name":"monthlyChurnRate","required":true,"description":"Monthly churn rate as a percentage. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"cac","required":false,"description":"Customer acquisition cost ($), optional. Example: 300"}],"responses":{"200":{"description":"Customer lifetime value, LTV:CAC ratio and payback period (if CAC supplied), and a health classification.","content":{"application/json":{"schema":{"type":"object","description":"Customer lifetime value, LTV:CAC ratio and payback period (if CAC supplied), and a health classification.","properties":{"result":{"type":"object","description":"The LTV result.","properties":{"ltv":{"type":"number","description":"Customer lifetime value ($). Example: 800"},"ltvToCacRatio":{"type":["null","number"],"description":"LTV divided by CAC. Null if cac was not supplied. Example: 2.67"},"paybackMonths":{"type":["null","number"],"description":"Months of margin-adjusted revenue needed to recoup CAC. Null if cac was not supplied. Example: 7.5"},"classification":{"type":["null","string"],"enum":["unsustainable","marginal","healthy","excellent",null],"description":"Health classification based on the LTV:CAC ratio. Null if cac was not supplied. Example: \"marginal\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"SaasCustomerWithCac":{"summary":"LTV for a SaaS customer with $50 ARPU, 80% gross margin, 5% churn, $300 CAC","value":{"result":{"ltv":800,"ltvToCacRatio":2.67,"paybackMonths":7.5,"classification":"marginal"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/break-even-revenue":{"get":{"summary":"Calculate the monthly break-even revenue for a business.","tags":["Business Finance"],"description":"Calculate the monthly break-even revenue for a business. Use this when a user wants to know how much they need to sell each month to cover fixed costs, or how much cushion they have above break-even. Returns break-even units per month, break-even revenue per month, contribution margin, and margin of safety if current monthly units sold is provided. Example: \"How much monthly revenue do I need to break even with $5,000 in fixed costs, a $20 cost per unit, and a $35 selling price?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"fixedCosts","required":true,"description":"Total monthly fixed costs. Example: 5000"},{"schema":{"type":"string"},"in":"query","name":"variableCostPerUnit","required":true,"description":"Variable cost to produce/sell one unit. Example: 20"},{"schema":{"type":"string"},"in":"query","name":"sellingPricePerUnit","required":true,"description":"Selling price of one unit. Example: 35"},{"schema":{"type":"string"},"in":"query","name":"currentSalesVolume","required":false,"description":"Optional current monthly units sold, used to compute margin of safety. Example: 400"}],"responses":{"200":{"description":"Break-even units and revenue for the month, contribution margin, and margin of safety if currentSalesVolume was supplied.","content":{"application/json":{"schema":{"type":"object","description":"Break-even units and revenue for the month, contribution margin, and margin of safety if currentSalesVolume was supplied.","properties":{"result":{"type":"object","description":"The break-even result.","properties":{"breakEvenUnits":{"type":"number","description":"Units needed per month to cover fixed costs, rounded up. Example: 334"},"breakEvenRevenue":{"type":"number","description":"Monthly revenue at the break-even unit count. Example: 11690"},"contributionMargin":{"type":"number","description":"Selling price minus variable cost per unit. Example: 15"},"contributionMarginRatio":{"type":"number","description":"Contribution margin as a percentage of selling price. Example: 42.86"},"marginOfSafetyUnits":{"type":["null","number"],"description":"Current monthly units sold minus break-even units. Null if currentSalesVolume was not supplied. Example: 66"},"marginOfSafetyPercent":{"type":["null","number"],"description":"Margin of safety as a percentage of current monthly units sold. Null if currentSalesVolume was not supplied. Example: 16.5"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"5kFixedCosts":{"summary":"Monthly break-even for $5,000 fixed costs, $20 variable cost, $35 selling price, 400 units sold","value":{"result":{"breakEvenUnits":334,"breakEvenRevenue":11690,"contributionMargin":15,"contributionMarginRatio":42.86,"marginOfSafetyUnits":66,"marginOfSafetyPercent":16.5},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/heart-disease-risk":{"get":{"summary":"Estimate 10-year cardiovascular disease risk using the published Framingham General CVD risk model.","tags":["Health & Life"],"description":"Estimate 10-year cardiovascular disease risk using the published Framingham General CVD risk model. Use this when a user wants a population-level estimate of their heart disease risk from standard clinical measurements. Returns risk percentage, risk category (low/moderate/high), and comparison to an average person of the same age and sex. Population-level estimate, not a diagnosis. Example: \"What is my 10-year cardiovascular risk if I'm a 55-year-old man with total cholesterol 220, HDL 45, systolic BP 135, not on medication, non-smoker, no diabetes?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years (30-79, the model's validated range). Example: 55"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex. Example: \"M\""},{"schema":{"type":"string"},"in":"query","name":"totalCholesterol","required":true,"description":"Total cholesterol in mg/dL. Example: 220"},{"schema":{"type":"string"},"in":"query","name":"hdlCholesterol","required":true,"description":"HDL (\"good\") cholesterol in mg/dL. Example: 45"},{"schema":{"type":"string"},"in":"query","name":"systolicBP","required":true,"description":"Systolic blood pressure in mmHg. Example: 135"},{"schema":{"type":"string"},"in":"query","name":"onBPMedication","required":true,"description":"Whether currently on blood pressure medication. Example: false"},{"schema":{"type":"string"},"in":"query","name":"smoker","required":true,"description":"Whether a current smoker. Example: false"},{"schema":{"type":"string"},"in":"query","name":"diabetes","required":true,"description":"Whether diagnosed with diabetes. Example: false"}],"responses":{"200":{"description":"10-year cardiovascular disease risk from the Framingham General CVD model, with risk category and comparison to an average peer.","content":{"application/json":{"schema":{"type":"object","description":"10-year cardiovascular disease risk from the Framingham General CVD model, with risk category and comparison to an average peer.","properties":{"result":{"type":"object","description":"The cardiovascular risk result.","properties":{"tenYearRiskPercent":{"type":"number","description":"Estimated 10-year cardiovascular disease risk, as a percentage, capped at 30. Example: 14.4"},"riskCategory":{"type":"string","description":"Risk category derived from tenYearRiskPercent. Example: \"moderate\"","enum":["low","moderate","high"]},"averageRiskForAgeSex":{"type":"number","description":"10-year risk for an average-profile peer of the same age and sex, as a percentage. Example: 9.6"},"vsAverage":{"type":"number","description":"Percentage points vs the average-profile peer. Example: 4.8"},"caveat":{"type":"string","description":"Disclaimer about the statistical, non-diagnostic nature of the estimate."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FiftyFiveYearOldMan":{"summary":"55-year-old man, total cholesterol 220, HDL 45, systolic BP 135, not on medication, non-smoker, no diabetes","value":{"result":{"tenYearRiskPercent":14.4,"riskCategory":"moderate","averageRiskForAgeSex":9.6,"vsAverage":4.8,"caveat":"A population-level statistical estimate from the published Framingham General CVD model, not a diagnosis. It does not account for family history, other lab values, or medications beyond blood pressure treatment — discuss your actual risk with a clinician."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/biological-age":{"get":{"summary":"Estimate biological age from lifestyle factors using ranges derived from published biomarker-aging research.","tags":["Health & Life"],"description":"Estimate biological age from lifestyle factors using ranges derived from published biomarker-aging research. Use this when a user wants to know how their exercise, sleep, weight, smoking, diet, stress, and drinking habits compare to their chronological age. Returns estimated biological age, the delta vs chronological age, and the top 3 factors to improve. Example: \"What is my biological age if I'm 35, exercise 90 minutes a week, sleep 6.5 hours, have a BMI of 27, don't smoke, eat a good diet, have medium stress, and drink 5 units of alcohol a week?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"chronologicalAge","required":true,"description":"Actual age in years. Example: 35"},{"schema":{"type":"string"},"in":"query","name":"exerciseMinPerWeek","required":true,"description":"Minutes of exercise per week. Example: 90"},{"schema":{"type":"string"},"in":"query","name":"sleepHours","required":true,"description":"Average hours of sleep per night. Example: 6.5"},{"schema":{"type":"string"},"in":"query","name":"bmi","required":true,"description":"Body mass index. Example: 27"},{"schema":{"type":"string"},"in":"query","name":"smoker","required":true,"description":"Whether a current smoker. Example: false"},{"schema":{"type":"string","enum":["poor","fair","good","excellent"]},"in":"query","name":"diet","required":true,"description":"Overall diet quality. Example: \"good\""},{"schema":{"type":"string","enum":["low","medium","high"]},"in":"query","name":"stress","required":true,"description":"Typical day-to-day stress level. Example: \"medium\""},{"schema":{"type":"string"},"in":"query","name":"alcoholUnitsPerWeek","required":true,"description":"Alcohol units consumed per week. Example: 5"}],"responses":{"200":{"description":"Estimated biological age from lifestyle factors, with a per-factor breakdown and the top factors to improve.","content":{"application/json":{"schema":{"type":"object","description":"Estimated biological age from lifestyle factors, with a per-factor breakdown and the top factors to improve.","properties":{"result":{"type":"object","description":"The biological age estimate.","properties":{"estimatedBiologicalAge":{"type":"number","description":"Estimated biological age in years. Example: 35.2"},"deltaYears":{"type":"number","description":"estimatedBiologicalAge minus chronologicalAge. Example: 0.2"},"factorBreakdown":{"type":"array","description":"Per-factor contribution to the biological age delta.","items":{"type":"object","properties":{"factor":{"type":"string","description":"Name of the lifestyle factor. Example: \"Exercise\""},"impactYears":{"type":"number","description":"Years contributed; positive ages you, negative makes you biologically younger. Example: 0.5"}}}},"topFactorsToImprove":{"type":"array","description":"Names of the top 3 factors with the largest positive (aging) impact.","items":{"type":"string"}},"caveat":{"type":"string","description":"Disclaimer about the statistical nature of the estimate."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"ThirtyFiveYearOldModerateLifestyle":{"summary":"35-year-old, 90 min/week exercise, 6.5h sleep, BMI 27, non-smoker, good diet, medium stress, 5 units/week alcohol","value":{"result":{"estimatedBiologicalAge":35.2,"deltaYears":0.2,"factorBreakdown":[{"factor":"Exercise","impactYears":0.5},{"factor":"Sleep","impactYears":0},{"factor":"BMI","impactYears":0.8},{"factor":"Smoking","impactYears":0},{"factor":"Diet quality","impactYears":-1.5},{"factor":"Stress level","impactYears":0},{"factor":"Alcohol","impactYears":0.4}],"topFactorsToImprove":["BMI","Exercise","Alcohol"],"caveat":"A population-level statistical estimate from published lifestyle-aging research, not a lab-measured biological age."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/alcohol-impact":{"get":{"summary":"Estimate the health impact of weekly alcohol consumption using WHO dose-response mortality research.","tags":["Health & Life"],"description":"Estimate the health impact of weekly alcohol consumption using WHO dose-response mortality research. Use this when a user wants to understand how their drinking habits affect life expectancy, liver disease risk, or cancer risk. Returns estimated years of life impact, liver disease risk percentile vs the population, and cancer risk uplift. Example: \"What's the health impact of drinking 14 units of alcohol a week for a 40-year-old man?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"unitsPerWeek","required":true,"description":"Standard alcohol units (10g of pure alcohol each) consumed per week. Example: 14"},{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Current age in years. Example: 40"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex — affects the dose-response curve used. Example: \"M\""}],"responses":{"200":{"description":"Estimated health impact of weekly alcohol consumption: years of life impact, liver disease risk percentile, and cancer risk uplift.","content":{"application/json":{"schema":{"type":"object","description":"Estimated health impact of weekly alcohol consumption: years of life impact, liver disease risk percentile, and cancer risk uplift.","properties":{"result":{"type":"object","description":"The alcohol impact estimate.","properties":{"estimatedYearsOfLifeImpact":{"type":"number","description":"Estimated years of life expectancy impact; negative = years lost. Example: -2.35"},"liverDiseaseRiskPercentile":{"type":"number","description":"Liver disease risk percentile vs the population, 0-99; higher = greater risk. Example: 27"},"cancerRiskUpliftPercent":{"type":"number","description":"Percentage increase in relative cancer risk. Example: 14"},"caveat":{"type":"string","description":"Disclaimer about the statistical nature of the estimate."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FortyYearOldManFourteenUnits":{"summary":"40-year-old man drinking 14 units of alcohol a week","value":{"result":{"estimatedYearsOfLifeImpact":-2.35,"liverDiseaseRiskPercentile":27,"cancerRiskUpliftPercent":14,"caveat":"A population-level statistical estimate derived from WHO alcohol dose-response mortality research, not a personal medical risk assessment."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/income-percentile":{"get":{"summary":"Estimate where a household's income ranks globally and within its own country.","tags":["Income & Wealth"],"description":"Estimate where a household's income ranks globally and within its own country. Use this when a user asks how rich they are compared to their country or the world — a common curiosity question. Returns global percentile, within-country percentile, and equivalent income needed in the world's highest-median-income countries. PPP-adjusted, modelled from curated median-income and Gini data. Example: \"What percentile is an $85,000 household income in for a family of 3 in Canada?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"annualIncome","required":true,"description":"Total annual household income. Example: 85000"},{"schema":{"type":"string"},"in":"query","name":"currency","required":true,"description":"ISO 4217 currency code (informational — figure should already be PPP-adjusted). Example: \"CAD\""},{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"CAN\""},{"schema":{"type":"string"},"in":"query","name":"householdSize","required":true,"description":"Number of people the income supports; used to derive per-capita income. Example: 3"}],"responses":{"200":{"description":"Global and within-country income percentile for a household, plus the income needed to reach the same percentile in the world's highest-median-income countries.","content":{"application/json":{"schema":{"type":"object","description":"Global and within-country income percentile for a household, plus the income needed to reach the same percentile in the world's highest-median-income countries.","properties":{"result":{"type":"object","description":"The income-percentile computation.","properties":{"perCapitaIncomePPP":{"type":"number","description":"Annual income divided by household size, in PPP terms. Example: 28333"},"globalPercentile":{"type":"number","description":"Percentile this per-capita income ranks at across the world's population. Example: 84.5"},"withinCountryPercentile":{"type":"number","description":"Percentile this per-capita income ranks at within the given country. Example: 46.2"},"richerThanPercent":{"type":"number","description":"Alias of globalPercentile, phrased for display. Example: 84.5"},"equivalentIncomeInTopCountries":{"type":"array","description":"The three highest-median-income countries and their median PPP income, for comparison.","items":{"type":"object","properties":{"country":{"type":"string","description":"Country name. Example: \"Singapore\""},"medianIncomePPP":{"type":"number","description":"Median per-capita PPP income for that country. Example: 62000"}}}},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"CanadianHouseholdOf3":{"summary":"Income percentile for an $85,000 CAD household income, family of 3, in Canada","value":{"result":{"perCapitaIncomePPP":28333,"globalPercentile":84.5,"withinCountryPercentile":46.2,"richerThanPercent":84.5,"equivalentIncomeInTopCountries":[{"country":"Singapore","medianIncomePPP":62000},{"country":"United Arab Emirates","medianIncomePPP":60000},{"country":"Saudi Arabia","medianIncomePPP":46000}],"caveat":"Illustrative estimate modelling each country's income distribution as log-normal from its median PPP income and Gini coefficient, weighted across 52 curated countries covering roughly 78% of world population — not an official World Bank PIP percentile lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/wealth-percentile":{"get":{"summary":"Estimate where net worth ranks globally and within its own country.","tags":["Income & Wealth"],"description":"Estimate where net worth ranks globally and within its own country. Use this when a user wants to know how wealthy they are compared to their country or the world. Returns global wealth percentile, within-country percentile, and wealth tier (bottom 50% / middle 40% / top 10% / top 1%). Modelled from curated median-wealth and Gini data (UBS/Credit Suisse Global Wealth Report style). Example: \"What percentile is a $500,000 net worth in the US?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"netWorth","required":true,"description":"Total assets minus debts, in USD. Example: 500000"},{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"USA\""}],"deprecated":true,"responses":{"200":{"description":"Where a net worth ranks globally and within its own country, plus a wealth tier.","content":{"application/json":{"schema":{"type":"object","description":"Where a net worth ranks globally and within its own country, plus a wealth tier.","properties":{"result":{"type":"object","description":"The wealth-percentile computation.","properties":{"globalWealthPercentile":{"type":"number","description":"Percentile this net worth ranks at across the world's adult population. Example: 97"},"withinCountryPercentile":{"type":"number","description":"Percentile this net worth ranks at within the given country. Example: 77.6"},"wealthTier":{"type":"string","description":"Wealth tier this percentile falls into. Example: \"top10\"","enum":["bottom50","middle40","top10","top1"]},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}},"deprecation":{"type":"object","description":"Present only on deprecated endpoints. States when the endpoint stops serving and why. See the Deprecation and Sunset response headers (RFC 8594).","properties":{"sunset":{"type":"string","description":"ISO date after which this endpoint stops serving. Example: \"2027-02-28\""},"reason":{"type":"string","description":"Why the endpoint is being withdrawn."},"replacement":{"type":["null","string"],"description":"Path of a replacement endpoint, or null where there is none."}}}}},"examples":{"UsFiveHundredThousand":{"summary":"Wealth percentile for a $500,000 net worth in the US","value":{"result":{"globalWealthPercentile":97,"withinCountryPercentile":77.6,"wealthTier":"top10","caveat":"Illustrative estimate modelling each country's wealth distribution as log-normal from its median wealth-per-adult and Gini coefficient (UBS/Credit Suisse Global Wealth Report style), weighted across 52 curated countries covering roughly 78% of world adult population — not an official decile lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/carbon-footprint":{"get":{"summary":"Estimate annual carbon footprint from flights, car use, diet, and home energy, using country-specific electricity grid intensity.","tags":["Global"],"description":"Estimate annual carbon footprint from flights, car use, diet, and home energy, using country-specific electricity grid intensity. Use this when a user wants to know their personal carbon footprint and how it compares to their country's average. Returns total tCO2e/year, a category breakdown, and comparison to the national per-capita average. Example: \"What is my annual carbon footprint if I live in the UK, take 2 short-haul and 1 long-haul flight a year, drive a petrol car 10,000km a year, eat an omnivore diet, and use 300 kWh of electricity a month?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"GBR\""},{"schema":{"type":"string"},"in":"query","name":"flightsShortHaulPerYear","required":true,"description":"Number of short-haul flights (under ~1500km) per year. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"flightsLongHaulPerYear","required":true,"description":"Number of long-haul flights (over ~1500km) per year. Example: 1"},{"schema":{"type":"string","enum":["petrol","diesel","hybrid","electric","none"]},"in":"query","name":"carType","required":true,"description":"Type of car driven, or \"none\". Example: \"petrol\""},{"schema":{"type":"string"},"in":"query","name":"annualCarKm","required":true,"description":"Kilometres driven per year. Example: 10000"},{"schema":{"type":"string","enum":["vegan","vegetarian","omnivore","heavyMeat"]},"in":"query","name":"diet","required":true,"description":"Typical diet type. Example: \"omnivore\""},{"schema":{"type":"string"},"in":"query","name":"homeEnergyKwhPerMonth","required":true,"description":"Home electricity consumption in kWh per month. Example: 300"}],"responses":{"200":{"description":"Estimated annual carbon footprint broken down by category, plus comparison to the country's per-capita average.","content":{"application/json":{"schema":{"type":"object","description":"Estimated annual carbon footprint broken down by category, plus comparison to the country's per-capita average.","properties":{"result":{"type":"object","description":"The carbon footprint result.","properties":{"totalTonnesCo2ePerYear":{"type":"number","description":"Total estimated annual footprint in tonnes CO2e. Example: 6.45"},"breakdown":{"type":"array","description":"Footprint broken down by category.","items":{"type":"object","properties":{"category":{"type":"string","description":"Category name. Example: \"Flights\""},"tonnesCo2e":{"type":"number","description":"Tonnes CO2e for this category. Example: 1.6"}}}},"countryAveragePerCapitaTonnes":{"type":"number","description":"The country's average per-capita annual footprint in tonnes CO2e. Example: 5"},"vsCountryAverage":{"type":"number","description":"totalTonnesCo2ePerYear minus countryAveragePerCapitaTonnes — positive means above average. Example: 1.45"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UKOmnivoreCommuter":{"summary":"Annual footprint for a UK resident with a petrol car and omnivore diet","value":{"result":{"totalTonnesCo2ePerYear":6.45,"breakdown":[{"category":"Flights","tonnesCo2e":1.6},{"category":"Car","tonnesCo2e":1.7},{"category":"Diet","tonnesCo2e":2.5},{"category":"Home energy","tonnesCo2e":0.65}],"countryAveragePerCapitaTonnes":5,"vsCountryAverage":1.45,"caveat":"Illustrative estimate using average emission factors (IEA/Ember-style grid intensity, published flight and diet averages) — not a certified carbon audit."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/electricity-cost-by-country":{"get":{"summary":"Estimate a monthly electricity bill from usage and country.","tags":["Global"],"description":"Estimate a monthly electricity bill from usage and country. Use this when a user wants to know what their electricity usage would cost in a given country, e.g. when relocating or comparing living costs. Returns cost in USD and local currency (live exchange rate), and comparison to the national average bill. Example: \"What would a 350 kWh monthly electricity bill cost in Germany?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"monthlyKwh","required":true,"description":"Monthly electricity consumption in kWh. Example: 350"},{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"DEU\""}],"responses":{"200":{"description":"An estimated monthly electricity bill in USD and local currency, with comparison to the national average bill.","content":{"application/json":{"schema":{"type":"object","description":"An estimated monthly electricity bill in USD and local currency, with comparison to the national average bill.","properties":{"result":{"type":"object","description":"The electricity cost result.","properties":{"monthlyCostUSD":{"type":"number","description":"Estimated monthly cost in USD. Example: 122.5"},"monthlyCostLocal":{"type":"number","description":"Estimated monthly cost in the country's local currency. Example: 112.7"},"currencyCode":{"type":"string","description":"ISO 4217 currency code for monthlyCostLocal. Example: \"EUR\""},"countryAverageMonthlyCostUSD":{"type":"number","description":"The country's average monthly electricity bill in USD. Example: 87.5"},"vsCountryAverage":{"type":"number","description":"monthlyCostUSD minus countryAverageMonthlyCostUSD. Example: 35"},"pricePerKwhUSD":{"type":"number","description":"The country's residential price per kWh in USD. Example: 0.35"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"350kWhInGermany":{"summary":"A 350 kWh monthly electricity bill in Germany","value":{"result":{"monthlyCostUSD":122.5,"monthlyCostLocal":112.7,"currencyCode":"EUR","countryAverageMonthlyCostUSD":87.5,"vsCountryAverage":35,"pricePerKwhUSD":0.35,"caveat":"Illustrative estimate using curated average residential tariffs, converted at live exchange rates — not your actual utility bill, which varies by provider, tariff plan, and time of use."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/salary-by-degree":{"get":{"summary":"Estimate salary outlook for a degree field.","tags":["Income & Wealth"],"description":"Estimate salary outlook for a degree field. Use this when a user is choosing a major or career path and wants to know typical pay and job growth. Returns median salary, 25th/75th percentile, top related occupations with salaries, and 10-year job growth outlook. Curated from BLS Occupational Outlook Handbook-style data. Example: \"What is the salary outlook for a Computer Science degree with 5 years of experience?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"degreeField","required":true,"description":"Degree field. Example: \"Computer Science\""},{"schema":{"type":"string"},"in":"query","name":"yearsOfExperience","required":true,"description":"Years of professional experience. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"usState","required":false,"description":"Optional 2-letter US state code to apply a regional salary index. Example: \"CA\""}],"responses":{"200":{"description":"Salary outlook for a degree field: median and percentile salaries, related occupations, and 10-year job growth outlook.","content":{"application/json":{"schema":{"type":"object","description":"Salary outlook for a degree field: median and percentile salaries, related occupations, and 10-year job growth outlook.","properties":{"result":{"type":"object","description":"The salary-by-degree computation.","properties":{"occupationTitle":{"type":"string","description":"The primary occupation title associated with this degree field. Example: \"Software Developer\""},"medianSalary":{"type":"number","description":"Median salary for this field, adjusted for experience and (if provided) state. Example: 117000"},"p25Salary":{"type":"number","description":"25th percentile salary for this field. Example: 85500"},"p75Salary":{"type":"number","description":"75th percentile salary for this field. Example: 157500"},"tenYearGrowthOutlookPercent":{"type":"number","description":"Projected 10-year job growth outlook for this occupation. Example: 17"},"relatedOccupations":{"type":"array","description":"Related occupations and their median salaries.","items":{"type":"object","properties":{"title":{"type":"string","description":"Occupation title. Example: \"Data Scientist\""},"medianSalary":{"type":"number","description":"Median salary for that occupation. Example: 108000"}}}},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"ComputerScienceFiveYears":{"summary":"Salary outlook for Computer Science with 5 years of experience","value":{"result":{"occupationTitle":"Software Developer","medianSalary":117000,"p25Salary":85500,"p75Salary":157500,"tenYearGrowthOutlookPercent":17,"relatedOccupations":[{"title":"Data Scientist","medianSalary":108000},{"title":"IT Manager","medianSalary":169000},{"title":"Systems Analyst","medianSalary":102000}],"caveat":"Illustrative estimate curated from BLS Occupational Outlook Handbook-style national medians, adjusted for experience and (if provided) a state salary index — not an exact BLS lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/lifetime-earnings":{"get":{"summary":"Project total career earnings to age 65 based on education level.","tags":["Income & Wealth"],"description":"Project total career earnings to age 65 based on education level. Use this when a user wants to know how much they might earn over their career, or how much more a higher degree is worth. Returns total projected lifetime earnings, an earnings curve by age band, and the earnings premium vs a high-school-only baseline. Curated from BLS age-earnings-profile-style data. Example: \"What are the projected lifetime earnings for a 25-year-old with a bachelor's degree?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age (18+). Example: 25"},{"schema":{"type":"string","enum":["highSchool","associate","bachelor","master","doctoral"]},"in":"query","name":"educationLevel","required":true,"description":"Highest education level attained. Example: \"bachelor\""},{"schema":{"type":"string"},"in":"query","name":"field","required":false,"description":"Optional degree field to apply a field-specific pay multiplier. Example: \"Computer Science\""}],"responses":{"200":{"description":"Projected total career earnings to age 65, an earnings curve by age band, and the earnings premium vs a high-school-only baseline.","content":{"application/json":{"schema":{"type":"object","description":"Projected total career earnings to age 65, an earnings curve by age band, and the earnings premium vs a high-school-only baseline.","properties":{"result":{"type":"object","description":"The lifetime-earnings projection.","properties":{"projectedTotalEarningsTo65":{"type":"number","description":"Total projected earnings from the current age through age 65. Example: 3420000"},"earningsCurveByDecade":{"type":"array","description":"Projected annual earnings for each career age band.","items":{"type":"object","properties":{"ageBand":{"type":"string","description":"The age band label. Example: \"25-34\""},"annualEarnings":{"type":"number","description":"Projected annual earnings in that age band. Example: 72000"}}}},"premiumVsHighSchoolBaselinePercent":{"type":"number","description":"Percent by which projected total earnings exceed a high-school-only baseline. Example: 71.4"},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"Bachelor25YearOld":{"summary":"Lifetime earnings for a 25-year-old with a bachelor's degree","value":{"result":{"projectedTotalEarningsTo65":3420000,"earningsCurveByDecade":[{"ageBand":"18-24","annualEarnings":54000},{"ageBand":"25-34","annualEarnings":72000},{"ageBand":"35-44","annualEarnings":86400},{"ageBand":"45-54","annualEarnings":93600},{"ageBand":"55-64","annualEarnings":90000}],"premiumVsHighSchoolBaselinePercent":71.4,"caveat":"Illustrative estimate curated from BLS age-earnings-profile-style data, assuming continuous full-time employment to age 65 with no unemployment, career breaks, or below-median years — not a personal financial projection."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/national-income-percentile":{"get":{"summary":"Estimate where an annual income ranks within its own country.","tags":["Income & Wealth"],"description":"Estimate where an annual income ranks within its own country. Use this when a user wants to know how their income compares specifically to others in their own country. Returns percentile, decile, quintile, position relative to the national median, and income class (low/middle/high). Interpolated from curated decile thresholds. Example: \"What percentile is a $75,000 income in for India?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"IND\""},{"schema":{"type":"string"},"in":"query","name":"annualIncome","required":true,"description":"Annual income in the country's PPP-equivalent terms. Example: 75000"}],"responses":{"200":{"description":"Where an annual income ranks within its own country: percentile, decile, quintile, position vs the national median, and income class.","content":{"application/json":{"schema":{"type":"object","description":"Where an annual income ranks within its own country: percentile, decile, quintile, position vs the national median, and income class.","properties":{"result":{"type":"object","description":"The national-income-percentile computation.","properties":{"percentile":{"type":"number","description":"Percentile this income ranks at within the country. Example: 99.5"},"decile":{"type":"number","description":"Decile (1-10) this income falls into. Example: 10"},"quintile":{"type":"number","description":"Quintile (1-5) this income falls into. Example: 5"},"vsNationalMedianPercent":{"type":"number","description":"Percent by which this income is above or below the national median. Example: 1263.6"},"incomeClass":{"type":"string","description":"Income class this percentile falls into. Example: \"high\"","enum":["low","middle","high"]},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","description":"The kind of calculation performed. Example: \"interpolated\""},"confidence":{"type":"string","description":"Confidence level in the estimate. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"IndiaSeventyFiveThousand":{"summary":"Percentile for a $75,000 PPP-equivalent income in India","value":{"result":{"percentile":99.5,"decile":10,"quintile":5,"vsNationalMedianPercent":1263.6,"incomeClass":"high","caveat":"Illustrative estimate interpolated from curated decile thresholds, not an official national statistics office percentile lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"interpolated","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ppp-salary-converter":{"get":{"summary":"Convert a salary from one country to its purchasing-power-equivalent in another.","tags":["Finance"],"description":"Convert a salary from one country to its purchasing-power-equivalent in another. Use this when a user is evaluating a job offer or move abroad and wants to know if their salary would go further or less far. Returns PPP-equivalent salary, live-FX-converted salary, and the purchasing-power gain or loss percentage between the two. Example: \"Convert a $120,000 US salary to its purchasing-power equivalent in Portugal.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 origin country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"salary","required":true,"description":"Annual salary in the origin country's local currency. Example: 120000"},{"schema":{"type":"string"},"in":"query","name":"destinationCountry","required":true,"description":"ISO 3166-1 alpha-3 destination country code. Example: \"PRT\""}],"responses":{"200":{"description":"The salary's purchasing-power and live-FX equivalents in the destination country.","content":{"application/json":{"schema":{"type":"object","description":"The salary's purchasing-power and live-FX equivalents in the destination country.","properties":{"result":{"type":"object","description":"The PPP conversion result.","properties":{"intlDollarEquivalent":{"type":"number","description":"The origin salary expressed in international dollars. Example: 120000"},"pppEquivalentSalary":{"type":"number","description":"The salary in destination local currency needed to match the same purchasing power."},"fxConvertedSalary":{"type":"number","description":"The salary in destination local currency at the live market exchange rate."},"purchasingPowerGainLossPercent":{"type":"number","description":"Positive means the FX-converted amount buys more than the PPP-equivalent needs — i.e. purchasing power gained by moving."},"destinationCurrency":{"type":"string","description":"ISO 4217 currency code of the destination country. Example: \"EUR\""},"caveat":{"type":"string","description":"Note on data provenance and estimate accuracy."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint (PPP factor combined with a live exchange rate)."},"confidence":{"type":"string","description":"Confidence level in the estimate. Always \"medium\" for this endpoint."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsToPortugal":{"summary":"Convert a $120,000 US salary to its Portugal equivalent","value":{"result":{"intlDollarEquivalent":120000,"pppEquivalentSalary":69600,"fxConvertedSalary":103879.92,"purchasingPowerGainLossPercent":49.25,"destinationCurrency":"EUR","caveat":"Illustrative estimate using curated PPP conversion factors and a live exchange rate — not an official World Bank ICP lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/real-income-erosion":{"get":{"summary":"Calculate how much inflation has eroded an income's purchasing power between two years.","tags":["Finance"],"description":"Calculate how much inflation has eroded an income's purchasing power between two years. Use this when a user wants to know if a raise (or a static salary) actually kept up with inflation. Returns inflation-adjusted real income today, percent purchasing power lost, and the nominal amount needed today to match the original income. Example: \"How much has a $60,000 salary from 2015 lost to inflation by 2025 in the US?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"originalIncome","required":true,"description":"Income amount in startYear. Example: 60000"},{"schema":{"type":"string"},"in":"query","name":"startYear","required":true,"description":"Starting year (2000-2025). Example: 2015"},{"schema":{"type":"string"},"in":"query","name":"endYear","required":true,"description":"Ending year (2000-2025), must be after startYear. Example: 2025"}],"responses":{"200":{"description":"How much inflation eroded the income's purchasing power between the two years.","content":{"application/json":{"schema":{"type":"object","description":"How much inflation eroded the income's purchasing power between the two years.","properties":{"result":{"type":"object","description":"The erosion calculation.","properties":{"realIncomeToday":{"type":"number","description":"The original income deflated to endYear purchasing power. Example: 46871.34"},"percentPurchasingPowerLost":{"type":"number","description":"Percent of purchasing power lost between startYear and endYear."},"amountNeededToday":{"type":"number","description":"The nominal amount at endYear needed to match the original income's purchasing power."},"caveat":{"type":"string","description":"Note on data provenance and estimate accuracy."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"direct\" for this endpoint."},"confidence":{"type":"string","description":"Confidence level in the estimate. Always \"medium\" for this endpoint."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsSalary2015to2025":{"summary":"A $60,000 US salary from 2015, deflated to 2025","value":{"result":{"realIncomeToday":46871.34,"percentPurchasingPowerLost":21.88,"amountNeededToday":76806,"caveat":"Illustrative estimate using a curated CPI series (smooth compounding from each country's average inflation rate), not an official year-by-year CPI download."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cross-country-budget":{"get":{"summary":"See what a monthly spending budget from one country buys in another.","tags":["Global"],"description":"See what a monthly spending budget from one country buys in another. Use this when a user wants to know how their spending power would change if they moved abroad. Returns the PPP-equivalent local amount, live-FX-converted local amount, and the purchasing-power ratio between the two (above 1 means the budget stretches further than PPP parity). Example: \"What does a $3,000/month budget in the US buy in Thailand?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 origin country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"destinationCountry","required":true,"description":"ISO 3166-1 alpha-3 destination country code. Example: \"THA\""},{"schema":{"type":"string"},"in":"query","name":"monthlySpending","required":true,"description":"Monthly spending amount in the origin country's local currency. Example: 3000"}],"responses":{"200":{"description":"What a monthly spending budget from one country buys in another, both at PPP parity and at the live exchange rate.","content":{"application/json":{"schema":{"type":"object","description":"What a monthly spending budget from one country buys in another, both at PPP parity and at the live exchange rate.","properties":{"result":{"type":"object","description":"The cross-country budget result.","properties":{"intlDollarEquivalent":{"type":"number","description":"The budget converted to international (PPP) dollars. Example: 3000"},"pppEquivalentLocal":{"type":"number","description":"What the budget buys in the destination's local currency, at equivalent purchasing power. Example: 33000"},"fxConvertedLocal":{"type":"number","description":"The budget converted to the destination's local currency at the live market exchange rate. Example: 106500"},"purchasingPowerRatio":{"type":"number","description":"fxConvertedLocal / pppEquivalentLocal — above 1 means the budget stretches further than PPP parity. Example: 3.23"},"destinationCurrency":{"type":"string","description":"ISO 4217 currency code of the destination country. Example: \"THB\""},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"composite\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"USToThailand":{"summary":"What a $3,000/month US budget buys in Thailand","value":{"result":{"intlDollarEquivalent":3000,"pppEquivalentLocal":33000,"fxConvertedLocal":106500,"purchasingPowerRatio":3.23,"destinationCurrency":"THB","caveat":"Illustrative estimate using curated PPP conversion factors and a live exchange rate — not an official World Bank ICP lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/national-age-percentile":{"get":{"summary":"Find where an age ranks within a country's population.","tags":["Global"],"description":"Find where an age ranks within a country's population. Use this when a user wants to know how their age compares to others in their own country specifically (as opposed to globally). Returns percent younger, percent older, the national median age, and the gap between the given age and that median. Example: \"How does being 50 compare to the median age in Japan?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"JPN\""},{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years (0-110). Example: 50"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":false,"description":"Optional — omit for both sexes combined. Example: \"F\""}],"responses":{"200":{"description":"Where an age ranks within a country's population, with the national median age and the gap to it.","content":{"application/json":{"schema":{"type":"object","description":"Where an age ranks within a country's population, with the national median age and the gap to it.","properties":{"result":{"type":"object","description":"The national age percentile result.","properties":{"percentYounger":{"type":"number","description":"Percent of the national population younger than this age. Example: 51.9"},"percentOlder":{"type":"number","description":"Percent of the national population older than this age. Example: 48.1"},"nationalMedianAge":{"type":"number","description":"The country's median age. Example: 48.9"},"medianAgeGap":{"type":"number","description":"The given age minus nationalMedianAge. Example: 1.1"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"interpolated\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"Age50InJapan":{"summary":"How being 50 compares to Japan's median age","value":{"result":{"percentYounger":51.9,"percentOlder":48.1,"nationalMedianAge":48.9,"medianAgeGap":1.1,"caveat":"Illustrative estimate from a modelled age-pyramid shape calibrated to national population figures, not a direct UN WPP download."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"interpolated","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/global-age-percentile":{"get":{"summary":"Find where an age ranks globally among the world's population.","tags":["Global"],"description":"Find where an age ranks globally among the world's population. Use this when a user wants to know how many people worldwide are the same age as them, or older/younger. Returns the global percentile, an approximate global headcount at that age, and projected cohort size in 10 and 20 years accounting for mortality. Example: \"How many people in the world are older than me if I'm 45?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Age in years (0-110). Example: 45"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":false,"description":"Optional — omit for both sexes combined. Example: \"M\""}],"responses":{"200":{"description":"Where an age ranks globally, with an approximate global headcount and projected cohort size in 10 and 20 years.","content":{"application/json":{"schema":{"type":"object","description":"Where an age ranks globally, with an approximate global headcount and projected cohort size in 10 and 20 years.","properties":{"result":{"type":"object","description":"The global age percentile result.","properties":{"globalPercentile":{"type":"number","description":"Percentile of the world population younger than this age. Example: 75.8"},"approxCountGlobally":{"type":"number","description":"Approximate number of people worldwide at this exact age. Example: 72211545"},"projectedCohortIn10Years":{"type":"number","description":"Projected surviving cohort size 10 years from now. Example: 67272626"},"projectedCohortIn20Years":{"type":"number","description":"Projected surviving cohort size 20 years from now. Example: 57195624"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"modelled\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"Age45":{"summary":"Global ranking for a 45-year-old","value":{"result":{"globalPercentile":75.8,"approxCountGlobally":72211545,"projectedCohortIn10Years":67272626,"projectedCohortIn20Years":57195624,"caveat":"Illustrative estimate from modelled global age-pyramid and mortality curves covering a curated set of countries (~78% of world population), not a direct UN WPP download."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"modelled","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/survival-probability":{"get":{"summary":"Estimate the probability of reaching a target age from a current age, given country and sex.","tags":["Health & Life"],"description":"Estimate the probability of reaching a target age from a current age, given country and sex. Use this when a user wants to know their odds of living to a certain age, based on population life tables. Returns survival probability, expected remaining years, and a note on whether life expectancy has been improving or declining. Example: \"What are the odds of a 40-year-old woman in Japan living to 90?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"JPN\""},{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age (0-100). Example: 40"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex. Example: \"F\""},{"schema":{"type":"string"},"in":"query","name":"targetAge","required":true,"description":"Target age to evaluate (must be >= currentAge, <= 100). Example: 90"}],"responses":{"200":{"description":"Probability of reaching the target age from the current age, plus expected remaining years and a life-expectancy trend note.","content":{"application/json":{"schema":{"type":"object","description":"Probability of reaching the target age from the current age, plus expected remaining years and a life-expectancy trend note.","properties":{"result":{"type":"object","description":"The survival probability result.","properties":{"probabilityOfReachingTargetAgePercent":{"type":"number","description":"Probability of surviving from currentAge to targetAge, as a percentage. Example: 46.7"},"expectedRemainingYears":{"type":"number","description":"Expected remaining years of life from the current age. Example: 48.1"},"comparisonNote":{"type":"string","description":"General note on whether the country's life expectancy has recently trended up or down."},"caveat":{"type":"string","description":"Disclaimer about the modelled, illustrative nature of the estimate."}}},"meta":{"type":"object","description":"Response metadata.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Always \"modelled\" for this endpoint.","enum":["direct","interpolated","modelled","composite"]},"confidence":{"type":"string","description":"Confidence level in the estimate. Always \"medium\" for this endpoint.","enum":["high","medium","low"]}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"FortyYearOldWomanJapanToNinety":{"summary":"40-year-old woman in Japan, odds of reaching age 90","value":{"result":{"probabilityOfReachingTargetAgePercent":46.7,"expectedRemainingYears":48.1,"comparisonNote":"Life expectancy in Japan has generally trended upward over the past decade, consistent with the broader global pattern.","caveat":"Illustrative estimate from a Gompertz mortality curve calibrated to national life-expectancy figures, not an official WHO/UN abridged life table. The comparison note is a general historical statement, not a computed decade-over-decade figure."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"modelled","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cohort-size":{"get":{"summary":"Estimate the size of a birth-year cohort, accounting for mortality.","tags":["Global"],"description":"Estimate the size of a birth-year cohort, accounting for mortality. Use this when a user wants to know how many people born in a given year are still alive today, or how many are projected to survive to a future age. Returns size at birth, estimated surviving size today, and projected size at age 65 and 80. Example: \"How many people born in the UK in 1990 are still alive today?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"birthYear","required":true,"description":"Birth year (must put current age between 0 and 100). Example: 1990"},{"schema":{"type":"string"},"in":"query","name":"country","required":false,"description":"ISO 3166-1 alpha-3 country code — omit for the world total. Example: \"GBR\""},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":false,"description":"Optional — omit for both sexes combined. Example: \"F\""}],"responses":{"200":{"description":"Estimated size of a birth-year cohort at birth, surviving today, and projected to ages 65 and 80.","content":{"application/json":{"schema":{"type":"object","description":"Estimated size of a birth-year cohort at birth, surviving today, and projected to ages 65 and 80.","properties":{"result":{"type":"object","description":"The cohort size result.","properties":{"currentAge":{"type":"number","description":"Current age of the cohort, derived from birthYear. Example: 36"},"estimatedCohortSizeAtBirth":{"type":"number","description":"Estimated number of people born in that year and country. Example: 1183598"},"estimatedSurvivingCohortToday":{"type":"number","description":"Estimated number of that cohort still alive today. Example: 1162543"},"projectedSizeAtAge65":{"type":"number","description":"Projected surviving cohort size at age 65. Example: 1006307"},"projectedSizeAtAge80":{"type":"number","description":"Projected surviving cohort size at age 80. Example: 671346"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"composite\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"low\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UK1990Cohort":{"summary":"People born in the UK in 1990, still alive today","value":{"result":{"currentAge":36,"estimatedCohortSizeAtBirth":1183598,"estimatedSurvivingCohortToday":1162543,"projectedSizeAtAge65":1006307,"projectedSizeAtAge80":671346,"caveat":"Illustrative estimate combining a modelled age-pyramid snapshot with a Gompertz mortality curve, not an official birth-registry or UN WPP cohort figure."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"low"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/national-salary-percentile":{"get":{"summary":"Estimate where a gross annual salary ranks within its own country.","tags":["Income & Wealth"],"description":"Estimate where a gross annual salary ranks within its own country. Use this when a user wants to know how their salary compares to the national wage distribution. Returns percentile, multiple of the mean wage, and multiple of the minimum wage (null where no statutory minimum exists). Example: \"What percentile is a £55,000 salary in the UK?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"GBR\""},{"schema":{"type":"string"},"in":"query","name":"grossAnnualSalary","required":true,"description":"Gross annual salary in the country's local currency. Example: 55000"}],"responses":{"200":{"description":"Where a gross annual salary ranks within its own country's wage distribution, plus multiples of the mean and minimum wage.","content":{"application/json":{"schema":{"type":"object","description":"Where a gross annual salary ranks within its own country's wage distribution, plus multiples of the mean and minimum wage.","properties":{"result":{"type":"object","description":"The national-salary-percentile computation.","properties":{"percentile":{"type":"number","description":"Percentile this salary ranks at within the country's earnings distribution. Example: 84.3"},"multipleOfMeanWage":{"type":"number","description":"This salary as a multiple of the country's mean annual wage. Example: 1.6"},"multipleOfMinWage":{"type":["null","number"],"description":"This salary as a multiple of the country's statutory minimum wage, or null where no statutory minimum exists. Example: 1.9"},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","description":"The kind of calculation performed. Example: \"interpolated\""},"confidence":{"type":"string","description":"Confidence level in the estimate. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UkFiftyFiveThousand":{"summary":"Percentile for a £55,000 salary in the UK","value":{"result":{"percentile":84.3,"multipleOfMeanWage":1.6,"multipleOfMinWage":1.9,"caveat":"Illustrative estimate interpolated from curated ILOSTAT-style earnings percentiles, not an official national statistics office lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"interpolated","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cross-country-equivalent-salary":{"get":{"summary":"Find the salary needed in a destination country for equivalent purchasing power to a salary in the origin country.","tags":["Income & Wealth"],"description":"Find the salary needed in a destination country for equivalent purchasing power to a salary in the origin country. Use this when a user is evaluating a job offer or relocation abroad and wants to know what salary would keep their standard of living the same. Returns the equivalent salary needed, local percentile in the destination, and purchasing-power gain/loss vs a live FX conversion. Example: \"What salary would I need in Germany to match the purchasing power of $120,000 in the US?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 origin country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"currentSalary","required":true,"description":"Current annual salary in the origin country's local currency. Example: 120000"},{"schema":{"type":"string"},"in":"query","name":"destinationCountry","required":true,"description":"ISO 3166-1 alpha-3 destination country code. Example: \"DEU\""}],"responses":{"200":{"description":"The equivalent salary needed in the destination country for the same purchasing power as the origin salary, plus local percentile and purchasing-power comparison vs a live FX conversion.","content":{"application/json":{"schema":{"type":"object","description":"The equivalent salary needed in the destination country for the same purchasing power as the origin salary, plus local percentile and purchasing-power comparison vs a live FX conversion.","properties":{"result":{"type":"object","description":"The equivalent-salary computation.","properties":{"equivalentSalaryNeeded":{"type":"number","description":"Salary needed in the destination country's local currency for equal purchasing power. Example: 93600"},"localPercentileInDestination":{"type":"number","description":"Percentile that equivalent salary ranks at within the destination country's earnings distribution. Example: 99.5"},"purchasingPowerGainLossPercent":{"type":"number","description":"Percent by which a live FX-converted salary over/undershoots the PPP-equivalent salary. Example: 10.98"},"destinationCurrency":{"type":"string","description":"ISO 4217 currency code of the destination country. Example: \"EUR\""},"caveat":{"type":"string","description":"Notes on the illustrative, curated nature of the estimate."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","description":"The kind of calculation performed. Example: \"composite\""},"confidence":{"type":"string","description":"Confidence level in the estimate. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsToGermany":{"summary":"Equivalent salary in Germany for $120,000 in the US","value":{"result":{"equivalentSalaryNeeded":93600,"localPercentileInDestination":99.5,"purchasingPowerGainLossPercent":10.98,"destinationCurrency":"EUR","caveat":"Illustrative estimate combining curated PPP conversion factors, curated earnings percentiles, and a live exchange rate — not an official lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/working-hours-comparison":{"get":{"summary":"Compare weekly working hours to national and OECD averages.","tags":["Global"],"description":"Compare weekly working hours to national and OECD averages. Use this when a user wants to know if they work more or less than typical for their country, or vs the OECD average. Returns annual hours, annual working days, and percent above/below the national and OECD (1,726 hrs/yr) averages. Example: \"How do my 45-hour work weeks compare to the average in Germany?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"DEU\""},{"schema":{"type":"string"},"in":"query","name":"weeklyHours","required":true,"description":"Hours worked per week. Example: 45"}],"responses":{"200":{"description":"Weekly working hours converted to annual hours and working days, compared to the national and OECD averages.","content":{"application/json":{"schema":{"type":"object","description":"Weekly working hours converted to annual hours and working days, compared to the national and OECD averages.","properties":{"result":{"type":"object","description":"The working hours comparison result.","properties":{"annualHours":{"type":"number","description":"weeklyHours multiplied by 52. Example: 2340"},"annualWorkingDays":{"type":"number","description":"annualHours divided by an 8-hour working day. Example: 292.5"},"percentVsNationalAverage":{"type":"number","description":"Percent above (positive) or below (negative) the national average annual hours. Example: 74.6"},"percentVsOecdAverage":{"type":"number","description":"Percent above (positive) or below (negative) the OECD average of 1,726 hrs/yr. Example: 35.6"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"45HourWeekInGermany":{"summary":"45-hour work weeks compared to Germany's average","value":{"result":{"annualHours":2340,"annualWorkingDays":292.5,"percentVsNationalAverage":74.6,"percentVsOecdAverage":35.6,"caveat":"Illustrative estimate using curated ILOSTAT-style annual hours figures, not an official year-specific lookup."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/house-price-to-income":{"get":{"summary":"Assess housing affordability using the price-to-income ratio (property price divided by gross annual household income).","tags":["Finance"],"description":"Assess housing affordability using the price-to-income ratio (property price divided by gross annual household income). Use this when a user wants to know if a property is affordable relative to their income, or wants a standard affordability benchmark. Returns the ratio, years of income required, and an affordability classification (affordable ≤3x, stretched 3-5x, unaffordable 5-8x, severely unaffordable >8x). Example: \"Is a $450,000 house affordable on a $90,000 household income?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"propertyPrice","required":true,"description":"Property purchase price. Example: 450000"},{"schema":{"type":"string"},"in":"query","name":"grossAnnualHouseholdIncome","required":true,"description":"Gross annual household income. Example: 90000"},{"schema":{"type":"string"},"in":"query","name":"country","required":false,"description":"Optional — display label only, not used in the calculation. Example: \"USA\""}],"responses":{"200":{"description":"The price-to-income ratio and an affordability classification.","content":{"application/json":{"schema":{"type":"object","description":"The price-to-income ratio and an affordability classification.","properties":{"result":{"type":"object","description":"House-price-to-income results.","properties":{"priceToIncomeRatio":{"type":"number","description":"Property price divided by gross annual household income. Example: 5"},"yearsOfIncomeRequired":{"type":"number","description":"Years of gross income required to buy the property (same value as priceToIncomeRatio). Example: 5"},"affordabilityClass":{"type":"string","enum":["affordable","stretched","unaffordable","severelyUnaffordable"],"description":"Standard affordability bucket for the computed ratio. Example: \"stretched\""},"caveat":{"type":"string","description":"Explanation of the affordability benchmark used."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","enum":["direct","interpolated","modelled","composite"],"description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence level in the result. Example: \"high\""}}}}},"examples":{"450kOn90kIncome":{"summary":"$450,000 house on a $90,000 household income","value":{"result":{"priceToIncomeRatio":5,"yearsOfIncomeRequired":5,"affordabilityClass":"stretched","caveat":"Standard price-to-income affordability benchmark (≤3× affordable, 3-5× stretched, 5-8× unaffordable, >8× severely unaffordable) — a rule of thumb, not a lending decision."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/max-affordable-property":{"get":{"summary":"Work out the maximum property a buyer can afford given their income and deposit.","tags":["Finance"],"description":"Work out the maximum property a buyer can afford given their income and deposit. Use this when a user wants to know their budget before house-hunting. Returns max monthly payment, max loan amount, max property price, and loan-to-value percentage. Example: \"What's the maximum property I can afford with a $6,000 monthly income, $50,000 deposit, at 6.5% over 30 years?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"monthlyGrossIncome","required":true,"description":"Gross monthly income. Example: 6000"},{"schema":{"type":"string"},"in":"query","name":"depositAvailable","required":true,"description":"Deposit / down payment available. Example: 50000"},{"schema":{"type":"string"},"in":"query","name":"interestRate","required":true,"description":"Annual interest rate, %. Example: 6.5"},{"schema":{"type":"string"},"in":"query","name":"termYears","required":true,"description":"Loan term in years. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"maxPaymentRatio","required":false,"description":"Max fraction of monthly gross income to spend on the payment (default 0.35). Example: 0.35"}],"responses":{"200":{"description":"The maximum affordable payment, loan amount, and property price given income, deposit, and rate.","content":{"application/json":{"schema":{"type":"object","description":"The maximum affordable payment, loan amount, and property price given income, deposit, and rate.","properties":{"result":{"type":"object","description":"Max affordable property results.","properties":{"maxMonthlyPayment":{"type":"number","description":"Maximum monthly payment given maxPaymentRatio of gross income. Example: 2100"},"maxLoan":{"type":"number","description":"Maximum loan amount supportable at that payment. Example: 332242.72"},"maxPropertyPrice":{"type":"number","description":"Maximum property price (max loan plus deposit). Example: 382242.72"},"ltvPercent":{"type":"number","description":"Loan-to-value ratio at the max property price, as a percentage. Example: 86.92"},"caveat":{"type":"string","description":"Disclaimer that this is affordability math, not a lending decision."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","enum":["direct","interpolated","modelled","composite"],"description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence level in the result. Example: \"high\""}}}}},"examples":{"SixKIncome":{"summary":"$6,000 monthly income, $50,000 deposit, 6.5% over 30 years","value":{"result":{"maxMonthlyPayment":2100,"maxLoan":332242.72,"maxPropertyPrice":382242.72,"ltvPercent":86.92,"caveat":"Pure affordability math based on your inputs — not a mortgage pre-approval or lending decision, which also weighs credit history and other debts."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/mortgage-stress-test":{"get":{"summary":"Stress-test a mortgage payment at the current rate plus 0/1/2/3 percentage points.","tags":["Finance"],"description":"Stress-test a mortgage payment at the current rate plus 0/1/2/3 percentage points. Use this when a user wants to know if they could still afford their mortgage if interest rates rose. Returns payment and income ratio at each rate scenario, and which scenario first breaches a 35% income-ratio threshold. Example: \"Can I still afford a $400,000 mortgage at 6.5% over 30 years with a $8,000 monthly income if rates rise 2 points?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"loanAmount","required":true,"description":"Loan principal. Example: 400000"},{"schema":{"type":"string"},"in":"query","name":"currentRate","required":true,"description":"Current annual interest rate, %. Example: 6.5"},{"schema":{"type":"string"},"in":"query","name":"termYears","required":true,"description":"Loan term in years. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"monthlyGrossIncome","required":true,"description":"Gross monthly income. Example: 8000"}],"responses":{"200":{"description":"Mortgage payment and income-ratio scenarios at the current rate plus 0/1/2/3 percentage points.","content":{"application/json":{"schema":{"type":"object","description":"Mortgage payment and income-ratio scenarios at the current rate plus 0/1/2/3 percentage points.","properties":{"result":{"type":"object","description":"Mortgage stress test results.","properties":{"scenarios":{"type":"array","description":"One entry per rate-bump scenario.","items":{"type":"object","properties":{"ratePercent":{"type":"number","description":"Interest rate for this scenario, as a percentage. Example: 6.5"},"bumpPp":{"type":"number","description":"Percentage points added to the current rate for this scenario. Example: 0"},"monthlyPayment":{"type":"number","description":"Monthly payment at this rate. Example: 2528.27"},"incomeRatioPercent":{"type":"number","description":"Payment as a percentage of gross monthly income. Example: 31.6"},"breaches35PercentThreshold":{"type":"boolean","description":"Whether this scenario exceeds the 35% income-ratio affordability threshold."}}}},"firstBreachAtBumpPp":{"type":["null","number"],"description":"Smallest rate bump (pp) at which the 35% threshold is breached, or null if none breach. Example: 2"},"caveat":{"type":"string","description":"Explanation of the stress-test methodology and threshold."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","enum":["direct","interpolated","modelled","composite"],"description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence level in the result. Example: \"high\""}}}}},"examples":{"FourHundredKAt6_5":{"summary":"$400,000 loan at 6.5% over 30 years, $8,000 monthly income","value":{"result":{"scenarios":[{"ratePercent":6.5,"bumpPp":0,"monthlyPayment":2528.27,"incomeRatioPercent":31.6,"breaches35PercentThreshold":false},{"ratePercent":7.5,"bumpPp":1,"monthlyPayment":2796.86,"incomeRatioPercent":34.96,"breaches35PercentThreshold":false},{"ratePercent":8.5,"bumpPp":2,"monthlyPayment":3075.65,"incomeRatioPercent":38.45,"breaches35PercentThreshold":true},{"ratePercent":9.5,"bumpPp":3,"monthlyPayment":3363.42,"incomeRatioPercent":42.04,"breaches35PercentThreshold":true}],"firstBreachAtBumpPp":2,"caveat":"Stress-tests your payment at the current rate plus 0/1/2/3 percentage points, flagging where the payment would exceed 35% of gross income — a common lender affordability threshold, not a guarantee of approval."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/rental-yield":{"get":{"summary":"Calculate rental property investment returns.","tags":["Finance"],"description":"Calculate rental property investment returns. Use this when a user is evaluating a rental property purchase and wants to know its yield and profitability. Returns gross yield %, net yield %, price-to-rent ratio, break-even monthly rent, and annual net income. Example: \"What is the rental yield on a $300,000 property renting for $1,800/month with 5% vacancy?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"purchasePrice","required":true,"description":"Property purchase price. Example: 300000"},{"schema":{"type":"string"},"in":"query","name":"monthlyRent","required":true,"description":"Monthly rent charged. Example: 1800"},{"schema":{"type":"string"},"in":"query","name":"vacancyRatePercent","required":true,"description":"Expected vacancy rate, % (0-99). Example: 5"},{"schema":{"type":"string"},"in":"query","name":"annualMaintenance","required":true,"description":"Annual maintenance cost. Example: 2000"},{"schema":{"type":"string"},"in":"query","name":"purchaseCostsPercent","required":true,"description":"One-off purchase costs as a % of purchase price (fees, taxes). Example: 3"}],"responses":{"200":{"description":"Gross and net rental yield, price-to-rent ratio, and break-even rent for the property.","content":{"application/json":{"schema":{"type":"object","description":"Gross and net rental yield, price-to-rent ratio, and break-even rent for the property.","properties":{"result":{"type":"object","description":"Rental yield results.","properties":{"grossYieldPercent":{"type":"number","description":"Annual rent divided by purchase price, as a percentage, before vacancy/costs. Example: 7.2"},"netYieldPercent":{"type":"number","description":"Net annual income divided by total investment (price plus purchase costs), as a percentage. Example: 5.99"},"priceToRentRatio":{"type":"number","description":"Purchase price divided by annual gross rent. Example: 13.89"},"breakEvenMonthlyRent":{"type":"number","description":"Minimum monthly rent needed to cover annual maintenance, accounting for vacancy. Example: 175.44"},"annualNetIncome":{"type":"number","description":"Effective annual rent (after vacancy) minus annual maintenance. Example: 18520"},"caveat":{"type":"string","description":"Disclaimer that this excludes financing, taxes, and appreciation."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"calculationClass":{"type":"string","enum":["direct","interpolated","modelled","composite"],"description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence level in the result. Example: \"high\""}}}}},"examples":{"ThreeHundredKProperty":{"summary":"$300,000 property renting for $1,800/month with 5% vacancy","value":{"result":{"grossYieldPercent":7.2,"netYieldPercent":5.99,"priceToRentRatio":13.89,"breakEvenMonthlyRent":175.44,"annualNetIncome":18520,"caveat":"Pure rental-math estimate — excludes financing costs (mortgage interest), taxes, and capital appreciation."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/climate-similarity-finder":{"get":{"summary":"Find the top 10 countries with the most similar climate to a desired temperature range and rainfall profile.","tags":["Global"],"description":"Find the top 10 countries with the most similar climate to a desired temperature range and rainfall profile. Use this when a user is considering relocating or traveling somewhere with a climate they like, and wants concrete country suggestions. Returns, per country, mean annual temperature, annual rainfall, a 0-100 similarity score, and a trade-off note combining climate match, safety, and relative cost of living. Example: \"Which countries have a climate similar to Lisbon, with a moderate rainfall profile?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 country code, excluded from the results. Example: \"PRT\""},{"schema":{"type":"string"},"in":"query","name":"minTempC","required":true,"description":"Minimum desired annual mean temperature in °C. Example: 15"},{"schema":{"type":"string"},"in":"query","name":"maxTempC","required":true,"description":"Maximum desired annual mean temperature in °C. Example: 22"},{"schema":{"type":"string","enum":["dry","moderate","wet"]},"in":"query","name":"rainfallProfile","required":true,"description":"Desired rainfall profile. Example: \"moderate\""}],"deprecated":true,"responses":{"200":{"description":"The top 10 countries most similar to a desired temperature range and rainfall profile, each with a similarity score and a trade-off note.","content":{"application/json":{"schema":{"type":"object","description":"The top 10 countries most similar to a desired temperature range and rainfall profile, each with a similarity score and a trade-off note.","properties":{"result":{"type":"object","description":"The climate similarity result.","properties":{"matches":{"type":"array","description":"Up to 10 matching countries, sorted by similarity score descending.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"PER\""},"name":{"type":"string","description":"Country name. Example: \"Peru\""},"annualMeanTempC":{"type":"number","description":"Annual mean temperature in °C. Example: 19"},"annualRainfallMm":{"type":"number","description":"Annual rainfall in mm. Example: 700"},"rainfallProfile":{"type":"string","description":"This country's classified rainfall profile. Example: \"moderate\"","enum":["dry","moderate","wet"]},"similarityScore":{"type":"number","description":"0-100 similarity score against the requested temperature range and rainfall profile. Example: 98.5"},"tradeoffNote":{"type":"string","description":"A note combining climate match, safety, and relative cost of living. Example: \"Strong climate match, elevated safety, typically lower cost of living by PPP.\""}}}},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"composite\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}},"deprecation":{"type":"object","description":"Present only on deprecated endpoints. States when the endpoint stops serving and why. See the Deprecation and Sunset response headers (RFC 8594).","properties":{"sunset":{"type":"string","description":"ISO date after which this endpoint stops serving. Example: \"2027-02-28\""},"reason":{"type":"string","description":"Why the endpoint is being withdrawn."},"replacement":{"type":["null","string"],"description":"Path of a replacement endpoint, or null where there is none."}}}}},"examples":{"LisbonLikeModerate":{"summary":"Countries similar to Lisbon's climate with moderate rainfall","value":{"result":{"matches":[{"code":"PER","name":"Peru","annualMeanTempC":19,"annualRainfallMm":700,"rainfallProfile":"moderate","similarityScore":98.5,"tradeoffNote":"Strong climate match, elevated safety, typically lower cost of living by PPP."},{"code":"KEN","name":"Kenya","annualMeanTempC":20,"annualRainfallMm":700,"rainfallProfile":"moderate","similarityScore":95.4,"tradeoffNote":"Strong climate match, elevated safety, typically lower cost of living by PPP."},{"code":"ETH","name":"Ethiopia","annualMeanTempC":18,"annualRainfallMm":850,"rainfallProfile":"moderate","similarityScore":93.5,"tradeoffNote":"Strong climate match, elevated safety, typically lower cost of living by PPP."},{"code":"GRC","name":"Greece","annualMeanTempC":16,"annualRainfallMm":650,"rainfallProfile":"moderate","similarityScore":92,"tradeoffNote":"Strong climate match, safe safety, broadly similar cost of living by PPP."},{"code":"MEX","name":"Mexico","annualMeanTempC":21,"annualRainfallMm":800,"rainfallProfile":"moderate","similarityScore":91.2,"tradeoffNote":"Strong climate match, elevated safety, broadly similar cost of living by PPP."},{"code":"ZAF","name":"South Africa","annualMeanTempC":17,"annualRainfallMm":500,"rainfallProfile":"moderate","similarityScore":90.4,"tradeoffNote":"Strong climate match, elevated safety, typically lower cost of living by PPP."},{"code":"AUS","name":"Australia","annualMeanTempC":21,"annualRainfallMm":500,"rainfallProfile":"moderate","similarityScore":88.5,"tradeoffNote":"Strong climate match, very safe safety, typically higher cost of living by PPP."},{"code":"PAK","name":"Pakistan","annualMeanTempC":21,"annualRainfallMm":500,"rainfallProfile":"moderate","similarityScore":88.5,"tradeoffNote":"Strong climate match, elevated safety, typically lower cost of living by PPP."},{"code":"ISR","name":"Israel","annualMeanTempC":20,"annualRainfallMm":450,"rainfallProfile":"moderate","similarityScore":88.5,"tradeoffNote":"Strong climate match, moderate safety, typically higher cost of living by PPP."},{"code":"ESP","name":"Spain","annualMeanTempC":15,"annualRainfallMm":600,"rainfallProfile":"moderate","similarityScore":88.4,"tradeoffNote":"Strong climate match, safe safety, broadly similar cost of living by PPP."}],"caveat":"Illustrative estimate from curated national-average climate normals — large countries are represented by a single figure, which understates internal climate diversity."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/air-quality-index":{"get":{"summary":"Look up a country's annual PM2.5 air quality.","tags":["Global"],"description":"Look up a country's annual PM2.5 air quality. Use this when a user wants to know how polluted the air is in a country, or wants to compare it to another. Returns exceedance multiple over the WHO guideline (5 µg/m³), health risk classification, global percentile (lower = cleaner), the 10 cleanest countries, and an optional side-by-side comparison. Example: \"How polluted is the air in India compared to Germany?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"IND\""},{"schema":{"type":"string"},"in":"query","name":"compareCountry","required":false,"description":"Optional second ISO 3166-1 alpha-3 country code to compare against. Example: \"DEU\""}],"responses":{"200":{"description":"A country's PM2.5 air quality with WHO guideline exceedance, health risk classification, global percentile, the 10 cleanest countries, and an optional comparison country.","content":{"application/json":{"schema":{"type":"object","description":"A country's PM2.5 air quality with WHO guideline exceedance, health risk classification, global percentile, the 10 cleanest countries, and an optional comparison country.","properties":{"result":{"type":"object","description":"The air quality index result.","properties":{"country":{"type":"object","description":"Air quality detail for the requested country.","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"IND\""},"name":{"type":"string","description":"Country name. Example: \"India\""},"pm25Annual":{"type":"number","description":"Annual mean PM2.5 concentration in µg/m³. Example: 51"},"exceedanceMultiple":{"type":"number","description":"Multiple of the WHO guideline (5 µg/m³) this country's PM2.5 represents. Example: 10.2"},"healthRiskClassification":{"type":"string","description":"Health risk band. Example: \"Very Unhealthy\"","enum":["Good","Moderate","Unhealthy","Very Unhealthy","Hazardous"]},"globalPercentile":{"type":"number","description":"Percentile among covered countries by cleanliness — lower means cleaner. Example: 100"}}},"comparison":{"type":"object","description":"Air quality detail for compareCountry, in the same shape as country. Null if compareCountry was not provided.","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"DEU\""},"name":{"type":"string","description":"Country name. Example: \"Germany\""},"pm25Annual":{"type":"number","description":"Annual mean PM2.5 concentration in µg/m³. Example: 10"},"exceedanceMultiple":{"type":"number","description":"Multiple of the WHO guideline (5 µg/m³) this country's PM2.5 represents. Example: 2"},"healthRiskClassification":{"type":"string","description":"Health risk band. Example: \"Moderate\"","enum":["Good","Moderate","Unhealthy","Very Unhealthy","Hazardous"]},"globalPercentile":{"type":"number","description":"Percentile among covered countries by cleanliness — lower means cleaner. Example: 30.2"}}},"whoGuidelinePm25":{"type":"number","description":"The WHO guideline PM2.5 level in µg/m³ used as the baseline. Example: 5"},"top10Cleanest":{"type":"array","description":"The 10 countries with the lowest annual PM2.5.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"SWE\""},"name":{"type":"string","description":"Country name. Example: \"Sweden\""},"pm25Annual":{"type":"number","description":"Annual mean PM2.5 concentration in µg/m³. Example: 5"}}}},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"IndiaVsGermany":{"summary":"India's air quality compared to Germany","value":{"result":{"country":{"code":"IND","name":"India","pm25Annual":51,"exceedanceMultiple":10.2,"healthRiskClassification":"Very Unhealthy","globalPercentile":100},"comparison":{"code":"DEU","name":"Germany","pm25Annual":10,"exceedanceMultiple":2,"healthRiskClassification":"Moderate","globalPercentile":30.2},"whoGuidelinePm25":5,"top10Cleanest":[{"code":"SWE","name":"Sweden","pm25Annual":5},{"code":"NOR","name":"Norway","pm25Annual":5},{"code":"FIN","name":"Finland","pm25Annual":5},{"code":"ISL","name":"Iceland","pm25Annual":5},{"code":"CAN","name":"Canada","pm25Annual":6},{"code":"AUS","name":"Australia","pm25Annual":6},{"code":"NZL","name":"New Zealand","pm25Annual":6},{"code":"IRL","name":"Ireland","pm25Annual":7},{"code":"SGP","name":"Singapore","pm25Annual":7},{"code":"USA","name":"United States","pm25Annual":8}],"caveat":"Illustrative country-level PM2.5 aggregations approximating the WHO Global Air Quality Database, not a direct per-station download."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/electricity-carbon-intensity":{"get":{"summary":"Look up a country's electricity grid carbon intensity.","tags":["Global"],"description":"Look up a country's electricity grid carbon intensity. Use this when a user wants to know how clean a country's electricity is, or how their own usage translates into emissions. Returns gCO2/kWh, low-carbon generation share, rank among covered countries, optional personal annual kg CO2 from weekly usage, an EV equivalent (kg CO2/100km), and an optional side-by-side comparison. Example: \"How carbon-intensive is France's electricity grid compared to Germany's?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"FRA\""},{"schema":{"type":"string"},"in":"query","name":"compareCountry","required":false,"description":"Optional second ISO 3166-1 alpha-3 country code to compare against. Example: \"DEU\""},{"schema":{"type":"string"},"in":"query","name":"weeklyKwh","required":false,"description":"Optional personal weekly electricity usage in kWh. Example: 70"}],"responses":{"200":{"description":"A country's electricity grid carbon intensity, with an optional personal usage estimate, EV equivalent, and side-by-side comparison.","content":{"application/json":{"schema":{"type":"object","description":"A country's electricity grid carbon intensity, with an optional personal usage estimate, EV equivalent, and side-by-side comparison.","properties":{"result":{"type":"object","description":"The electricity carbon intensity result.","properties":{"country":{"type":"object","description":"Grid carbon intensity detail for the requested country.","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"FRA\""},"name":{"type":"string","description":"Country name. Example: \"France\""},"gridIntensityGCo2PerKwh":{"type":"number","description":"Grid carbon intensity in gCO2/kWh. Example: 50"},"lowCarbonSharePercent":{"type":"number","description":"Share of generation from low-carbon sources. Example: 95.8"},"rank":{"type":"number","description":"Rank among covered countries by grid intensity (1 = cleanest). Example: 5"},"personalAnnualKgCo2":{"type":"number","description":"Annual kg CO2 from the given weeklyKwh usage. Null if weeklyKwh was not provided. Example: 182"},"evEquivalentKgCo2Per100km":{"type":"number","description":"kg CO2 per 100km for an EV charged from this grid. Example: 0.9"}}},"comparison":{"type":"object","description":"Grid carbon intensity detail for compareCountry, in the same shape as country. Null if compareCountry was not provided.","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"DEU\""},"name":{"type":"string","description":"Country name. Example: \"Germany\""},"gridIntensityGCo2PerKwh":{"type":"number","description":"Grid carbon intensity in gCO2/kWh. Example: 350"},"lowCarbonSharePercent":{"type":"number","description":"Share of generation from low-carbon sources. Example: 53.9"},"rank":{"type":"number","description":"Rank among covered countries by grid intensity (1 = cleanest). Example: 25"},"personalAnnualKgCo2":{"type":"number","description":"Annual kg CO2 from the given weeklyKwh usage. Null if weeklyKwh was not provided. Example: 1274"},"evEquivalentKgCo2Per100km":{"type":"number","description":"kg CO2 per 100km for an EV charged from this grid. Example: 6.3"}}},"totalCountriesCovered":{"type":"number","description":"Total number of countries in the underlying dataset. Example: 52"},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"direct\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"FranceVsGermany":{"summary":"France's electricity grid compared to Germany's, with 70 kWh/week personal usage","value":{"result":{"country":{"code":"FRA","name":"France","gridIntensityGCo2PerKwh":50,"lowCarbonSharePercent":95.8,"rank":5,"personalAnnualKgCo2":182,"evEquivalentKgCo2Per100km":0.9},"comparison":{"code":"DEU","name":"Germany","gridIntensityGCo2PerKwh":350,"lowCarbonSharePercent":53.9,"rank":25,"personalAnnualKgCo2":1274,"evEquivalentKgCo2Per100km":6.3},"totalCountriesCovered":52,"caveat":"Illustrative curated estimate approximating IEA/Ember-style grid intensity, not exact published year-specific figures."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"direct","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/country-safety-composite":{"post":{"summary":"Look up a composite safety score for a country, optionally compared against up to 4 others.","tags":["Global"],"description":"Look up a composite safety score for a country, optionally compared against up to 4 others. Use this when a user asks how safe a country is, or wants to compare safety between destinations. Returns homicide rate per 100k, rule of law and political stability percentiles, corruption score, a 0-100 composite safety score, classification (Very Safe/Safe/Moderate/Elevated/High Risk), and global rank. Example: \"How does Japan's safety compare to the US, UK, and Mexico?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"JPN\""},"compareCountries":{"type":"array","items":{"type":"string"},"description":"Optional array of up to 4 ISO 3166-1 alpha-3 country codes to compare against. Example: [\"USA\", \"GBR\", \"MEX\"]"}},"required":["country"]}}}},"responses":{"200":{"description":"A composite safety score for a country, with optional side-by-side comparisons against up to 4 other countries.","content":{"application/json":{"schema":{"type":"object","description":"A composite safety score for a country, with optional side-by-side comparisons against up to 4 other countries.","properties":{"result":{"type":"object","description":"The country safety composite result.","properties":{"country":{"type":"object","description":"Safety detail for the requested country.","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"JPN\""},"name":{"type":"string","description":"Country name. Example: \"Japan\""},"homicideRatePer100k":{"type":"number","description":"Homicide rate per 100,000 population. Example: 0.2"},"ruleOfLawPct":{"type":"number","description":"Rule of law percentile rank. Example: 90"},"politicalStabilityPct":{"type":"number","description":"Political stability percentile rank. Example: 86"},"corruptionScore":{"type":"number","description":"Corruption control score. Example: 73"},"compositeSafetyScore":{"type":"number","description":"0-100 composite safety score. Example: 89.3"},"classification":{"type":"string","description":"Safety classification. Example: \"Very Safe\"","enum":["Very Safe","Safe","Moderate","Elevated","High Risk"]},"globalRank":{"type":"number","description":"Rank among covered countries by composite safety score (1 = safest). Example: 11"}}},"comparisons":{"type":"array","description":"Safety detail for each requested compareCountries entry, in the same shape as country.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"USA\""},"name":{"type":"string","description":"Country name. Example: \"United States\""},"homicideRatePer100k":{"type":"number","description":"Homicide rate per 100,000 population. Example: 6.5"},"ruleOfLawPct":{"type":"number","description":"Rule of law percentile rank. Example: 80"},"politicalStabilityPct":{"type":"number","description":"Political stability percentile rank. Example: 55"},"corruptionScore":{"type":"number","description":"Corruption control score. Example: 69"},"compositeSafetyScore":{"type":"number","description":"0-100 composite safety score. Example: 74.2"},"classification":{"type":"string","description":"Safety classification. Example: \"Safe\"","enum":["Very Safe","Safe","Moderate","Elevated","High Risk"]},"globalRank":{"type":"number","description":"Rank among covered countries by composite safety score (1 = safest). Example: 26"}}}},"totalCountriesCovered":{"type":"number","description":"Total number of countries in the underlying dataset. Example: 53"},"caveat":{"type":"string","description":"Explanation of the data source, its limitations, and the composite score formula."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"composite\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"medium\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"JapanVsUsGbMx":{"summary":"Japan's safety compared to the US, UK, and Mexico","value":{"result":{"country":{"code":"JPN","name":"Japan","homicideRatePer100k":0.2,"ruleOfLawPct":90,"politicalStabilityPct":86,"corruptionScore":73,"compositeSafetyScore":89.3,"classification":"Very Safe","globalRank":11},"comparisons":[{"code":"USA","name":"United States","homicideRatePer100k":6.5,"ruleOfLawPct":80,"politicalStabilityPct":55,"corruptionScore":69,"compositeSafetyScore":74.2,"classification":"Safe","globalRank":26},{"code":"GBR","name":"United Kingdom","homicideRatePer100k":1.2,"ruleOfLawPct":92,"politicalStabilityPct":68,"corruptionScore":78,"compositeSafetyScore":85.6,"classification":"Very Safe","globalRank":16},{"code":"MEX","name":"Mexico","homicideRatePer100k":25,"ruleOfLawPct":22,"politicalStabilityPct":25,"corruptionScore":30,"compositeSafetyScore":32.4,"classification":"Elevated","globalRank":52}],"totalCountriesCovered":53,"caveat":"Illustrative approximations of World Bank Worldwide Governance Indicators percentile ranks and UNODC-style homicide rates, not a direct download. Composite = 30% homicide (inverted, capped at 50/100k) + 30% rule of law + 25% political stability + 15% corruption control."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"medium"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/country-retirement-fit/countries":{"get":{"summary":"List countries supported by the country retirement fit ranking","tags":["Global"],"description":"Lists the countries eligible to appear in a /v1/country-retirement-fit ranking. Use this to populate a country picker before calling the main endpoint. Returns a list of { code, name } options.","deprecated":true,"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","description":"Successful response.","properties":{"options":{"type":"array","description":"Supported countries.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code."},"name":{"type":"string","description":"Country display name."}}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}},"deprecation":{"type":"object","description":"Present only on deprecated endpoints. States when the endpoint stops serving and why. See the Deprecation and Sunset response headers (RFC 8594).","properties":{"sunset":{"type":"string","description":"ISO date after which this endpoint stops serving. Example: \"2027-02-28\""},"reason":{"type":"string","description":"Why the endpoint is being withdrawn."},"replacement":{"type":["null","string"],"description":"Path of a replacement endpoint, or null where there is none."}}}},"additionalProperties":true}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/country-retirement-fit":{"get":{"summary":"Rank the top 10 retirement destinations by a weighted fit score","tags":["Global"],"description":"Rank the top 10 retirement destinations by a weighted fit score combining healthcare, climate, safety, and affordability. Use this when a user is planning where to retire and wants country suggestions matched to their priorities and pension. Returns a ranked list with each country's fit score and component scores. Example: \"Where should I retire at 65 with a $30,000/year pension, prioritizing healthcare and safety over climate and cost?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 country code, excluded from the results. Example: \"GBR\""},{"schema":{"type":"string"},"in":"query","name":"targetRetirementAge","required":true,"description":"Planned retirement age (40-90). Example: 65"},{"schema":{"type":"string"},"in":"query","name":"annualPensionUSD","required":true,"description":"Annual pension/retirement income, treated as an international-dollar (PPP) figure. Example: 30000"},{"schema":{"type":"string"},"in":"query","name":"healthcarePriority","required":true,"description":"Priority weight, 1-5. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"climatePriority","required":true,"description":"Priority weight, 1-5. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"safetyPriority","required":true,"description":"Priority weight, 1-5. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"affordabilityPriority","required":true,"description":"Priority weight, 1-5. Example: 3"}],"deprecated":true,"responses":{"200":{"description":"The top 10 retirement destinations ranked by weighted fit score.","content":{"application/json":{"schema":{"type":"object","description":"The top 10 retirement destinations ranked by weighted fit score.","properties":{"result":{"type":"object","description":"The ranking result.","properties":{"matches":{"type":"array","description":"Up to 10 countries, ranked by fit score, highest first.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"PRT\""},"name":{"type":"string","description":"Country display name. Example: \"Portugal\""},"fitScore":{"type":"number","description":"Overall weighted fit score, 0-100."},"healthcareScore":{"type":"number","description":"Healthcare component score, 0-100."},"climateScore":{"type":"number","description":"Climate component score, 0-100."},"safetyScore":{"type":"number","description":"Safety component score, 0-100."},"affordabilityScore":{"type":"number","description":"Affordability component score, 0-100."},"pppEquivalentPensionLocal":{"type":"number","description":"The pension amount in this country's local currency, at purchasing-power parity."},"currencyCode":{"type":"string","description":"ISO 4217 currency code. Example: \"EUR\""},"missingDimensions":{"type":"array","items":{"type":"string","enum":["healthcare","climate","safety","affordability"]},"description":"Score dimensions this country had no data for — scored as a neutral 50 placeholder instead of being excluded. Empty when every dimension had real data."}}}},"caveat":{"type":"string","description":"Note on data provenance and estimate accuracy."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"Confidence level in the estimate. Always \"low\" for this endpoint."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}},"deprecation":{"type":"object","description":"Present only on deprecated endpoints. States when the endpoint stops serving and why. See the Deprecation and Sunset response headers (RFC 8594).","properties":{"sunset":{"type":"string","description":"ISO date after which this endpoint stops serving. Example: \"2027-02-28\""},"reason":{"type":"string","description":"Why the endpoint is being withdrawn."},"replacement":{"type":["null","string"],"description":"Path of a replacement endpoint, or null where there is none."}}}}},"examples":{"UkRetireeHealthcareAndSafety":{"summary":"A UK retiree at 65 with a $30,000 pension, prioritizing healthcare and safety (top 3 of 10 shown)","value":{"result":{"matches":[{"code":"PRT","name":"Portugal","fitScore":85.7,"healthcareScore":73.3,"climateScore":100,"safetyScore":83.9,"affordabilityScore":100,"pppEquivalentPensionLocal":17400,"currencyCode":"EUR","missingDimensions":[]},{"code":"ESP","name":"Spain","fitScore":84.9,"healthcareScore":81,"climateScore":100,"safetyScore":79.3,"affordabilityScore":90.9,"pppEquivalentPensionLocal":18900,"currencyCode":"EUR","missingDimensions":[]},{"code":"JPN","name":"Japan","fitScore":84.9,"healthcareScore":90.5,"climateScore":80,"safetyScore":89.3,"affordabilityScore":71.4,"pppEquivalentPensionLocal":3000000,"currencyCode":"JPY","missingDimensions":[]}],"caveat":"Illustrative composite score combining curated life-table, climate, safety, and income data — a starting point for research, not personalized retirement or immigration advice. Countries missing a dimension (see missingDimensions) use a neutral 50/100 placeholder for it instead of being excluded."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"low"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/country-affordability-match":{"get":{"summary":"Find countries where a given income reaches the top half of earners nationally, ranked by monthly surplus over an estimated lifestyle cost.","tags":["Global"],"description":"Find countries where a given income reaches the top half of earners nationally, ranked by monthly surplus over an estimated lifestyle cost. Use this when a user is considering relocating and wants to know where their income would go furthest. Returns estimated lifestyle cost, monthly surplus, national income percentile, and a housing burden proxy, per country. Example: \"Where could a $4,000/month income for a household of 2 afford a comfortable lifestyle, coming from the US?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 country code, excluded from the results. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"netMonthlyIncomeUSD","required":true,"description":"Net monthly income, treated as an international-dollar (PPP) figure. Example: 4000"},{"schema":{"type":"string"},"in":"query","name":"householdSize","required":true,"description":"Number of people the income supports (1-6). Example: 2"},{"schema":{"type":"string","enum":["frugal","moderate","comfortable"]},"in":"query","name":"lifestyleLevel","required":true,"description":"Desired lifestyle level. Example: \"comfortable\""}],"responses":{"200":{"description":"Up to 10 countries where the given income reaches the top half of national earners, ranked by monthly surplus over an estimated lifestyle cost.","content":{"application/json":{"schema":{"type":"object","description":"Up to 10 countries where the given income reaches the top half of national earners, ranked by monthly surplus over an estimated lifestyle cost.","properties":{"result":{"type":"object","description":"The affordability match result.","properties":{"matches":{"type":"array","description":"Up to 10 matching countries, sorted by monthly surplus descending.","items":{"type":"object","properties":{"code":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Example: \"ETH\""},"name":{"type":"string","description":"Country name. Example: \"Ethiopia\""},"estimatedMonthlyLifestyleCostLocal":{"type":"number","description":"Estimated monthly lifestyle cost in the country's local currency. Example: 4235"},"currencyCode":{"type":"string","description":"ISO 4217 currency code for estimatedMonthlyLifestyleCostLocal. Example: \"ETB\""},"monthlySurplusIntl":{"type":"number","description":"Monthly income left over after the estimated lifestyle cost, in international dollars. Example: 3717.7"},"nationalIncomePercentile":{"type":"number","description":"Where the given income (adjusted for household size) ranks nationally. Example: 99.5"},"housingBurdenProxyPercent":{"type":"number","description":"Illustrative share of the income that a typical housing cost would consume. Example: 2.3"}}}},"caveat":{"type":"string","description":"Explanation of the data source and its limitations."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How the result was derived. Example: \"composite\""},"confidence":{"type":"string","description":"Confidence level in the result. Example: \"low\""}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"USA4000Comfortable":{"summary":"Where a $4,000/month income for a household of 2 affords a comfortable lifestyle, coming from the US","value":{"result":{"matches":[{"code":"ETH","name":"Ethiopia","estimatedMonthlyLifestyleCostLocal":4235,"currencyCode":"ETB","monthlySurplusIntl":3717.7,"nationalIncomePercentile":99.5,"housingBurdenProxyPercent":2.3},{"code":"KEN","name":"Kenya","estimatedMonthlyLifestyleCostLocal":20533,"currencyCode":"KES","monthlySurplusIntl":3486.7,"nationalIncomePercentile":99.5,"housingBurdenProxyPercent":4.1},{"code":"PAK","name":"Pakistan","estimatedMonthlyLifestyleCostLocal":23100,"currencyCode":"PKR","monthlySurplusIntl":3422.5,"nationalIncomePercentile":99.5,"housingBurdenProxyPercent":4.6},{"code":"NGA","name":"Nigeria","estimatedMonthlyLifestyleCostLocal":132825,"currencyCode":"NGN","monthlySurplusIntl":3422.5,"nationalIncomePercentile":99.5,"housingBurdenProxyPercent":4.6},{"code":"BGD","name":"Bangladesh","estimatedMonthlyLifestyleCostLocal":20533,"currencyCode":"BDT","monthlySurplusIntl":3358.3,"nationalIncomePercentile":99.5,"housingBurdenProxyPercent":5.1},{"code":"IND","name":"India","estimatedMonthlyLifestyleCostLocal":14823,"currencyCode":"INR","monthlySurplusIntl":3294.2,"nationalIncomePercentile":99.5,"housingBurdenProxyPercent":5.6},{"code":"PHL","name":"Philippines","estimatedMonthlyLifestyleCostLocal":16170,"currencyCode":"PHP","monthlySurplusIntl":3101.7,"nationalIncomePercentile":98.6,"housingBurdenProxyPercent":7.2},{"code":"VNM","name":"Vietnam","estimatedMonthlyLifestyleCostLocal":8726667,"currencyCode":"VND","monthlySurplusIntl":2909.2,"nationalIncomePercentile":96.5,"housingBurdenProxyPercent":8.7},{"code":"IDN","name":"Indonesia","estimatedMonthlyLifestyleCostLocal":5428500,"currencyCode":"IDR","monthlySurplusIntl":2845,"nationalIncomePercentile":92.7,"housingBurdenProxyPercent":9.2},{"code":"PER","name":"Peru","estimatedMonthlyLifestyleCostLocal":2438,"currencyCode":"PEN","monthlySurplusIntl":2716.7,"nationalIncomePercentile":85.6,"housingBurdenProxyPercent":10.3}],"caveat":"Illustrative estimate using a lifestyle-cost model (a multiple of each country's median PPP income) rather than real cost-of-living survey data — a starting point for research, not a relocation budget."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"low"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cross-border-retirement-income":{"get":{"summary":"Estimate how a pension translates to another country for a retiree considering moving abroad.","tags":["Finance"],"description":"Estimate how a pension translates to another country for a retiree considering moving abroad. Use this when a user wants to know how far their pension would stretch in a different country. Returns PPP-equivalent income in local currency, an approximate FX-equivalent, purchasing-power gain/loss %, and estimated years the amount lasts at a moderate local lifestyle cost. Example: \"How far would a $40,000/year US pension go if I retired in Portugal?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"originCountry","required":true,"description":"ISO 3166-1 alpha-3 country code — contextual only. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"pensionAmountUSD","required":true,"description":"Pension amount in USD, treated as a lump sum for the years-lasts estimate. Example: 40000"},{"schema":{"type":"string"},"in":"query","name":"targetCountry","required":true,"description":"ISO 3166-1 alpha-3 destination country code. Example: \"PRT\""}],"responses":{"200":{"description":"How far the pension would stretch in the target country.","content":{"application/json":{"schema":{"type":"object","description":"How far the pension would stretch in the target country.","properties":{"result":{"type":"object","description":"The cross-border retirement income estimate.","properties":{"pppEquivalentIncomeLocal":{"type":"number","description":"The pension in target-country local currency, at purchasing-power parity."},"pppEquivalentIncomeUsd":{"type":"number","description":"The pension expressed in international (PPP) dollars — equal to pensionAmountUSD."},"approximateFxEquivalentLocal":{"type":"number","description":"An approximate market-FX equivalent in local currency, triangulated from relative income levels (not a live quote)."},"currencyCode":{"type":"string","description":"ISO 4217 currency code of the target country. Example: \"EUR\""},"purchasingPowerGainLossPercent":{"type":"number","description":"Positive means the pension is estimated to go further here by market FX than PPP parity alone would suggest."},"estimatedYearsPensionLasts":{"type":"number","description":"Years the pension amount lasts as a lump sum at a moderate local lifestyle cost."},"suitabilityNote":{"type":"string","description":"A short, human-readable summary of the estimate."},"caveat":{"type":"string","description":"Note on data provenance and estimate accuracy."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"modelled\" for this endpoint."},"confidence":{"type":"string","description":"Confidence level in the estimate. Always \"low\" for this endpoint."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsPensionToPortugal":{"summary":"A $40,000/year US pension retiring in Portugal","value":{"result":{"pppEquivalentIncomeLocal":23200,"pppEquivalentIncomeUsd":40000,"approximateFxEquivalentLocal":34664,"currencyCode":"EUR","purchasingPowerGainLossPercent":49.4,"estimatedYearsPensionLasts":2.7,"suitabilityNote":"Your pension is estimated to go significantly further here by market FX than PPP parity alone would suggest, lasting roughly 2.7 years at a moderate local lifestyle cost.","caveat":"Illustrative estimate. The FX-equivalent figure approximates the market exchange rate via PPP triangulation through relative income levels — it is not a live quote and can diverge substantially from actual market rates. \"Years pension lasts\" treats the amount as a lump sum drawn down at a moderate local lifestyle cost, not a recurring guaranteed income."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"modelled","confidence":"low"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/reference/{table}":{"get":{"summary":"List reference data options for a supported table","tags":["Developer Tools"],"description":"Returns a { code, name } list of reference data for a supported table, used to populate country/field dropdowns before calling a calculator. This is an internal support endpoint the web front end uses, documented here for completeness rather than as a primary calculator.","parameters":[{"schema":{"type":"string"},"in":"path","name":"table","required":true,"description":"The reference table slug, e.g. \"income-percentiles\", \"ppp-factors\", \"country-safety\". See the route path for the full list of supported tables."}],"responses":{"200":{"description":"A { code, name } list for the requested reference table, sorted alphabetically by name. Some tables include extra fields beyond code/name — e.g. \"ppp-factors\" also returns currencyCode and pppFactor, \"degree-salaries\" uses \"field\" as both code and name.","content":{"application/json":{"schema":{"type":"object","description":"A { code, name } list for the requested reference table, sorted alphabetically by name. Some tables include extra fields beyond code/name — e.g. \"ppp-factors\" also returns currencyCode and pppFactor, \"degree-salaries\" uses \"field\" as both code and name.","properties":{"options":{"type":"array","description":"One row per option available in the requested table.","items":{"type":"object","description":"Every table includes at least code and name; some tables add further fields.","additionalProperties":true,"properties":{"code":{"type":"string","description":"The row's identifying code — usually an ISO 3166-1 alpha-3 country code. Example: \"DEU\""},"name":{"type":"string","description":"Human-readable display name. Example: \"Germany\""}}}}}},"examples":{"IncomePercentilesTable":{"summary":"List countries available in the income-percentiles table","value":{"options":[{"code":"ARG","name":"Argentina"},{"code":"AUS","name":"Australia"},{"code":"AUT","name":"Austria"},{"code":"BGD","name":"Bangladesh"},{"code":"BEL","name":"Belgium"}]}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/current-ratio":{"get":{"summary":"Calculate the current ratio — current assets divided by current liabilities — a standard short-term liquidity test.","tags":["Business Finance"],"description":"Calculate the current ratio — current assets divided by current liabilities — a standard short-term liquidity test. Use this when a user wants to know if a company can cover its short-term obligations with its short-term assets. Returns the current ratio with a danger/acceptable/healthy benchmark label. Example: \"What is the current ratio for a company with $1.2M in current assets and $800,000 in current liabilities?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentAssets","required":true,"description":"Total current assets. Example: 1200000"},{"schema":{"type":"string"},"in":"query","name":"currentLiabilities","required":true,"description":"Total current liabilities. Example: 800000"}],"responses":{"200":{"description":"The current ratio with a danger/acceptable/healthy benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The current ratio with a danger/acceptable/healthy benchmark label.","properties":{"result":{"type":"object","description":"The current ratio result.","properties":{"ratio":{"type":"number","description":"Current assets divided by current liabilities. Example: 1.5"},"benchmark":{"type":"string","enum":["danger","acceptable","healthy"],"description":"Benchmark label based on the ratio. Example: \"acceptable\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"1point2MCurrentAssets":{"summary":"Current ratio for $1.2M current assets and $800,000 current liabilities","value":{"result":{"ratio":1.5,"benchmark":"acceptable"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/quick-ratio":{"get":{"summary":"Calculate the quick ratio (acid test) — (current assets minus inventory) divided by current liabilities — a stricter liquidity test than the current ratio since it excludes inventory.","tags":["Business Finance"],"description":"Calculate the quick ratio (acid test) — (current assets minus inventory) divided by current liabilities — a stricter liquidity test than the current ratio since it excludes inventory. Use this when a user wants to know if a company can cover short-term liabilities without relying on selling inventory. Returns the quick ratio with a concern/healthy benchmark. Example: \"What is the quick ratio for a company with $1.2M current assets, $300,000 inventory, and $800,000 current liabilities?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"currentAssets","required":true,"description":"Total current assets. Example: 1200000"},{"schema":{"type":"string"},"in":"query","name":"inventory","required":true,"description":"Inventory value. Example: 300000"},{"schema":{"type":"string"},"in":"query","name":"currentLiabilities","required":true,"description":"Total current liabilities. Example: 800000"}],"responses":{"200":{"description":"The quick ratio with a concern/healthy benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The quick ratio with a concern/healthy benchmark label.","properties":{"result":{"type":"object","description":"The quick ratio result.","properties":{"ratio":{"type":"number","description":"(Current assets minus inventory) divided by current liabilities. Example: 1.13"},"benchmark":{"type":"string","enum":["concern","healthy"],"description":"Benchmark label based on the ratio. Example: \"healthy\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"1point2MCurrentAssets":{"summary":"Quick ratio for $1.2M current assets, $300,000 inventory, $800,000 current liabilities","value":{"result":{"ratio":1.13,"benchmark":"healthy"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cash-ratio":{"get":{"summary":"Calculate the cash ratio — cash and cash equivalents divided by current liabilities, the most conservative test of a company's ability to cover short-term obligations.","tags":["Business Finance"],"description":"Calculate the cash ratio — cash and cash equivalents divided by current liabilities, the most conservative test of a company's ability to cover short-term obligations. Use this when a user wants the strictest possible liquidity check, ignoring receivables and inventory. Returns the cash ratio. Example: \"What is the cash ratio for a company with $500,000 in cash and $800,000 in current liabilities?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"cash","required":true,"description":"Cash and cash equivalents. Example: 500000"},{"schema":{"type":"string"},"in":"query","name":"currentLiabilities","required":true,"description":"Total current liabilities. Example: 800000"}],"responses":{"200":{"description":"The cash ratio with a low/adequate benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The cash ratio with a low/adequate benchmark label.","properties":{"result":{"type":"object","description":"The cash ratio result.","properties":{"ratio":{"type":"number","description":"Cash divided by current liabilities. Example: 0.63"},"benchmark":{"type":"string","enum":["low","adequate"],"description":"Benchmark label based on the ratio. Example: \"adequate\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"500kCash":{"summary":"Cash ratio for $500,000 cash and $800,000 current liabilities","value":{"result":{"ratio":0.63,"benchmark":"adequate"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/operating-cash-flow-ratio":{"get":{"summary":"Calculate the operating cash flow ratio — operating cash flow divided by current liabilities — a liquidity test based on actual cash rather than accounting profit.","tags":["Business Finance"],"description":"Calculate the operating cash flow ratio — operating cash flow divided by current liabilities — a liquidity test based on actual cash rather than accounting profit. Use this when a user wants to know if a company generates enough cash to cover short-term obligations. Returns the operating cash flow ratio. Example: \"What is the operating cash flow ratio for a company with $600,000 operating cash flow and $500,000 in current liabilities?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"operatingCF","required":true,"description":"Operating cash flow. Example: 600000"},{"schema":{"type":"string"},"in":"query","name":"currentLiabilities","required":true,"description":"Total current liabilities. Example: 500000"}],"responses":{"200":{"description":"The operating cash flow ratio with an insufficient/sufficient benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The operating cash flow ratio with an insufficient/sufficient benchmark label.","properties":{"result":{"type":"object","description":"The operating cash flow ratio result.","properties":{"ratio":{"type":"number","description":"Operating cash flow divided by current liabilities. Example: 1.2"},"benchmark":{"type":"string","enum":["insufficient","sufficient"],"description":"Benchmark label based on the ratio. Example: \"sufficient\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"600kOperatingCashFlow":{"summary":"Operating cash flow ratio for $600,000 OCF and $500,000 current liabilities","value":{"result":{"ratio":1.2,"benchmark":"sufficient"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/debt-to-equity":{"get":{"summary":"Calculate the debt-to-equity ratio — total debt divided by shareholders' equity — with a high-leverage benchmark above 2.","tags":["Business Finance"],"description":"Calculate the debt-to-equity ratio — total debt divided by shareholders' equity — with a high-leverage benchmark above 2. Use this when a user wants to assess a company's financial leverage or compare capital structure between companies. Returns the debt-to-equity ratio. Example: \"What is the debt-to-equity ratio for a company with $4M in debt and $5M in shareholders' equity?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"totalDebt","required":true,"description":"Total debt. Example: 4000000"},{"schema":{"type":"string"},"in":"query","name":"equity","required":true,"description":"Shareholders' equity. Example: 5000000"}],"responses":{"200":{"description":"The debt-to-equity ratio with a conservative/high leverage benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The debt-to-equity ratio with a conservative/high leverage benchmark label.","properties":{"result":{"type":"object","description":"The debt-to-equity result.","properties":{"ratio":{"type":"number","description":"Total debt divided by shareholders' equity. Example: 0.8"},"benchmark":{"type":"string","enum":["conservative","high leverage"],"description":"Benchmark label — \"high leverage\" above 2. Example: \"conservative\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"4MDebt":{"summary":"Debt-to-equity for $4M debt and $5M equity","value":{"result":{"ratio":0.8,"benchmark":"conservative"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/debt-to-assets":{"get":{"summary":"Calculate the debt-to-assets ratio — total debt as a percentage of total assets — flagging majority debt-financed companies above 50%.","tags":["Business Finance"],"description":"Calculate the debt-to-assets ratio — total debt as a percentage of total assets — flagging majority debt-financed companies above 50%. Use this when a user wants to assess how much of a company's assets are financed by debt vs equity. Returns the debt-to-assets ratio as a percentage. Example: \"What is the debt-to-assets ratio for a company with $4M in debt and $10M in total assets?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"totalDebt","required":true,"description":"Total debt. Example: 4000000"},{"schema":{"type":"string"},"in":"query","name":"totalAssets","required":true,"description":"Total assets. Example: 10000000"}],"responses":{"200":{"description":"The debt-to-assets ratio, as a percentage, with an asset-financed/majority debt-financed benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The debt-to-assets ratio, as a percentage, with an asset-financed/majority debt-financed benchmark label.","properties":{"result":{"type":"object","description":"The debt-to-assets result.","properties":{"percentage":{"type":"number","description":"Total debt / total assets x 100. Example: 40"},"benchmark":{"type":"string","enum":["asset-financed","majority debt-financed"],"description":"Benchmark label — \"majority debt-financed\" above 50%. Example: \"asset-financed\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"4MDebt":{"summary":"Debt-to-assets for $4M debt and $10M total assets","value":{"result":{"percentage":40,"benchmark":"asset-financed"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/interest-coverage":{"get":{"summary":"Calculate the interest coverage ratio — EBIT divided by interest expense — with distress/watch/comfortable bands.","tags":["Business Finance"],"description":"Calculate the interest coverage ratio — EBIT divided by interest expense — with distress/watch/comfortable bands. Use this when a user wants to assess how easily a company can pay interest on its outstanding debt. Returns the interest coverage ratio and its risk band. Example: \"What is the interest coverage ratio for a company with $2M EBIT and $400,000 in interest expense?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"ebit","required":true,"description":"Earnings before interest and tax. Example: 2000000"},{"schema":{"type":"string"},"in":"query","name":"interestExpense","required":true,"description":"Interest expense. Example: 400000"}],"responses":{"200":{"description":"The interest coverage ratio with a distress/watch/comfortable benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"The interest coverage ratio with a distress/watch/comfortable benchmark label.","properties":{"result":{"type":"object","description":"The interest coverage result.","properties":{"ratio":{"type":"number","description":"EBIT divided by interest expense. Example: 5"},"benchmark":{"type":"string","enum":["distress","watch","comfortable"],"description":"Risk band based on the ratio. Example: \"comfortable\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"2MEbit":{"summary":"Interest coverage for $2M EBIT and $400,000 interest expense","value":{"result":{"ratio":5,"benchmark":"comfortable"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/debt-service-coverage":{"get":{"summary":"Calculate the debt service coverage ratio (DSCR) — net operating income divided by total debt service — against the typical 1.25x lender threshold.","tags":["Business Finance"],"description":"Calculate the debt service coverage ratio (DSCR) — net operating income divided by total debt service — against the typical 1.25x lender threshold. Use this when a user is evaluating whether a property or business generates enough income to cover its debt payments, e.g. for a loan application. Returns the DSCR and whether it clears the typical lender threshold. Example: \"What is the DSCR for a property with $150,000 net operating income and $100,000 in annual debt service?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"noi","required":true,"description":"Net operating income. Example: 150000"},{"schema":{"type":"string"},"in":"query","name":"totalDebtService","required":true,"description":"Total debt service (principal + interest) for the period. Example: 100000"}],"responses":{"200":{"description":"The debt service coverage ratio against the typical 1.25x lender threshold.","content":{"application/json":{"schema":{"type":"object","description":"The debt service coverage ratio against the typical 1.25x lender threshold.","properties":{"result":{"type":"object","description":"The DSCR result.","properties":{"ratio":{"type":"number","description":"Net operating income divided by total debt service. Example: 1.5"},"benchmark":{"type":"string","enum":["cannot cover","below lender threshold","meets lender threshold"],"description":"Benchmark label against the 1.0x and 1.25x thresholds. Example: \"meets lender threshold\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"150kNoi":{"summary":"DSCR for $150,000 NOI and $100,000 total debt service","value":{"result":{"ratio":1.5,"benchmark":"meets lender threshold"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/equity-multiplier":{"get":{"summary":"Calculate the equity multiplier — total assets divided by shareholders' equity — the leverage component of DuPont analysis.","tags":["Business Finance"],"description":"Calculate the equity multiplier — total assets divided by shareholders' equity — the leverage component of DuPont analysis. Use this when a user wants to isolate how much financial leverage is contributing to a company's ROE. Returns the equity multiplier. Example: \"What is the equity multiplier for a company with $15M in total assets and $8M in equity?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"totalAssets","required":true,"description":"Total assets. Example: 15000000"},{"schema":{"type":"string"},"in":"query","name":"equity","required":true,"description":"Shareholders' equity. Example: 8000000"}],"responses":{"200":{"description":"The equity multiplier.","content":{"application/json":{"schema":{"type":"object","description":"The equity multiplier.","properties":{"result":{"type":"object","description":"The equity multiplier result.","properties":{"ratio":{"type":"number","description":"Total assets divided by shareholders' equity. Example: 1.88"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"15MTotalAssets":{"summary":"Equity multiplier for $15M total assets and $8M equity","value":{"result":{"ratio":1.88},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/gross-profit-margin":{"get":{"summary":"Calculate gross profit margin — (revenue minus cost of goods sold) as a percentage of revenue.","tags":["Business Finance"],"description":"Calculate gross profit margin — (revenue minus cost of goods sold) as a percentage of revenue. Use this when a user wants to know how much profit is left after direct production costs, before operating expenses. Returns the gross profit margin as a percentage. Example: \"What is the gross profit margin for a company with $10M revenue and $6M cost of goods sold?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 10000000"},{"schema":{"type":"string"},"in":"query","name":"cogs","required":true,"description":"Cost of goods sold. Example: 6000000"}],"responses":{"200":{"description":"Gross profit margin, as a percentage.","content":{"application/json":{"schema":{"type":"object","description":"Gross profit margin, as a percentage.","properties":{"result":{"type":"object","description":"The gross profit margin result.","properties":{"percentage":{"type":"number","description":"(Revenue - COGS) / revenue x 100. Example: 40"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"10MRevenue":{"summary":"Gross profit margin for $10M revenue and $6M COGS","value":{"result":{"percentage":40},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/operating-profit-margin":{"get":{"summary":"Calculate operating profit margin — EBIT as a percentage of revenue.","tags":["Business Finance"],"description":"Calculate operating profit margin — EBIT as a percentage of revenue. Use this when a user wants to assess core operating profitability before interest and tax. Returns the operating profit margin as a percentage. Example: \"What is the operating profit margin for a company with $2M EBIT and $10M revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"ebit","required":true,"description":"Earnings before interest and tax. Example: 2000000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 10000000"}],"responses":{"200":{"description":"Operating profit margin, as a percentage.","content":{"application/json":{"schema":{"type":"object","description":"Operating profit margin, as a percentage.","properties":{"result":{"type":"object","description":"The operating profit margin result.","properties":{"percentage":{"type":"number","description":"EBIT / revenue x 100. Example: 20"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"2MEbit":{"summary":"Operating profit margin for $2M EBIT and $10M revenue","value":{"result":{"percentage":20},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/net-profit-margin":{"get":{"summary":"Calculate net profit margin — net income as a percentage of revenue, the bottom-line profitability measure.","tags":["Business Finance"],"description":"Calculate net profit margin — net income as a percentage of revenue, the bottom-line profitability measure. Use this when a user wants to know how much of every dollar of revenue becomes actual profit. Returns the net profit margin as a percentage. Example: \"What is the net profit margin for a company with $1.5M net income and $10M revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"netIncome","required":true,"description":"Net income. Example: 1500000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 10000000"}],"responses":{"200":{"description":"Net profit margin, as a percentage.","content":{"application/json":{"schema":{"type":"object","description":"Net profit margin, as a percentage.","properties":{"result":{"type":"object","description":"The net profit margin result.","properties":{"percentage":{"type":"number","description":"Net income / revenue x 100. Example: 15"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"1point5MNetIncome":{"summary":"Net profit margin for $1.5M net income and $10M revenue","value":{"result":{"percentage":15},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ebitda-margin":{"get":{"summary":"Calculate EBITDA margin — EBITDA as a percentage of revenue.","tags":["Business Finance"],"description":"Calculate EBITDA margin — EBITDA as a percentage of revenue. Use this when a user wants to assess a company's core operating profitability independent of financing, tax, and non-cash accounting choices. Returns the EBITDA margin as a percentage. Example: \"What is the EBITDA margin for a company with $3M EBITDA and $15M revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"ebitda","required":true,"description":"Earnings before interest, tax, depreciation and amortization. Example: 3000000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 15000000"}],"responses":{"200":{"description":"EBITDA margin, as a percentage.","content":{"application/json":{"schema":{"type":"object","description":"EBITDA margin, as a percentage.","properties":{"result":{"type":"object","description":"The EBITDA margin result.","properties":{"percentage":{"type":"number","description":"EBITDA / revenue x 100. Example: 20"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"3MEbitda":{"summary":"EBITDA margin for $3M EBITDA and $15M revenue","value":{"result":{"percentage":20},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/return-on-assets":{"get":{"summary":"Calculate return on assets (ROA) — net income as a percentage of total assets — flagging good performance above 5%.","tags":["Business Finance"],"description":"Calculate return on assets (ROA) — net income as a percentage of total assets — flagging good performance above 5%. Use this when a user wants to know how efficiently a company generates profit from its asset base. Returns ROA as a percentage. Example: \"What is the ROA for a company with $1.5M net income and $20M in total assets?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"netIncome","required":true,"description":"Net income. Example: 1500000"},{"schema":{"type":"string"},"in":"query","name":"totalAssets","required":true,"description":"Total assets. Example: 20000000"}],"responses":{"200":{"description":"Return on assets, as a percentage, with a below average/good benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"Return on assets, as a percentage, with a below average/good benchmark label.","properties":{"result":{"type":"object","description":"The ROA result.","properties":{"percentage":{"type":"number","description":"Net income / total assets x 100. Example: 7.5"},"benchmark":{"type":"string","enum":["below average","good"],"description":"Benchmark label — \"good\" above 5%. Example: \"good\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"1point5MNetIncome":{"summary":"ROA for $1.5M net income and $20M total assets","value":{"result":{"percentage":7.5,"benchmark":"good"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/return-on-equity":{"get":{"summary":"Calculate return on equity (ROE) — net income as a percentage of shareholders' equity — flagging strong performance above 15%.","tags":["Business Finance"],"description":"Calculate return on equity (ROE) — net income as a percentage of shareholders' equity — flagging strong performance above 15%. Use this when a user wants to know how efficiently a company generates profit from shareholders' invested capital. Returns ROE as a percentage. Example: \"What is the ROE for a company with $2M net income and $10M in shareholders' equity?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"netIncome","required":true,"description":"Net income. Example: 2000000"},{"schema":{"type":"string"},"in":"query","name":"equity","required":true,"description":"Shareholders' equity. Example: 10000000"}],"responses":{"200":{"description":"Return on equity, as a percentage, with a below average/strong benchmark label.","content":{"application/json":{"schema":{"type":"object","description":"Return on equity, as a percentage, with a below average/strong benchmark label.","properties":{"result":{"type":"object","description":"The ROE result.","properties":{"percentage":{"type":"number","description":"Net income / equity x 100. Example: 20"},"benchmark":{"type":"string","enum":["below average","strong"],"description":"Benchmark label — \"strong\" above 15%. Example: \"strong\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"2MNetIncome":{"summary":"ROE for $2M net income and $10M shareholders' equity","value":{"result":{"percentage":20,"benchmark":"strong"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/return-on-invested-capital":{"get":{"summary":"Calculate return on invested capital (ROIC) — NOPAT divided by invested capital — meant to be compared against WACC to judge whether a company creates or destroys value.","tags":["Business Finance"],"description":"Calculate return on invested capital (ROIC) — NOPAT divided by invested capital — meant to be compared against WACC to judge whether a company creates or destroys value. Use this when a user wants to know if a company earns more than its cost of capital. Returns ROIC as a percentage. Example: \"What is the ROIC for a company with $1.8M NOPAT and $12M invested capital?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"nopat","required":true,"description":"Net operating profit after tax. Example: 1800000"},{"schema":{"type":"string"},"in":"query","name":"investedCapital","required":true,"description":"Invested capital. Example: 12000000"}],"responses":{"200":{"description":"Return on invested capital, as a percentage, with a note on how to interpret it against WACC.","content":{"application/json":{"schema":{"type":"object","description":"Return on invested capital, as a percentage, with a note on how to interpret it against WACC.","properties":{"result":{"type":"object","description":"The ROIC result.","properties":{"percentage":{"type":"number","description":"NOPAT / invested capital x 100. Example: 15"},"note":{"type":"string","description":"Guidance on comparing ROIC against WACC."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"1point8MNopat":{"summary":"ROIC for $1.8M NOPAT and $12M invested capital","value":{"result":{"percentage":15,"note":"Compare against WACC — ROIC above WACC means the business is creating value; below means it is destroying it."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/earnings-per-share":{"get":{"summary":"Calculate earnings per share (EPS) — (net income minus preferred dividends) divided by weighted average shares outstanding.","tags":["Business Finance"],"description":"Calculate earnings per share (EPS) — (net income minus preferred dividends) divided by weighted average shares outstanding. Use this when a user wants to know how much profit a company generates per share of stock. Returns EPS in dollars per share. Example: \"What is the EPS for a company with $5M net income, $200,000 in preferred dividends, and 2 million shares outstanding?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"netIncome","required":true,"description":"Net income. Example: 5000000"},{"schema":{"type":"string"},"in":"query","name":"preferredDividends","required":true,"description":"Preferred dividends paid. Example: 200000"},{"schema":{"type":"string"},"in":"query","name":"sharesOutstanding","required":true,"description":"Weighted average shares outstanding. Example: 2000000"}],"responses":{"200":{"description":"Earnings per share, in dollars per share.","content":{"application/json":{"schema":{"type":"object","description":"Earnings per share, in dollars per share.","properties":{"result":{"type":"object","description":"The EPS result.","properties":{"earningsPerShare":{"type":"number","description":"(Net income - preferred dividends) / shares outstanding. Example: 2.4"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"5MNetIncome":{"summary":"EPS for $5M net income, $200,000 preferred dividends, 2M shares outstanding","value":{"result":{"earningsPerShare":2.4},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/asset-turnover":{"get":{"summary":"Calculate asset turnover — revenue divided by average total assets, a measure of how efficiently a company uses its assets to generate sales.","tags":["Business Finance"],"description":"Calculate asset turnover — revenue divided by average total assets, a measure of how efficiently a company uses its assets to generate sales. Use this when a user wants to assess or compare operational efficiency between periods or companies. Returns the asset turnover ratio. Example: \"What is the asset turnover ratio for a company with $12M revenue and total assets of $8M at the start of the year and $10M at the end?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue for the period. Example: 12000000"},{"schema":{"type":"string"},"in":"query","name":"assetsStart","required":true,"description":"Total assets at the start of the period. Example: 8000000"},{"schema":{"type":"string"},"in":"query","name":"assetsEnd","required":true,"description":"Total assets at the end of the period. Example: 10000000"}],"responses":{"200":{"description":"The asset turnover ratio and the average assets used in its denominator.","content":{"application/json":{"schema":{"type":"object","description":"The asset turnover ratio and the average assets used in its denominator.","properties":{"result":{"type":"object","description":"The asset turnover result.","properties":{"ratio":{"type":"number","description":"Revenue divided by average total assets. Example: 1.33"},"averageAssets":{"type":"number","description":"Average of assetsStart and assetsEnd. Example: 9000000"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"12MRevenue":{"summary":"Asset turnover for $12M revenue, $8M assets start, $10M assets end","value":{"result":{"ratio":1.33,"averageAssets":9000000},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/inventory-turnover":{"get":{"summary":"Calculate inventory turnover — cost of goods sold divided by average inventory — a measure of how many times inventory is sold and replaced over a period.","tags":["Business Finance"],"description":"Calculate inventory turnover — cost of goods sold divided by average inventory — a measure of how many times inventory is sold and replaced over a period. Use this when a user wants to assess inventory management efficiency. Returns the inventory turnover ratio. Example: \"What is the inventory turnover for a company with $3M COGS and inventory of $500,000 at the start and $700,000 at the end of the year?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"cogs","required":true,"description":"Cost of goods sold. Example: 3000000"},{"schema":{"type":"string"},"in":"query","name":"inventoryStart","required":true,"description":"Inventory at period start. Example: 500000"},{"schema":{"type":"string"},"in":"query","name":"inventoryEnd","required":true,"description":"Inventory at period end. Example: 700000"}],"responses":{"200":{"description":"The inventory turnover ratio and the average inventory used in its denominator.","content":{"application/json":{"schema":{"type":"object","description":"The inventory turnover ratio and the average inventory used in its denominator.","properties":{"result":{"type":"object","description":"The inventory turnover result.","properties":{"ratio":{"type":"number","description":"COGS divided by average inventory. Example: 5"},"averageInventory":{"type":"number","description":"Average of inventoryStart and inventoryEnd. Example: 600000"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"3MCogs":{"summary":"Inventory turnover for $3M COGS, $500,000 inventory start, $700,000 inventory end","value":{"result":{"ratio":5,"averageInventory":600000},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/days-sales-outstanding":{"get":{"summary":"Calculate days sales outstanding (DSO) — the average number of days a company takes to collect payment after a sale.","tags":["Business Finance"],"description":"Calculate days sales outstanding (DSO) — the average number of days a company takes to collect payment after a sale. Use this when a user wants to assess how quickly a company converts sales into cash. Returns DSO in days. Example: \"What is the days sales outstanding for a company with $250,000 in accounts receivable and $3,000,000 in annual revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"accountsReceivable","required":true,"description":"Accounts receivable. Example: 250000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue (annual). Example: 3000000"}],"responses":{"200":{"description":"Days sales outstanding, in days.","content":{"application/json":{"schema":{"type":"object","description":"Days sales outstanding, in days.","properties":{"result":{"type":"object","description":"The DSO result.","properties":{"days":{"type":"number","description":"Accounts receivable / revenue x 365. Example: 30.42"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"250kAccountsReceivable":{"summary":"DSO for $250,000 accounts receivable and $3,000,000 annual revenue","value":{"result":{"days":30.42},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/days-payable-outstanding":{"get":{"summary":"Calculate days payable outstanding (DPO) — the average number of days a company takes to pay its suppliers.","tags":["Business Finance"],"description":"Calculate days payable outstanding (DPO) — the average number of days a company takes to pay its suppliers. Use this when a user wants to assess how a company manages payables or compares suppliers' payment terms. Returns DPO in days. Example: \"What is the days payable outstanding for a company with $400,000 in accounts payable and $3,000,000 in annual COGS?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"accountsPayable","required":true,"description":"Accounts payable. Example: 400000"},{"schema":{"type":"string"},"in":"query","name":"cogs","required":true,"description":"Cost of goods sold (annual). Example: 3000000"}],"responses":{"200":{"description":"Days payable outstanding, in days.","content":{"application/json":{"schema":{"type":"object","description":"Days payable outstanding, in days.","properties":{"result":{"type":"object","description":"The DPO result.","properties":{"days":{"type":"number","description":"Accounts payable / COGS x 365. Example: 48.67"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"400kAccountsPayable":{"summary":"DPO for $400,000 accounts payable and $3,000,000 annual COGS","value":{"result":{"days":48.67},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/days-inventory-outstanding":{"get":{"summary":"Calculate days inventory outstanding (DIO) — the average number of days a company holds inventory before selling it.","tags":["Business Finance"],"description":"Calculate days inventory outstanding (DIO) — the average number of days a company holds inventory before selling it. Use this when a user wants to assess inventory efficiency or working-capital tie-up. Returns DIO in days. Example: \"What is the days inventory outstanding for a company with $500,000 in inventory and $3,000,000 in annual COGS?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"inventory","required":true,"description":"Inventory value. Example: 500000"},{"schema":{"type":"string"},"in":"query","name":"cogs","required":true,"description":"Cost of goods sold (annual). Example: 3000000"}],"responses":{"200":{"description":"Days inventory outstanding, in days.","content":{"application/json":{"schema":{"type":"object","description":"Days inventory outstanding, in days.","properties":{"result":{"type":"object","description":"The DIO result.","properties":{"days":{"type":"number","description":"Inventory / COGS x 365. Example: 60.83"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"500kInventory":{"summary":"DIO for $500,000 inventory and $3,000,000 annual COGS","value":{"result":{"days":60.83},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cash-conversion-cycle":{"get":{"summary":"Calculate the cash conversion cycle — the number of days cash is tied up in operations, computed as days sales outstanding plus days inventory outstanding minus days payable outstanding.","tags":["Business Finance"],"description":"Calculate the cash conversion cycle — the number of days cash is tied up in operations, computed as days sales outstanding plus days inventory outstanding minus days payable outstanding. Use this when a user wants to know how efficiently a company converts inventory investments into cash. Returns the cash conversion cycle in days. Example: \"What is the cash conversion cycle for a company with 45 days sales outstanding, 60 days inventory outstanding, and 30 days payable outstanding?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"dso","required":true,"description":"Days sales outstanding. Example: 45"},{"schema":{"type":"string"},"in":"query","name":"dio","required":true,"description":"Days inventory outstanding. Example: 60"},{"schema":{"type":"string"},"in":"query","name":"dpo","required":true,"description":"Days payable outstanding. Example: 30"}],"responses":{"200":{"description":"The cash conversion cycle, in days.","content":{"application/json":{"schema":{"type":"object","description":"The cash conversion cycle, in days.","properties":{"result":{"type":"object","description":"The cash conversion cycle result.","properties":{"days":{"type":"number","description":"DSO + DIO - DPO. Example: 75"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"45DsoAnd60Dio":{"summary":"Cash conversion cycle for 45 DSO, 60 DIO, 30 DPO","value":{"result":{"days":75},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/altman-z-score":{"get":{"summary":"Calculate the Altman Z-Score bankruptcy-risk model from a company's financials.","tags":["Business Finance"],"description":"Calculate the Altman Z-Score bankruptcy-risk model from a company's financials. Use this when a user wants a quick bankruptcy-risk read on a public company from its balance sheet and income statement — for credit analysis, equity screening, or distress monitoring. Returns the Z-Score, its distress/grey/safe zone, and each component's contribution. Example: \"What is the Altman Z-Score for a company with $2M working capital, $5M retained earnings, $1.5M EBIT, $10M market cap, $8M total assets, $4M total liabilities, and $12M revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"workingCapital","required":true,"description":"Working capital (current assets minus current liabilities). Example: 2000000"},{"schema":{"type":"string"},"in":"query","name":"retainedEarnings","required":true,"description":"Retained earnings from the balance sheet. Example: 5000000"},{"schema":{"type":"string"},"in":"query","name":"ebit","required":true,"description":"Earnings before interest and tax. Example: 1500000"},{"schema":{"type":"string"},"in":"query","name":"marketCap","required":true,"description":"Market capitalization (share price x shares outstanding). Example: 10000000"},{"schema":{"type":"string"},"in":"query","name":"totalAssets","required":true,"description":"Total assets. Example: 8000000"},{"schema":{"type":"string"},"in":"query","name":"totalLiabilities","required":true,"description":"Total liabilities. Example: 4000000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Annual revenue. Example: 12000000"}],"responses":{"200":{"description":"The Altman Z-Score bankruptcy-risk result, including its distress/grey/safe zone and each of the five weighted components.","content":{"application/json":{"schema":{"type":"object","description":"The Altman Z-Score bankruptcy-risk result, including its distress/grey/safe zone and each of the five weighted components.","properties":{"result":{"type":"object","description":"The Z-Score result.","properties":{"zScore":{"type":"number","description":"The Altman Z-Score. Example: 4.79"},"zone":{"type":"string","enum":["distress","grey","safe"],"description":"Bankruptcy-risk zone based on the Z-Score. Example: \"safe\""},"components":{"type":"object","description":"Each of the five weighted components that sum to the Z-Score.","properties":{"x1WorkingCapitalToAssets":{"type":"object","description":"Working capital / total assets, weighted 1.2x.","properties":{"value":{"type":"number","description":"The raw ratio. Example: 0.25"},"contribution":{"type":"number","description":"The weighted contribution to the Z-Score. Example: 0.3"}}},"x2RetainedEarningsToAssets":{"type":"object","description":"Retained earnings / total assets, weighted 1.4x.","properties":{"value":{"type":"number","description":"The raw ratio. Example: 0.625"},"contribution":{"type":"number","description":"The weighted contribution to the Z-Score. Example: 0.88"}}},"x3EbitToAssets":{"type":"object","description":"EBIT / total assets, weighted 3.3x.","properties":{"value":{"type":"number","description":"The raw ratio. Example: 0.1875"},"contribution":{"type":"number","description":"The weighted contribution to the Z-Score. Example: 0.62"}}},"x4MarketCapToLiabilities":{"type":"object","description":"Market cap / total liabilities, weighted 0.6x.","properties":{"value":{"type":"number","description":"The raw ratio. Example: 2.5"},"contribution":{"type":"number","description":"The weighted contribution to the Z-Score. Example: 1.5"}}},"x5RevenueToAssets":{"type":"object","description":"Revenue / total assets, weighted 1.0x.","properties":{"value":{"type":"number","description":"The raw ratio. Example: 1.5"},"contribution":{"type":"number","description":"The weighted contribution to the Z-Score. Example: 1.5"}}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"SafeZoneCompany":{"summary":"Z-Score for a financially safe company","value":{"result":{"zScore":4.79,"zone":"safe","components":{"x1WorkingCapitalToAssets":{"value":0.25,"contribution":0.3},"x2RetainedEarningsToAssets":{"value":0.625,"contribution":0.88},"x3EbitToAssets":{"value":0.1875,"contribution":0.62},"x4MarketCapToLiabilities":{"value":2.5,"contribution":1.5},"x5RevenueToAssets":{"value":1.5,"contribution":1.5}}},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/piotroski-f-score":{"get":{"summary":"Calculate the Piotroski F-Score — 9 binary fundamental signals across profitability, leverage, and efficiency, summed into a 0-9 strength score.","tags":["Business Finance"],"description":"Calculate the Piotroski F-Score — 9 binary fundamental signals across profitability, leverage, and efficiency, summed into a 0-9 strength score. Use this when a user wants a quick fundamental-quality screen for a value stock. Returns the score and each signal's pass/fail result. Example: \"What is the Piotroski F-Score for a company with ROA 0.08, positive operating cash flow of $2M, decreasing debt ratio, improving current ratio, no new shares issued, improving gross margin, improving asset turnover, improving ROA, and negative accrual?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"roa","required":true,"description":"Return on assets. Example: 0.08"},{"schema":{"type":"string"},"in":"query","name":"ocf","required":true,"description":"Operating cash flow. Example: 2000000"},{"schema":{"type":"string"},"in":"query","name":"deltaDebt","required":true,"description":"Year-over-year change in long-term debt ratio. Example: -0.02"},{"schema":{"type":"string"},"in":"query","name":"deltaLiquidity","required":true,"description":"Year-over-year change in current ratio. Example: 0.1"},{"schema":{"type":"string"},"in":"query","name":"sharesIssued","required":true,"description":"Change in shares outstanding. Example: 0"},{"schema":{"type":"string"},"in":"query","name":"deltaGrossMargin","required":true,"description":"Year-over-year change in gross margin. Example: 0.01"},{"schema":{"type":"string"},"in":"query","name":"deltaAssetTurnover","required":true,"description":"Year-over-year change in asset turnover. Example: 0.03"},{"schema":{"type":"string"},"in":"query","name":"deltaROA","required":true,"description":"Year-over-year change in ROA. Example: 0.01"},{"schema":{"type":"string"},"in":"query","name":"accrual","required":true,"description":"(Net income minus operating cash flow) divided by total assets. Example: -0.02"}],"responses":{"200":{"description":"The Piotroski F-Score (0-9) with a weak/average/strong strength label and each of the 9 underlying binary signals.","content":{"application/json":{"schema":{"type":"object","description":"The Piotroski F-Score (0-9) with a weak/average/strong strength label and each of the 9 underlying binary signals.","properties":{"result":{"type":"object","description":"The F-Score result.","properties":{"score":{"type":"number","description":"Sum of passed signals, 0-9. Example: 9"},"strength":{"type":"string","enum":["weak","average","strong"],"description":"Strength label based on the score. Example: \"strong\""},"signals":{"type":"object","description":"Pass/fail result for each of the 9 underlying fundamental signals.","properties":{"positiveROA":{"type":"boolean","description":"Whether ROA is positive."},"positiveOperatingCashFlow":{"type":"boolean","description":"Whether operating cash flow is positive."},"improvingROA":{"type":"boolean","description":"Whether ROA improved year-over-year."},"qualityOfEarnings":{"type":"boolean","description":"Whether accrual (net income minus OCF over assets) is negative, i.e. cash earnings exceed reported earnings."},"decreasingLeverage":{"type":"boolean","description":"Whether the long-term debt ratio decreased year-over-year."},"improvingLiquidity":{"type":"boolean","description":"Whether the current ratio improved year-over-year."},"noDilutiveIssuance":{"type":"boolean","description":"Whether no new dilutive shares were issued."},"improvingGrossMargin":{"type":"boolean","description":"Whether gross margin improved year-over-year."},"improvingAssetTurnover":{"type":"boolean","description":"Whether asset turnover improved year-over-year."}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"StrongFundamentals":{"summary":"F-Score for a company passing all 9 signals","value":{"result":{"score":9,"strength":"strong","signals":{"positiveROA":true,"positiveOperatingCashFlow":true,"improvingROA":true,"qualityOfEarnings":true,"decreasingLeverage":true,"improvingLiquidity":true,"noDilutiveIssuance":true,"improvingGrossMargin":true,"improvingAssetTurnover":true}},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/dupont-analysis":{"get":{"summary":"Run a DuPont analysis, decomposing return on equity (ROE) into net margin x asset turnover x equity multiplier (3-factor), or a 5-factor version if EBIT and pretax income are supplied.","tags":["Business Finance"],"description":"Run a DuPont analysis, decomposing return on equity (ROE) into net margin x asset turnover x equity multiplier (3-factor), or a 5-factor version if EBIT and pretax income are supplied. Use this when a user wants to understand WHY a company's ROE is high or low, not just what it is. Returns ROE and each component's contribution. Example: \"Break down ROE for a company with $2M net income, $20M revenue, $15M total assets, and $8M equity.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"netIncome","required":true,"description":"Net income. Example: 2000000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 20000000"},{"schema":{"type":"string"},"in":"query","name":"totalAssets","required":true,"description":"Total assets. Example: 15000000"},{"schema":{"type":"string"},"in":"query","name":"equity","required":true,"description":"Shareholders' equity. Example: 8000000"},{"schema":{"type":"string"},"in":"query","name":"ebit","required":false,"description":"Earnings before interest and tax — optional, enables the 5-factor decomposition. Example: 3000000"},{"schema":{"type":"string"},"in":"query","name":"pretaxIncome","required":false,"description":"Pretax income — optional, enables the 5-factor decomposition. Example: 2500000"}],"responses":{"200":{"description":"ROE decomposed into its 3-factor components (always present) and, when EBIT and pretax income are supplied, the 5-factor decomposition.","content":{"application/json":{"schema":{"type":"object","description":"ROE decomposed into its 3-factor components (always present) and, when EBIT and pretax income are supplied, the 5-factor decomposition.","properties":{"result":{"type":"object","description":"The DuPont analysis result.","properties":{"roe":{"type":"number","description":"Return on equity, as a decimal (0.25 = 25%). Example: 0.25"},"threeFactor":{"type":"object","description":"Net margin x asset turnover x equity multiplier decomposition of ROE.","properties":{"netProfitMargin":{"type":"number","description":"Net income / revenue. Example: 0.1"},"assetTurnover":{"type":"number","description":"Revenue / total assets. Example: 1.3333"},"equityMultiplier":{"type":"number","description":"Total assets / equity. Example: 1.875"}}},"fiveFactor":{"type":["null","object"],"description":"Tax burden x interest burden x operating margin x asset turnover x equity multiplier decomposition. Null unless both ebit and pretaxIncome were supplied.","properties":{"taxBurden":{"type":"number","description":"Net income / pretax income. Example: 0.8"},"interestBurden":{"type":"number","description":"Pretax income / EBIT. Example: 0.8333"},"operatingMargin":{"type":"number","description":"EBIT / revenue. Example: 0.15"},"assetTurnover":{"type":"number","description":"Revenue / total assets. Example: 1.3333"},"equityMultiplier":{"type":"number","description":"Total assets / equity. Example: 1.875"}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"FiveFactorBreakdown":{"summary":"3-factor and 5-factor DuPont breakdown of ROE","value":{"result":{"roe":0.25,"threeFactor":{"netProfitMargin":0.1,"assetTurnover":1.3333,"equityMultiplier":1.875},"fiveFactor":{"taxBurden":0.8,"interestBurden":0.8333,"operatingMargin":0.15,"assetTurnover":1.3333,"equityMultiplier":1.875}},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/free-cash-flow":{"get":{"summary":"Calculate free cash flow — operating cash flow minus capital expenditure — plus FCF margin and (if market cap is supplied) FCF yield.","tags":["Business Finance"],"description":"Calculate free cash flow — operating cash flow minus capital expenditure — plus FCF margin and (if market cap is supplied) FCF yield. Use this when a user wants to know how much cash a company generates after reinvesting in itself. Returns free cash flow, FCF margin, and optional FCF yield. Example: \"What is the free cash flow for a company with $4M operating cash flow, $1M capex, and $20M revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"operatingCF","required":true,"description":"Operating cash flow. Example: 4000000"},{"schema":{"type":"string"},"in":"query","name":"capex","required":true,"description":"Capital expenditure. Example: 1000000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 20000000"},{"schema":{"type":"string"},"in":"query","name":"marketCap","required":false,"description":"Market capitalization — optional, enables FCF yield. Example: 50000000"}],"responses":{"200":{"description":"Free cash flow, FCF margin, and (if marketCap supplied) FCF yield.","content":{"application/json":{"schema":{"type":"object","description":"Free cash flow, FCF margin, and (if marketCap supplied) FCF yield.","properties":{"result":{"type":"object","description":"The free cash flow result.","properties":{"freeCashFlow":{"type":"number","description":"Operating cash flow minus capex. Example: 3000000"},"fcfMargin":{"type":"number","description":"Free cash flow as a percentage of revenue. Example: 15"},"fcfYield":{"type":["null","number"],"description":"Free cash flow as a percentage of market cap. Null if marketCap was not supplied. Example: 6"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp when this result was computed."}}}}},"examples":{"4MOperatingCashFlow":{"summary":"FCF for $4M operating cash flow, $1M capex, $20M revenue, $50M market cap","value":{"result":{"freeCashFlow":3000000,"fcfMargin":15,"fcfYield":6},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/wacc":{"get":{"summary":"Calculate weighted average cost of capital (WACC) — the blended required return a company must earn to satisfy both its debt and equity holders.","tags":["Finance"],"description":"Calculate weighted average cost of capital (WACC) — the blended required return a company must earn to satisfy both its debt and equity holders. Use this when a user needs a discount rate for a DCF or wants to assess a company's capital costs. Returns WACC as a percentage, plus a value-creation note if ROIC is supplied. Example: \"What is the WACC for a company with $40M equity, $20M debt, 10% cost of equity, 5% pre-tax cost of debt, and a 25% tax rate?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"equityValue","required":true,"description":"Market value of equity. Example: 40000000"},{"schema":{"type":"string"},"in":"query","name":"debtValue","required":true,"description":"Market value of debt. Example: 20000000"},{"schema":{"type":"string"},"in":"query","name":"costOfEquity","required":true,"description":"Cost of equity, percent. Example: 10"},{"schema":{"type":"string"},"in":"query","name":"costOfDebt","required":true,"description":"Pre-tax cost of debt, percent. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"taxRate","required":true,"description":"Marginal tax rate, percent. Example: 25"},{"schema":{"type":"string"},"in":"query","name":"roic","required":false,"description":"Return on invested capital, percent — optional, adds a value-creation comparison note. Example: 14"}],"responses":{"200":{"description":"The weighted average cost of capital, its equity/debt weights, and an optional value-creation note.","content":{"application/json":{"schema":{"type":"object","description":"The weighted average cost of capital, its equity/debt weights, and an optional value-creation note.","properties":{"result":{"type":"object","description":"WACC calculation results.","properties":{"wacc":{"type":"number","description":"Weighted average cost of capital, as a percentage. Example: 7.92"},"equityWeight":{"type":"number","description":"Equity value as a fraction of total capital (equity + debt). Example: 0.6667"},"debtWeight":{"type":"number","description":"Debt value as a fraction of total capital (equity + debt). Example: 0.3333"},"note":{"type":["null","string"],"description":"Value-creation comparison note if roic was supplied, otherwise null. Example: \"ROIC exceeds WACC — the business is creating value.\""}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FortyMillionEquity":{"summary":"$40M equity, $20M debt, 10% cost of equity, 5% pre-tax cost of debt, 25% tax rate, 14% ROIC","value":{"result":{"wacc":7.92,"equityWeight":0.6667,"debtWeight":0.3333,"note":"ROIC exceeds WACC — the business is creating value."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/capm":{"get":{"summary":"Calculate the required/expected return on an investment using the Capital Asset Pricing Model (CAPM): risk-free rate plus beta times the equity risk premium.","tags":["Finance"],"description":"Calculate the required/expected return on an investment using the Capital Asset Pricing Model (CAPM): risk-free rate plus beta times the equity risk premium. Use this when a user wants a theoretically-required rate of return for a stock or project given its risk (beta) relative to the market. Returns the CAPM expected return. Example: \"What is the CAPM expected return for a stock with a beta of 1.2, a 4% risk-free rate, and an 8% expected market return?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"riskFreeRate","required":true,"description":"Risk-free rate as a percentage, e.g. a government bond yield. Example: 4"},{"schema":{"type":"string"},"in":"query","name":"beta","required":true,"description":"The asset's beta — volatility relative to the market. Example: 1.2"},{"schema":{"type":"string"},"in":"query","name":"expectedMarketReturn","required":true,"description":"Expected return of the overall market as a percentage. Example: 8"}],"responses":{"200":{"description":"The CAPM expected return and the equity risk premium it was derived from.","content":{"application/json":{"schema":{"type":"object","description":"The CAPM expected return and the equity risk premium it was derived from.","properties":{"result":{"type":"object","description":"CAPM results.","properties":{"expectedReturn":{"type":"number","description":"CAPM expected/required return, as a percentage. Example: 8.8"},"equityRiskPremium":{"type":"number","description":"Expected market return minus the risk-free rate, as a percentage. Example: 4"}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"Beta1_2":{"summary":"CAPM for a beta 1.2 stock, 4% risk-free rate, 8% expected market return","value":{"result":{"expectedReturn":8.8,"equityRiskPremium":4},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/valuation-multiples":{"get":{"summary":"Calculate standard valuation multiples — EV/EBITDA, P/E, P/B, P/S, and EV/Revenue — from a company's financials.","tags":["Finance"],"description":"Calculate standard valuation multiples — EV/EBITDA, P/E, P/B, P/S, and EV/Revenue — from a company's financials. Use this when a user wants a quick set of valuation ratios to compare against peers or historical norms. Returns all five multiples. Example: \"What are the valuation multiples for a company with $50M market cap, $5M net debt, $8M EBITDA, $4M earnings, $15M book value, and $30M revenue?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"marketCap","required":true,"description":"Market capitalization. Example: 50000000"},{"schema":{"type":"string"},"in":"query","name":"netDebt","required":true,"description":"Net debt. Example: 5000000"},{"schema":{"type":"string"},"in":"query","name":"ebitda","required":true,"description":"EBITDA. Example: 8000000"},{"schema":{"type":"string"},"in":"query","name":"earnings","required":true,"description":"Net earnings. Example: 4000000"},{"schema":{"type":"string"},"in":"query","name":"bookValue","required":true,"description":"Book value of equity. Example: 15000000"},{"schema":{"type":"string"},"in":"query","name":"revenue","required":true,"description":"Revenue. Example: 30000000"}],"responses":{"200":{"description":"Standard valuation multiples derived from the company's financials.","content":{"application/json":{"schema":{"type":"object","description":"Standard valuation multiples derived from the company's financials.","properties":{"result":{"type":"object","description":"Valuation multiples results.","properties":{"enterpriseValue":{"type":"number","description":"Market cap plus net debt. Example: 55000000"},"evToEbitda":{"type":["null","number"],"description":"Enterprise value / EBITDA; null if ebitda is 0. Example: 6.88"},"priceToEarnings":{"type":["null","number"],"description":"Market cap / earnings; null if earnings is 0. Example: 12.5"},"priceToBook":{"type":["null","number"],"description":"Market cap / book value; null if bookValue is 0. Example: 3.33"},"priceToSales":{"type":["null","number"],"description":"Market cap / revenue; null if revenue is 0. Example: 1.67"},"evToRevenue":{"type":["null","number"],"description":"Enterprise value / revenue; null if revenue is 0. Example: 1.83"}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FiftyMillionMarketCap":{"summary":"$50M market cap, $5M net debt, $8M EBITDA, $4M earnings, $15M book value, $30M revenue","value":{"result":{"enterpriseValue":55000000,"evToEbitda":6.88,"priceToEarnings":12.5,"priceToBook":3.33,"priceToSales":1.67,"evToRevenue":1.83},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sharpe-ratio":{"get":{"summary":"Calculate the Sharpe ratio — risk-adjusted return per unit of total volatility.","tags":["Finance"],"description":"Calculate the Sharpe ratio — risk-adjusted return per unit of total volatility. Use this when a user wants to compare investments or portfolios on a risk-adjusted basis, not just raw return. Returns the Sharpe ratio. Example: \"What is the Sharpe ratio for a portfolio with a 12% return, a 3% risk-free rate, and 15% standard deviation?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"portfolioReturn","required":true,"description":"Portfolio return, percent. Example: 12"},{"schema":{"type":"string"},"in":"query","name":"riskFreeRate","required":true,"description":"Risk-free rate, percent. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"standardDeviation","required":true,"description":"Portfolio standard deviation, percent. Example: 15"}],"responses":{"200":{"description":"The Sharpe ratio and a qualitative benchmark for it.","content":{"application/json":{"schema":{"type":"object","description":"The Sharpe ratio and a qualitative benchmark for it.","properties":{"result":{"type":"object","description":"Sharpe ratio results.","properties":{"ratio":{"type":"number","description":"Sharpe ratio: excess return per unit of total volatility. Example: 0.6"},"benchmark":{"type":"string","enum":["poor","acceptable","good"],"description":"Qualitative rating of the ratio (poor <1, acceptable 1-2, good >2). Example: \"poor\""}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"TwelvePercentReturn":{"summary":"12% return, 3% risk-free rate, 15% standard deviation","value":{"result":{"ratio":0.6,"benchmark":"poor"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sortino-ratio":{"get":{"summary":"Calculate the Sortino ratio — like the Sharpe ratio but penalizing only downside volatility, not total volatility.","tags":["Finance"],"description":"Calculate the Sortino ratio — like the Sharpe ratio but penalizing only downside volatility, not total volatility. Use this when a user wants a risk-adjusted return measure that doesn't penalize upside swings. Returns the Sortino ratio. Example: \"What is the Sortino ratio for a portfolio with a 12% return, a 3% risk-free rate, and 8% downside deviation?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"portfolioReturn","required":true,"description":"Portfolio return, percent. Example: 12"},{"schema":{"type":"string"},"in":"query","name":"riskFreeRate","required":true,"description":"Risk-free rate, percent. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"downsideDeviation","required":true,"description":"Downside deviation, percent. Example: 8"}],"responses":{"200":{"description":"The Sortino ratio — excess return per unit of downside volatility only.","content":{"application/json":{"schema":{"type":"object","description":"The Sortino ratio — excess return per unit of downside volatility only.","properties":{"result":{"type":"object","description":"Sortino ratio results.","properties":{"ratio":{"type":"number","description":"Sortino ratio: excess return per unit of downside deviation. Example: 1.13"}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"TwelvePercentReturn":{"summary":"12% return, 3% risk-free rate, 8% downside deviation","value":{"result":{"ratio":1.13},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/levered-beta":{"get":{"summary":"Apply the Hamada equation to re-lever or unlever a beta, so betas can be compared across companies with different capital structures.","tags":["Finance"],"description":"Apply the Hamada equation to re-lever or unlever a beta, so betas can be compared across companies with different capital structures. Use this when a user wants to strip out or add back the effect of leverage on a stock's beta, e.g. when adapting a comparable company's beta to a different debt level. Returns the re-levered or unlevered beta. Example: \"What is the unlevered beta for a stock with a levered beta of 1.4, a debt-to-equity ratio of 0.5, and a 25% tax rate?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"beta","required":true,"description":"Unlevered beta if direction is lever, levered beta if direction is unlever. Example: 1.4"},{"schema":{"type":"string"},"in":"query","name":"debtToEquity","required":true,"description":"Debt-to-equity ratio. Example: 0.5"},{"schema":{"type":"string"},"in":"query","name":"taxRate","required":true,"description":"Marginal tax rate, percent. Example: 25"},{"schema":{"type":"string","enum":["lever","unlever"]},"in":"query","name":"direction","required":true,"description":"'lever' to add leverage to an unlevered beta, 'unlever' to strip leverage from a levered beta. Example: \"unlever\""}],"responses":{"200":{"description":"The re-levered or unlevered beta.","content":{"application/json":{"schema":{"type":"object","description":"The re-levered or unlevered beta.","properties":{"result":{"type":"object","description":"Hamada beta results.","properties":{"adjustedBeta":{"type":"number","description":"The re-levered or unlevered beta. Example: 1.0182"},"direction":{"type":"string","enum":["lever","unlever"],"description":"Which direction the adjustment was applied, echoed from the input. Example: \"unlever\""}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"UnleverBeta1_4":{"summary":"Unlever a beta of 1.4 with a 0.5 debt-to-equity ratio and 25% tax rate","value":{"result":{"adjustedBeta":1.0182,"direction":"unlever"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/risk-free-rate":{"get":{"summary":"Look up the current 10-year government bond yield for the US, UK, or EU, sourced from FRED and cached 24h.","tags":["Finance"],"description":"Look up the current 10-year government bond yield for the US, UK, or EU, sourced from FRED and cached 24h. Use this when a user needs an up-to-date risk-free rate as an input to CAPM, Sharpe ratio, or Sortino ratio calculations. Returns the current yield as a percentage. Example: \"What is the current risk-free rate for the US?\"","parameters":[{"schema":{"type":"string","enum":["US","UK","EU"]},"in":"query","name":"region","required":true,"description":"Region to fetch the risk-free rate for. Example: \"US\""}],"responses":{"200":{"description":"The current 10-year government bond yield for the requested region.","content":{"application/json":{"schema":{"type":"object","description":"The current 10-year government bond yield for the requested region.","properties":{"result":{"type":"object","description":"The risk-free rate lookup.","properties":{"region":{"type":"string","enum":["US","UK","EU"],"description":"The region that was queried."},"yieldPercent":{"type":"number","description":"The 10-year government bond yield, as a percentage. Example: 4.28"},"date":{"type":"string","description":"The date this observation is from, per FRED. Example: \"2026-08-07\""},"sourceUrl":{"type":"string","description":"The FRED series page this figure was sourced from."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"cached":{"type":"boolean","description":"Whether this value came from cache rather than a live FRED fetch."},"source":{"type":"string","description":"The FRED series URL this figure was sourced from — same value as result.sourceUrl."},"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}},"examples":{"UsTenYear":{"summary":"Current US 10-year Treasury yield","value":{"result":{"region":"US","yieldPercent":4.28,"date":"2026-08-07","sourceUrl":"https://fred.stlouisfed.org/series/DGS10"},"meta":{"cached":false,"source":"https://fred.stlouisfed.org/series/DGS10","computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/yield-curve":{"get":{"summary":"Live US Treasury yield curve across 9 maturities, with inversion detection.","tags":["Finance"],"description":"Fetches the current US Treasury yield curve from FRED (DGS3MO … DGS30). Returns all 9 yields, inversion flags, and basis-point spread. Cached 24h.","responses":{"200":{"description":"The current US Treasury yield curve.","content":{"application/json":{"schema":{"type":"object","description":"The current US Treasury yield curve.","properties":{"result":{"type":"object","description":"The yield curve snapshot.","properties":{"yields":{"type":"array","description":"Yield observations across all 9 maturities, ordered shortest to longest.","items":{"type":"object","properties":{"label":{"type":"string","description":"Human-readable maturity label. Example: \"10-Year\""},"maturity":{"type":"string","description":"Short maturity code. Example: \"10Y\""},"years":{"type":"number","description":"Maturity in years. Example: 10"},"yieldPercent":{"type":"number","description":"The yield, as a percentage. Example: 4.28"},"date":{"type":"string","description":"The FRED observation date for this maturity."}}}},"tenYearYield":{"type":"number","description":"The 10-year yield, for convenience — this is the value handed off to the Black-Scholes pricer."},"threeMonthYield":{"type":"number","description":"The 3-month yield, used for the primary inversion check."},"twoYearYield":{"type":"number","description":"The 2-year yield, used for the secondary inversion check."},"isInverted":{"type":"boolean","description":"True when the 3-month yield exceeds the 10-year yield — the most-watched recession signal."},"is2Y10YInverted":{"type":"boolean","description":"True when the 2-year yield exceeds the 10-year yield — a secondary recession signal."},"inversionBps":{"type":"number","description":"(3-month yield − 10-year yield) × 100, in basis points. Negative means not inverted."},"sourceUrl":{"type":"string","description":"The FRED series page this data was sourced from."},"dataDate":{"type":"string","description":"The observation date of the most recent (10-year) data point."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"cached":{"type":"boolean","description":"Whether this value came from cache rather than a live FRED fetch."},"source":{"type":"string","description":"The FRED series URL this data was sourced from."},"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}}}}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sp500-returns":{"get":{"summary":"Annual S&P 500 returns from 1928 to present, with CAGR, volatility, and best/worst year statistics.","tags":["Finance"],"description":"Annual S&P 500 returns from 1928 to present, with CAGR, volatility, and best/worst year statistics.","parameters":[{"schema":{"type":"string"},"in":"query","name":"startYear","required":false,"description":"First year to include. Defaults to the earliest available year (1928). Example: \"2000\""},{"schema":{"type":"string"},"in":"query","name":"endYear","required":false,"description":"Last year to include. Defaults to the latest available year. Example: \"2025\""},{"schema":{"type":"string","enum":["total","price","real"]},"in":"query","name":"returnType","required":false,"description":"Which return figure to use. Defaults to \"total\". Example: \"total\""}],"responses":{"200":{"description":"S&P 500 historical return statistics over the requested period.","content":{"application/json":{"schema":{"type":"object","description":"S&P 500 historical return statistics over the requested period.","properties":{"result":{"type":"object","properties":{"startYear":{"type":"number"},"endYear":{"type":"number"},"returnType":{"type":"string","enum":["total","price","real"]},"years":{"type":"number"},"cagr":{"type":"number","description":"Compound annual growth rate over the period, as a decimal."},"arithmeticMean":{"type":"number","description":"Simple average of annual returns, as a decimal."},"standardDeviation":{"type":"number","description":"Annualised volatility of returns, as a decimal."},"bestYear":{"type":"object","properties":{"year":{"type":"number"},"return":{"type":"number"}}},"worstYear":{"type":"object","properties":{"year":{"type":"number"},"return":{"type":"number"}}},"positiveYears":{"type":"number"},"negativeYears":{"type":"number"},"positiveYearPercent":{"type":"number"},"data":{"type":"array","description":"The raw annual series, filtered to the requested range.","items":{"type":"object","properties":{"year":{"type":"number"},"priceReturn":{"type":"number"},"totalReturn":{"type":"number"},"realReturn":{"type":"number"},"inflationRate":{"type":"number"}}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/purchasing-power":{"get":{"summary":"Convert a dollar amount between any two years using US CPI-U data (1913–2024).","tags":["Finance"],"description":"Convert a dollar amount between any two years using US CPI-U data (1913–2024).","parameters":[{"schema":{"type":"string"},"in":"query","name":"amount","required":true,"description":"The original dollar amount. Must be greater than 0. Example: \"100\""},{"schema":{"type":"string"},"in":"query","name":"fromYear","required":true,"description":"The source year, 1913–2024. Example: \"1970\""},{"schema":{"type":"string"},"in":"query","name":"toYear","required":true,"description":"The target year, 1913–2024. Example: \"2024\""}],"responses":{"200":{"description":"The inflation-adjusted equivalent amount, plus context milestones.","content":{"application/json":{"schema":{"type":"object","description":"The inflation-adjusted equivalent amount, plus context milestones.","properties":{"result":{"type":"object","properties":{"fromYear":{"type":"number"},"toYear":{"type":"number"},"originalAmount":{"type":"number"},"adjustedAmount":{"type":"number"},"totalInflationPercent":{"type":"number"},"cagr":{"type":"number"},"years":{"type":"number"},"fromCpi":{"type":"number"},"toCpi":{"type":"number"},"milestones":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"cpi":{"type":"number"},"adjustedAmount":{"type":"number"}}}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sector-betas":{"get":{"summary":"List industry beta references for every covered sector","tags":["Finance"],"description":"Lists the levered beta, unlevered beta, debt-to-equity, and sample size for every sector this API has an industry beta reference for. Use this when a user wants to browse or search available sectors before looking one up by name. Returns the full list of sectors with their beta data.","responses":{"200":{"description":"Every covered sector with its beta data, sorted alphabetically.","content":{"application/json":{"schema":{"type":"object","description":"Every covered sector with its beta data, sorted alphabetically.","properties":{"sectors":{"type":"array","description":"Every covered sector with its beta data.","items":{"type":"object","description":"One sector: name, levered beta, unlevered beta, debt-to-equity, and sample size.","properties":{"sector":{"type":"string","description":"Sector name. Example: \"Software (System & Application)\""},"leveredBeta":{"type":"number","description":"The sector's levered (equity) beta."},"unleveredBeta":{"type":"number","description":"The sector's unlevered (asset) beta, stripped of financing effects."},"debtToEquity":{"type":"number","description":"Average debt-to-equity ratio for firms in this sector."},"firmsInSample":{"type":"number","description":"Number of firms the average is drawn from."},"year":{"type":"number","description":"The data year. Example: 2025"}}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"FirstThreeSectors":{"summary":"The first few sectors in the list (alphabetical)","value":{"sectors":[{"sector":"Advertising","leveredBeta":1.7,"unleveredBeta":1.2,"debtToEquity":0.55,"firmsInSample":219,"year":2025},{"sector":"Aerospace/Defense","leveredBeta":1.17,"unleveredBeta":0.93,"debtToEquity":0.35,"firmsInSample":207,"year":2025},{"sector":"Air Transport","leveredBeta":1.95,"unleveredBeta":1.07,"debtToEquity":1.1,"firmsInSample":195,"year":2025}]}}}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/sector-betas/{sector}":{"get":{"summary":"Look up an industry beta reference for a named sector","tags":["Finance"],"description":"Look up an industry beta reference for a named sector. Use this when a user needs a beta for CAPM but doesn't have a company-specific one — a common substitute for private companies or new ventures. Returns levered beta, unlevered beta, debt-to-equity, and sample size for the sector.","parameters":[{"schema":{"type":"string"},"in":"path","name":"sector","required":true,"description":"URL-encoded sector name. Example: \"Software%20(System%20%26%20Application)\""}],"responses":{"200":{"description":"The industry beta reference for the requested sector.","content":{"application/json":{"schema":{"type":"object","description":"The industry beta reference for the requested sector.","properties":{"result":{"type":"object","description":"The sector beta lookup.","properties":{"sector":{"type":"string","description":"Sector name, as given in the request. Example: \"Software (System & Application)\""},"leveredBeta":{"type":"number","description":"The sector's levered (equity) beta. Example: 1.55"},"unleveredBeta":{"type":"number","description":"The sector's unlevered (asset) beta, stripped of financing effects."},"debtToEquity":{"type":"number","description":"Average debt-to-equity ratio for firms in this sector."},"firmsInSample":{"type":"number","description":"Number of firms the average is drawn from."},"year":{"type":"number","description":"The data year. Example: 2025"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"SoftwareSector":{"summary":"Beta reference for the Software (System & Application) sector","value":{"result":{"sector":"Software (System & Application)","leveredBeta":1.55,"unleveredBeta":1.44,"debtToEquity":0.1,"firmsInSample":252,"year":2025},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/market-risk-premium":{"get":{"summary":"Look up a country equity risk premium (ERP) estimate, for use as the (Rm - Rf) input to CAPM.","tags":["Finance"],"description":"Look up a country equity risk premium (ERP) estimate, for use as the (Rm - Rf) input to CAPM. Use this when a user needs a country-specific equity risk premium for a valuation model. The figures are fixed reference estimates, not derived from live market prices; see the provenance field on the response for what the data is. Returns the estimated ERP. Example: \"What is the equity risk premium for Brazil?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"BRA\""}],"responses":{"200":{"description":"The implied equity risk premium for the requested country.","content":{"application/json":{"schema":{"type":"object","description":"The implied equity risk premium for the requested country.","properties":{"result":{"type":"object","description":"Market risk premium lookup results.","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-3 country code, echoed from the input. Example: \"BRA\""},"countryName":{"type":"string","description":"Full country name. Example: \"Brazil\""},"impliedERP":{"type":"number","description":"Implied equity risk premium, as a percentage. Example: 8.1"},"year":{"type":"number","description":"Year the dataset reflects. Example: 2025"},"source":{"type":"string","description":"Data source description."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."},"source":{"type":"string","description":"Data source description, same as result.source."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"Brazil":{"summary":"Equity risk premium for Brazil","value":{"result":{"country":"BRA","countryName":"Brazil","impliedERP":8.1,"year":2025,"source":"Damodaran Online (NYU Stern) — country implied ERP, styled after the January 2025 table"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z","source":"Damodaran Online (NYU Stern) — country implied ERP, styled after the January 2025 table"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/car-buy-vs-lease":{"get":{"summary":"Compare buying vs leasing a car over a chosen ownership horizon.","tags":["Finance"],"description":"Compare buying vs leasing a car over a chosen ownership horizon. Use this when a user is deciding whether to buy or lease a vehicle and wants to see which is cheaper, including the opportunity cost of a down payment. Returns total cost, break-even ownership horizon, opportunity cost of the down payment, and net worth at your ownership horizon under each scenario. Example: \"Should I buy or lease a $35,000 car if I plan to keep it for 5 years?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"vehiclePrice","required":true,"description":"Vehicle purchase price"},{"schema":{"type":"string"},"in":"query","name":"downPayment","required":true,"description":"Cash down payment for the purchase (buy scenario only)"},{"schema":{"type":"string"},"in":"query","name":"loanRate","required":true,"description":"Auto loan annual interest rate, percent"},{"schema":{"type":"string"},"in":"query","name":"loanTermMonths","required":true,"description":"Auto loan term, months"},{"schema":{"type":"string"},"in":"query","name":"leaseMonthlyPayment","required":true,"description":"Quoted monthly lease payment"},{"schema":{"type":"string"},"in":"query","name":"leaseTermMonths","required":true,"description":"Lease term, months"},{"schema":{"type":"string"},"in":"query","name":"moneyFactor","required":true,"description":"Lease money factor (e.g. 0.00125), used to cross-check the quoted lease payment"},{"schema":{"type":"string"},"in":"query","name":"residualValuePct","required":true,"description":"Residual value at lease-end, as a percent of vehiclePrice"},{"schema":{"type":"string"},"in":"query","name":"annualMileage","required":true,"description":"Expected annual mileage"},{"schema":{"type":"string"},"in":"query","name":"excessMileageCharge","required":true,"description":"Lease charge per mile over the assumed 12,000 mi/yr allowance"},{"schema":{"type":"string"},"in":"query","name":"ownershipYears","required":true,"description":"Planning horizon, years"},{"schema":{"type":"string"},"in":"query","name":"expectedAppreciationRate","required":true,"description":"Annual vehicle value change, percent (negative for typical depreciation)"},{"schema":{"type":"string"},"in":"query","name":"opportunityCostRate","required":true,"description":"Annual return foregone on cash tied up in the down payment, percent"}],"responses":{"200":{"description":"Total cost, break-even horizon, and net worth outcome comparing buying vs leasing the vehicle.","content":{"application/json":{"schema":{"type":"object","description":"Total cost, break-even horizon, and net worth outcome comparing buying vs leasing the vehicle.","properties":{"result":{"type":"object","description":"Buy-vs-lease comparison results.","properties":{"buyTotalCost":{"type":"number","description":"Total cash paid under the buy scenario through the ownership horizon. Example: 40219.07"},"leaseTotalCost":{"type":"number","description":"Total cash paid under the lease scenario through the ownership horizon. Example: 27000"},"buyMonthlyPayment":{"type":"number","description":"Monthly auto loan payment. Example: 586.98"},"impliedLeaseMonthlyPayment":{"type":"number","description":"Lease payment implied by moneyFactor and residualValuePct, as a cross-check against the quoted leaseMonthlyPayment. Example: 505.31"},"residualValue":{"type":"number","description":"Vehicle's residual value at lease-end. Example: 19250"},"breakEvenYears":{"type":["null","number"],"description":"First whole year buying's net worth outcome catches up to leasing's, or null if not within 15 years. Example: 3"},"opportunityCostOfDownPayment":{"type":"number","description":"Foregone investment return on cash tied up in the down payment. Example: 1381.41"},"netWorthBuyAtHorizon":{"type":"number","description":"Net worth impact of buying at the ownership horizon. Example: -21748.45"},"netWorthLeaseAtHorizon":{"type":"number","description":"Net worth impact of leasing at the ownership horizon. Example: -27000"},"verdict":{"type":"string","enum":["buy","lease","roughly equivalent"],"description":"Which option comes out ahead at the ownership horizon. Example: \"buy\""}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when the result was computed."}}}}},"examples":{"FiveYearOwnership":{"summary":"Buy vs lease a $35,000 car over a 5-year ownership horizon","value":{"result":{"buyTotalCost":40219.07,"leaseTotalCost":27000,"buyMonthlyPayment":586.98,"impliedLeaseMonthlyPayment":505.31,"residualValue":19250,"breakEvenYears":3,"opportunityCostOfDownPayment":1381.41,"netWorthBuyAtHorizon":-21748.45,"netWorthLeaseAtHorizon":-27000,"verdict":"buy"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/buy-vs-rent-full":{"get":{"summary":"Compare buying vs renting with full affordability and investment context","tags":["Composite"],"description":"Compares buying a home against renting and investing the difference, combined with affordability and house-price-to-income context. Use this when a user wants a comprehensive buy-vs-rent analysis, not just the raw net-worth comparison. Returns break-even year, net worth under each scenario, and affordability context.","parameters":[{"schema":{"type":"string"},"in":"query","name":"monthlyGrossIncome","required":true,"description":"Gross monthly household income. Example: 8000"},{"schema":{"type":"string"},"in":"query","name":"depositAvailable","required":true,"description":"Deposit/down payment available. Example: 60000"},{"schema":{"type":"string"},"in":"query","name":"propertyPrice","required":true,"description":"Property purchase price. Example: 400000"},{"schema":{"type":"string"},"in":"query","name":"monthlyRent","required":true,"description":"Monthly rent for the equivalent rental. Example: 1800"},{"schema":{"type":"string"},"in":"query","name":"mortgageRate","required":true,"description":"Annual mortgage interest rate as a percentage. Example: 6.5"},{"schema":{"type":"string"},"in":"query","name":"termYears","required":true,"description":"Mortgage term in years. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"investmentReturnRate","required":true,"description":"Annual return the renter earns investing the deposit and any savings, as a percentage. Example: 7"},{"schema":{"type":"string"},"in":"query","name":"propertyAppreciationRate","required":true,"description":"Annual property value change as a percentage, can be negative. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"yearsHorizon","required":true,"description":"Years to compare over. Example: 10"},{"schema":{"type":"string"},"in":"query","name":"country","required":false,"description":"Optional ISO 3166-1 alpha-3 country code, for house-price-to-income context. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"vacancyRatePercent","required":false,"description":"Optional expected vacancy rate as a percentage, defaults to 5. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"annualMaintenance","required":false,"description":"Optional annual maintenance cost, defaults to 1% of property price. Example: 4000"},{"schema":{"type":"string"},"in":"query","name":"purchaseCostsPercent","required":false,"description":"Optional one-off purchase costs as a percentage of property price. Example: 3"}],"responses":{"200":{"description":"A buy-vs-rent-and-invest net worth projection with affordability, stress-test and rental-yield context.","content":{"application/json":{"schema":{"type":"object","description":"A buy-vs-rent-and-invest net worth projection with affordability, stress-test and rental-yield context.","properties":{"result":{"type":"object","description":"The comparison result.","properties":{"maxAffordableProperty":{"type":"object","description":"What the household could afford to borrow, independent of the specific property price given.","properties":{"maxPropertyPrice":{"type":"number","description":"Maximum property price affordable at the given income, deposit, rate and term."},"withinBudget":{"type":"boolean","description":"Whether the given propertyPrice is within that maximum."}}},"housePriceToIncome":{"type":"object","description":"How the property price compares to gross household income.","properties":{"priceToIncomeRatio":{"type":"number","description":"Property price divided by gross annual household income."},"affordabilityClass":{"type":"string","description":"Affordability bucket for that ratio, e.g. \"affordable\", \"stretched\", \"unaffordable\", \"severelyUnaffordable\"."}}},"stressTest":{"type":"object","description":"How the mortgage payment would change if rates rose.","properties":{"firstBreachAtBumpPp":{"type":["null","number"],"description":"The smallest rate increase (in percentage points) at which the payment breaches 35% of gross income. Null if no tested bump breaches it."},"monthlyPaymentAtCurrentRate":{"type":"number","description":"Monthly mortgage payment at the given rate."},"monthlyPaymentAtPlus3pp":{"type":"number","description":"Monthly mortgage payment if the rate rose by 3 percentage points."}}},"rentalYieldContext":{"type":"object","description":"Supplementary landlord-yield context for the same property, at the given rent.","properties":{"grossYieldPercent":{"type":"number","description":"Annual rent as a percentage of purchase price, before costs."},"netYieldPercent":{"type":"number","description":"Annual rent after vacancy and maintenance, as a percentage of total investment including purchase costs."},"priceToRentRatio":{"type":"number","description":"Purchase price divided by annual rent."}}},"opportunityCostOfDeposit":{"type":"number","description":"Interest the deposit alone would have earned if invested instead, over the horizon, ignoring any monthly rent-vs-mortgage savings."},"breakEvenYear":{"type":["null","number"],"description":"First year (up to 30) in which buying's net worth catches up to renting-and-investing's. Null if it never does within that window."},"netWorthAtHorizon":{"type":"object","description":"Net worth under each scenario at yearsHorizon.","properties":{"buy":{"type":"number","description":"Home equity minus total cash paid (deposit + all mortgage payments to date)."},"rentAndInvest":{"type":"number","description":"Value of the deposit plus any monthly savings from renting, invested at investmentReturnRate."},"difference":{"type":"number","description":"buy minus rentAndInvest."}}},"verdict":{"type":"string","enum":["buy","rent","roughly equivalent"],"description":"Which scenario comes out ahead at the horizon, or \"roughly equivalent\" if the difference is under 1% of property price."},"inflation":{"type":"object","description":"Illustrative historical inflation context over a same-length window ending at the latest available CPI year (this dataset can't forecast forward).","properties":{"country":{"type":"string","description":"Country used for the CPI lookup."},"period":{"type":"string","description":"The historical year range used, e.g. \"2015–2025\"."},"purchasingPowerLostPercent":{"type":["null","number"],"description":"Percent purchasing power a rent-sized income lost to inflation over that period. Null if CPI data was unavailable for this country."}}},"assumptions":{"type":"object","description":"Echo of the rate/horizon inputs used, for display alongside the result.","properties":{"mortgageRate":{"type":"number","description":"Annual mortgage interest rate used, as a percentage."},"propertyAppreciationRate":{"type":"number","description":"Annual property value change used, as a percentage."},"investmentReturnRate":{"type":"number","description":"Annual investment return used, as a percentage."},"yearsHorizon":{"type":"number","description":"Comparison horizon in years."},"termYears":{"type":"number","description":"Mortgage term in years."}}},"caveat":{"type":"string","description":"Explains what netWorthAtHorizon does and doesn't account for."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually contributed to this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"low\" if the supplementary inflation context was unavailable for the given country, \"high\" otherwise."}}}}},"examples":{"UsHomeVsRent":{"summary":"A $400,000 US home vs renting at $1,800/month, 10-year horizon","value":{"result":{"maxAffordableProperty":{"maxPropertyPrice":502990.29,"withinBudget":true},"housePriceToIncome":{"priceToIncomeRatio":4.17,"affordabilityClass":"stretched"},"stressTest":{"firstBreachAtBumpPp":3,"monthlyPaymentAtCurrentRate":2149.03,"monthlyPaymentAtPlus3pp":2858.9},"rentalYieldContext":{"grossYieldPercent":5.4,"netYieldPercent":4.01,"priceToRentRatio":18.52},"opportunityCostOfDeposit":60579.68,"breakEvenYear":null,"netWorthAtHorizon":{"buy":-68556.03,"rentAndInvest":181344.1,"difference":-249900.13},"verdict":"rent","inflation":{"country":"USA","period":"2015–2025","purchasingPowerLostPercent":21.88},"assumptions":{"mortgageRate":6.5,"propertyAppreciationRate":3,"investmentReturnRate":7,"yearsHorizon":10,"termYears":30},"caveat":"netWorthAtHorizon compares home equity minus total cash paid (deposit + all mortgage payments) against an invested deposit plus any monthly saving from renting being cheaper than the mortgage payment — it does not separately credit rent avoided, only the resulting cash positions. A mortgage payment lower than rent still shows as a cash outlay here, same as car-buy-vs-lease treats loan payments."},"components":["max-affordable-property","house-price-to-income","mortgage-stress-test","rental-yield","compound-interest","real-income-erosion"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/salary-negotiation-brief":{"get":{"summary":"Get a data-backed salary negotiation brief","tags":["Composite"],"description":"Combines national salary percentile and degree-field salary benchmarks into a single negotiation brief. Use this when a user is preparing to negotiate a salary and wants market data to back up their ask. Returns their national percentile, a degree-field salary benchmark, and a suggested target range.","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"currentGrossSalary","required":true,"description":"Current gross annual salary. Example: 85000"},{"schema":{"type":"string"},"in":"query","name":"degreeField","required":true,"description":"Degree field, e.g. \"Computer Science\". Example: \"Computer Science\""},{"schema":{"type":"string"},"in":"query","name":"yearsOfExperience","required":true,"description":"Years of professional experience. Example: 6"},{"schema":{"type":"string","enum":["highSchool","associate","bachelor","master","doctoral"]},"in":"query","name":"educationLevel","required":true,"description":"Highest education level attained. Example: \"bachelor\""},{"schema":{"type":"string"},"in":"query","name":"currentAge","required":true,"description":"Current age. Example: 30"},{"schema":{"type":"string"},"in":"query","name":"weeklyHours","required":true,"description":"Typical hours worked per week. Example: 40"},{"schema":{"type":"string"},"in":"query","name":"householdSize","required":false,"description":"Optional household size, for income-percentile context, defaults to 1. Example: 1"},{"schema":{"type":"string"},"in":"query","name":"usState","required":false,"description":"Optional 2-letter US state code, refines the degree salary benchmark. Example: \"CA\""}],"responses":{"200":{"description":"A data-backed salary negotiation brief.","content":{"application/json":{"schema":{"type":"object","description":"A data-backed salary negotiation brief.","properties":{"result":{"type":"object","description":"The negotiation brief.","properties":{"nationalPercentile":{"type":"object","description":"Where the given salary ranks within the given country's own income distribution.","properties":{"percentile":{"type":"number","description":"National salary percentile, 0-100."},"multipleOfMeanWage":{"type":"number","description":"currentGrossSalary as a multiple of the country's mean annual wage."}}},"degreeBenchmark":{"type":"object","description":"US market benchmark for the given degree field and experience.","properties":{"occupationTitle":{"type":"string","description":"Benchmark occupation title for the given degree field."},"medianSalary":{"type":"number","description":"US median salary for this occupation, adjusted for years of experience (and state, if usState was given)."},"p75Salary":{"type":"number","description":"US 75th-percentile salary for this occupation, similarly adjusted."},"tenYearGrowthOutlookPercent":{"type":"number","description":"Projected 10-year employment growth outlook for this occupation, as a percentage."}}},"gapToP75":{"type":"object","description":"Gap between the current salary and the given country's 75th percentile of earners.","properties":{"countryP75Salary":{"type":"number","description":"The country's 75th-percentile annual salary."},"dollarGap":{"type":"number","description":"countryP75Salary minus currentGrossSalary. Negative means already above it."},"percentGap":{"type":"number","description":"dollarGap as a percentage of currentGrossSalary."}}},"workingHours":{"type":"object","description":"How the given weekly hours compare to national and OECD averages.","properties":{"annualHours":{"type":"number","description":"weeklyHours annualized (x52)."},"percentVsNationalAverage":{"type":"number","description":"annualHours vs the given country's national average, as a percentage."},"percentVsOecdAverage":{"type":"number","description":"annualHours vs the OECD average, as a percentage."}}},"globalIncomeContext":{"type":["null","object"],"description":"Global and within-country income percentile context. Null if income-percentile data was unavailable for this country (its country list doesn't exactly match the national-percentile dataset).","properties":{"globalPercentile":{"type":"number","description":"Percentile among the world's population, by per-capita PPP income."},"withinCountryPercentile":{"type":"number","description":"Percentile within the given country's own income distribution (household-size-adjusted)."}}},"raiseImpact":{"type":"array","description":"Projected effect of 10%, 15%, and 20% raise scenarios.","items":{"type":"object","properties":{"raisePercent":{"type":"number","description":"The raise scenario percentage."},"newSalary":{"type":"number","description":"currentGrossSalary after this raise."},"lifetimeEarningsIncrease":{"type":"number","description":"Approximate increase to projected lifetime earnings to age 65 under this raise, scaling the baseline earnings curve proportionally."}}}},"negotiationSummary":{"type":"string","description":"A prose summary of the brief, combining the figures above."},"caveat":{"type":"string","description":"Explains the lifetime-earnings scaling approximation and that benchmarks are illustrative market data."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually returned data for this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"high\" when every component had data; \"low\" if income-percentile was unavailable for this country."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsSoftwareDeveloperSixYears":{"summary":"A US$85,000 Computer Science degree holder with 6 years of experience, in the USA","value":{"result":{"nationalPercentile":{"percentile":88,"multipleOfMeanWage":1.87},"degreeBenchmark":{"occupationTitle":"Software Developer","medianSalary":117000,"p75Salary":157500,"tenYearGrowthOutlookPercent":17},"gapToP75":{"countryP75Salary":56845,"dollarGap":-28155,"percentGap":-33.12},"workingHours":{"annualHours":2080,"percentVsNationalAverage":15.6,"percentVsOecdAverage":20.5},"globalIncomeContext":{"globalPercentile":98.4,"withinCountryPercentile":88.5},"raiseImpact":[{"raisePercent":10,"newSalary":93500,"lifetimeEarningsIncrease":552500},{"raisePercent":15,"newSalary":97750,"lifetimeEarningsIncrease":828750},{"raisePercent":20,"newSalary":102000,"lifetimeEarningsIncrease":1105000}],"negotiationSummary":"You currently earn US$85,000 (PPP-adjusted), placing you at the 88th percentile of earners in USA. The US market benchmark for a Software Developer with 6 years of experience is US$117,000 (US 75th percentile: US$157,500). Closing the gap to your country's 75th percentile of earners would mean no gap — you're already above it. You work 15.6% more hours per week than the national average. A 10% raise to US$93,500 would add an estimated US$552,500 to your projected US-equivalent lifetime earnings; a 20% raise would add US$1,105,000.","caveat":"Lifetime earnings figures scale the model’s baseline age/education earnings curve by the raise percentage — an approximation of applying that raise consistently going forward, not a re-run of the underlying projection against your actual salary. All benchmarks are illustrative market data, not a guarantee of what any specific employer will offer."},"components":["national-salary-percentile","working-hours-comparison","salary-by-degree","lifetime-earnings","income-percentile"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/true-cost-of-living":{"post":{"summary":"Compare true cost-of-living-adjusted affordability across target countries","tags":["Composite"],"description":"Compares purchasing power, local salary percentile, and lifestyle affordability across up to 5 candidate countries for someone considering relocating. Use this when a user is choosing between several possible relocation destinations, not just comparing two. Returns a ranked comparison across all target countries.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"originCountry":{"type":"string","description":"ISO 3166-1 alpha-3 origin country code. Example: \"USA\""},"currentSalary":{"type":"number","description":"Current annual salary in the origin country's local currency. Example: 90000"},"targetCountries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-3 codes for 1-5 candidate destination countries. Example: [\"PRT\", \"ESP\", \"MEX\"]"},"lifestyleLevel":{"type":"string","enum":["frugal","moderate","comfortable"],"description":"Desired lifestyle level. Example: \"moderate\""},"weeklyHours":{"type":"number","description":"Typical hours worked per week, for working-hours context. Example: 40"}},"required":["originCountry","currentSalary","targetCountries","lifestyleLevel","weeklyHours"]}}}},"responses":{"200":{"description":"A ranked cost-of-living-adjusted affordability comparison across the target countries.","content":{"application/json":{"schema":{"type":"object","description":"A ranked cost-of-living-adjusted affordability comparison across the target countries.","properties":{"result":{"type":"object","description":"The comparison result.","properties":{"originCountry":{"type":"string","description":"The origin country, as given in the request."},"originWorkingHoursVsNationalAveragePercent":{"type":["null","number"],"description":"How the given weekly hours compare to the origin country's national average, as a percentage. Null if origin working-hours data was unavailable."},"countries":{"type":"array","description":"One entry per target country, ranked best (highest trueAffordabilityScore) first.","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-3 target country code."},"pppEquivalentSalary":{"type":["null","number"],"description":"Salary in destination local currency needed to match the same purchasing power. Null if unavailable for this country."},"destinationCurrency":{"type":["null","string"],"description":"ISO 4217 currency code of the destination country."},"fxConvertedSalary":{"type":["null","number"],"description":"Salary in destination local currency at the live market exchange rate."},"purchasingPowerGainLossPercent":{"type":["null","number"],"description":"Positive means the FX-converted amount buys more than the PPP-equivalent needs."},"localSalaryPercentile":{"type":["null","number"],"description":"Where the equivalent salary ranks within the destination country's own income distribution, 0-100."},"electricityCostUSD":{"type":["null","number"],"description":"Estimated monthly electricity cost in USD at a reference 300 kWh usage."},"electricityVsCountryAveragePercent":{"type":["null","number"],"description":"Electricity cost vs that country's average, as an absolute USD difference."},"workingHoursVsNationalAveragePercent":{"type":["null","number"],"description":"The given weekly hours vs this country's national average, as a percentage."},"inflationPurchasingPowerLostPercent":{"type":["null","number"],"description":"Percent purchasing power lost to inflation over the trailing ~10-year window, in this country."},"trueAffordabilityScore":{"type":["null","number"],"description":"Composite 0-100 score combining all available dimensions above, normalized only against the other requested target countries — not a universal absolute scale. Null if no dimension had data."},"missingComponents":{"type":"array","items":{"type":"string"},"description":"Which sub-components returned no data for this country (and were skipped rather than blocking the whole response). Empty when every dimension had data."}}}},"excludedFromScore":{"type":"array","items":{"type":"string"},"description":"Components this composite deliberately never computes (e.g. no per-country median property price dataset exists for a housing-burden figure), listed so callers know what's structurally out of scope rather than silently missing."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually returned data for at least one country in this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"high\" when every target country had every component; \"low\" if any country was missing at least one component."}}}}},"examples":{"UkToSpainAndMexico":{"summary":"A UK salary of £65,000 compared against Spain and Mexico","value":{"result":{"originCountry":"GBR","originWorkingHoursVsNationalAveragePercent":35.9,"countries":[{"country":"MEX","pppEquivalentSalary":882143,"destinationCurrency":"MXN","fxConvertedSalary":1503749.13,"purchasingPowerGainLossPercent":70.47,"localSalaryPercentile":99.5,"electricityCostUSD":24,"electricityVsCountryAveragePercent":8,"workingHoursVsNationalAveragePercent":-2.3,"inflationPurchasingPowerLostPercent":37.43,"trueAffordabilityScore":80,"missingComponents":[]},{"country":"ESP","pppEquivalentSalary":58500,"destinationCurrency":"EUR","fxConvertedSalary":75858.9,"purchasingPowerGainLossPercent":29.67,"localSalaryPercentile":97.2,"electricityCostUSD":84,"electricityVsCountryAveragePercent":8.4,"workingHoursVsNationalAveragePercent":26.8,"inflationPurchasingPowerLostPercent":17.16,"trueAffordabilityScore":20,"missingComponents":[]}],"excludedFromScore":["house-price-to-income (housing burden) — no per-country median property price reference dataset exists"]},"components":["working-hours-comparison","ppp-salary-converter","cross-country-equivalent-salary","electricity-cost-by-country","real-income-erosion"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/global-relocation-fit":{"post":{"summary":"Rank countries for relocation fit against weighted priorities","tags":["Composite"],"description":"Ranks candidate countries by a weighted fit score combining affordability, safety, healthcare, climate, and community age fit. Use this when a user is deciding where to relocate and wants country suggestions matched to what they personally care about. Returns a ranked list of countries with each component score and an overall weighted fit score.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currentCountry":{"type":"string","description":"ISO 3166-1 alpha-3 country code, excluded from the results. Example: \"USA\""},"currentSalary":{"type":"number","description":"Current annual salary in the origin country's local currency. Example: 90000"},"age":{"type":"number","description":"Current age. Example: 32"},"sex":{"type":"string","enum":["M","F"],"description":"Biological sex, used for the healthcare/survival-probability component. Example: \"F\""},"priorities":{"type":"object","description":"Relative importance weights, 0-100 each, for each fit component. Example: {\"affordability\": 40, \"safety\": 30, \"healthcare\": 10, \"climate\": 10, \"communityAge\": 10}","properties":{"affordability":{"type":"number","description":"Relative weight for affordability, 0-100. Example: 40"},"safety":{"type":"number","description":"Relative weight for safety, 0-100. Example: 30"},"healthcare":{"type":"number","description":"Relative weight for healthcare, 0-100. Example: 10"},"climate":{"type":"number","description":"Relative weight for climate, 0-100. Example: 10"},"communityAge":{"type":"number","description":"Relative weight for community age fit, 0-100. Example: 10"}},"required":["affordability","safety","healthcare","climate","communityAge"]}},"required":["currentCountry","currentSalary","age","sex","priorities"]}}}},"deprecated":true,"responses":{"200":{"description":"A ranked list of candidate countries by weighted relocation fit, with each component score.","content":{"application/json":{"schema":{"type":"object","description":"A ranked list of candidate countries by weighted relocation fit, with each component score.","properties":{"result":{"type":"object","description":"The relocation fit comparison.","properties":{"currentCountry":{"type":"string","description":"The origin country, as given in the request."},"candidates":{"type":"array","description":"Ranked candidate countries from a fixed 52-country pool (minus the origin), best fit first, capped at 20.","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-3 candidate country code."},"affordabilityScore":{"type":["null","number"],"description":"Normalized purchasing-power gain/loss vs the origin salary, 0-100, higher = more affordable. Null if unavailable for this country."},"safetyScore":{"type":["null","number"],"description":"country-safety-composite compositeSafetyScore, 0-100, higher = safer. Null if unavailable."},"healthcareScore":{"type":["null","number"],"description":"Survival probability to age 80, 0-100, higher = better. Null if unavailable."},"climateScore":{"type":["null","number"],"description":"Normalized inverse grid carbon intensity, 0-100, higher = cleaner grid. Null if unavailable."},"communityAgeFitScore":{"type":["null","number"],"description":"Normalized inverse absolute median-age gap, 0-100, higher = closer to your age. Null if unavailable."},"medianAgeGap":{"type":["null","number"],"description":"Raw signed gap between your age and this country's median age, for display. Null if unavailable."},"weightedFitScore":{"type":["null","number"],"description":"This server's initial weighted ranking score using the request's priorities. The client is expected to recompute this on re-weight from the per-dimension scores, without another server call. Null if every dimension was unavailable."},"missingComponents":{"type":"array","items":{"type":"string"},"description":"Which sub-components returned no data for this country. Empty when every dimension had data."}}}},"totalCandidatePoolSize":{"type":"number","description":"Size of the fixed candidate pool actually considered (52 countries with complete reference-data coverage, minus the origin country)."},"excludedFromScore":{"type":"array","items":{"type":"string"},"description":"Components this composite deliberately never computes (e.g. no per-country median property price dataset exists for a housing-burden figure), listed so callers know what's structurally out of scope rather than silently missing."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually returned data for at least one candidate country in this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"low\" if any returned candidate was missing at least one component; \"high\" otherwise."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}},"deprecation":{"type":"object","description":"Present only on deprecated endpoints. States when the endpoint stops serving and why. See the Deprecation and Sunset response headers (RFC 8594).","properties":{"sunset":{"type":"string","description":"ISO date after which this endpoint stops serving. Example: \"2027-02-28\""},"reason":{"type":"string","description":"Why the endpoint is being withdrawn."},"replacement":{"type":["null","string"],"description":"Path of a replacement endpoint, or null where there is none."}}}}},"examples":{"UsProfessionalWeightedAffordability":{"summary":"A 32-year-old US earner ($90,000) weighting affordability and safety highest","value":{"result":{"currentCountry":"USA","candidates":[{"country":"ARG","affordabilityScore":100,"safetyScore":58.4,"healthcareScore":51.5,"climateScore":51.5,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":77.8,"missingComponents":[]},{"country":"ETH","affordabilityScore":92.9,"safetyScore":42.3,"healthcareScore":30.5,"climateScore":98.5,"communityAgeFitScore":0,"medianAgeGap":17.6,"weightedFitScore":62.8,"missingComponents":[]},{"country":"EGY","affordabilityScore":77.1,"safetyScore":46.8,"healthcareScore":35.8,"climateScore":32.4,"communityAgeFitScore":47.6,"medianAgeGap":9.8,"weightedFitScore":56.5,"missingComponents":[]},{"country":"TUR","affordabilityScore":52.2,"safetyScore":46,"healthcareScore":52.8,"climateScore":47.1,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":54.7,"missingComponents":[]},{"country":"SGP","affordabilityScore":7.3,"safetyScore":95,"healthcareScore":70.6,"climateScore":44.1,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":52.9,"missingComponents":[]},{"country":"NZL","affordabilityScore":4.2,"safetyScore":92.8,"healthcareScore":66.2,"climateScore":89.7,"communityAgeFitScore":61,"medianAgeGap":-7.6,"weightedFitScore":51.2,"missingComponents":[]},{"country":"CHL","affordabilityScore":13.5,"safetyScore":76.9,"healthcareScore":60.6,"climateScore":51.5,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":49.7,"missingComponents":[]},{"country":"CAN","affordabilityScore":4.1,"safetyScore":87.9,"healthcareScore":65.8,"climateScore":85.3,"communityAgeFitScore":61,"medianAgeGap":-7.6,"weightedFitScore":49.2,"missingComponents":[]},{"country":"FRA","affordabilityScore":4.5,"safetyScore":79.5,"healthcareScore":67.6,"climateScore":95.6,"communityAgeFitScore":61,"medianAgeGap":-7.6,"weightedFitScore":48.1,"missingComponents":[]},{"country":"ARE","affordabilityScore":10.4,"safetyScore":77,"healthcareScore":57.3,"climateScore":44.1,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":47.4,"missingComponents":[]},{"country":"GBR","affordabilityScore":3.2,"safetyScore":85.6,"healthcareScore":61.8,"climateScore":76.5,"communityAgeFitScore":61,"medianAgeGap":-7.6,"weightedFitScore":46.9,"missingComponents":[]},{"country":"IRL","affordabilityScore":2.9,"safetyScore":88.8,"healthcareScore":65,"climateScore":58.8,"communityAgeFitScore":61,"medianAgeGap":-7.6,"weightedFitScore":46.3,"missingComponents":[]},{"country":"NOR","affordabilityScore":1.8,"safetyScore":93.9,"healthcareScore":66.8,"climateScore":100,"communityAgeFitScore":4.3,"medianAgeGap":-16.9,"weightedFitScore":46,"missingComponents":[]},{"country":"SWE","affordabilityScore":3.2,"safetyScore":90.6,"healthcareScore":66.8,"climateScore":99.3,"communityAgeFitScore":4.3,"medianAgeGap":-16.9,"weightedFitScore":45.5,"missingComponents":[]},{"country":"CHE","affordabilityScore":0,"safetyScore":94.2,"healthcareScore":68.3,"climateScore":98.5,"communityAgeFitScore":4.3,"medianAgeGap":-16.9,"weightedFitScore":45.4,"missingComponents":[]},{"country":"FIN","affordabilityScore":2.6,"safetyScore":92.8,"healthcareScore":66.4,"climateScore":89.7,"communityAgeFitScore":4.3,"medianAgeGap":-16.9,"weightedFitScore":44.9,"missingComponents":[]},{"country":"MYS","affordabilityScore":17,"safetyScore":68.6,"healthcareScore":45.4,"climateScore":29.4,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":44.9,"missingComponents":[]},{"country":"THA","affordabilityScore":21.1,"safetyScore":55.2,"healthcareScore":55,"climateScore":36.8,"communityAgeFitScore":100,"medianAgeGap":-1.2,"weightedFitScore":44.2,"missingComponents":[]},{"country":"DNK","affordabilityScore":1.2,"safetyScore":93.8,"healthcareScore":63.9,"climateScore":86.8,"communityAgeFitScore":4.3,"medianAgeGap":-16.9,"weightedFitScore":44.1,"missingComponents":[]},{"country":"AUT","affordabilityScore":3.4,"safetyScore":88.5,"healthcareScore":64.8,"climateScore":88.2,"communityAgeFitScore":4.3,"medianAgeGap":-16.9,"weightedFitScore":43.6,"missingComponents":[]}],"totalCandidatePoolSize":51,"excludedFromScore":["house-price-to-income (housing burden) — no per-country median property price reference dataset exists"]},"components":["cross-country-equivalent-salary","country-safety-composite","survival-probability","national-age-percentile","carbon-intensity-reference"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/financial-life-position":{"get":{"summary":"Get a composite financial life position score","tags":["Composite"],"description":"Combines income percentile, wealth percentile, and retirement readiness into a single 0-100 financial position score. Use this when a user wants one overall read on their financial standing, rather than checking several calculators separately. Returns the composite score, each component's percentile, and retirement readiness under current savings.","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Current age. Example: 35"},{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"annualIncome","required":true,"description":"Annual household income. Example: 95000"},{"schema":{"type":"string"},"in":"query","name":"netWorth","required":true,"description":"Total assets minus debts. Example: 180000"},{"schema":{"type":"string"},"in":"query","name":"currentRetirementSavings","required":true,"description":"Current retirement savings balance. Example: 120000"},{"schema":{"type":"string"},"in":"query","name":"monthlyContribution","required":true,"description":"Monthly retirement contribution. Example: 1200"},{"schema":{"type":"string"},"in":"query","name":"retirementAge","required":true,"description":"Planned retirement age. Example: 65"},{"schema":{"type":"string"},"in":"query","name":"expectedAnnualReturn","required":true,"description":"Expected annual investment return as a percentage. Example: 7"},{"schema":{"type":"string"},"in":"query","name":"desiredMonthlyRetirementIncome","required":true,"description":"Desired monthly income during retirement. Example: 5000"},{"schema":{"type":"string"},"in":"query","name":"householdSize","required":false,"description":"Optional number of people the income supports, defaults to 1. Example: 2"}],"responses":{"200":{"description":"A composite 0-100 financial position score combining income percentile, wealth percentile, and retirement readiness.","content":{"application/json":{"schema":{"type":"object","description":"A composite 0-100 financial position score combining income percentile, wealth percentile, and retirement readiness.","properties":{"result":{"type":"object","description":"The financial position result.","properties":{"financialPositionScore":{"type":["null","number"],"description":"0-100 average of whichever of incomePercentile.withinCountry, wealthPercentile.withinCountry, and a retirement-readiness score were available. Null if none were."},"incomePercentile":{"type":["null","object"],"description":"Where annualIncome ranks. Null if income-percentile data was unavailable for this country.","properties":{"withinCountry":{"type":"number","description":"Percentile within the given country, 0-100."},"global":{"type":"number","description":"Percentile among the world population covered by the dataset, 0-100."}}},"wealthPercentile":{"type":["null","object"],"description":"Where netWorth ranks. Null if wealth-percentile data was unavailable for this country.","properties":{"withinCountry":{"type":"number","description":"Percentile within the given country, 0-100."},"global":{"type":"number","description":"Percentile among the world adult population covered by the dataset, 0-100."},"tier":{"type":"string","enum":["bottom50","middle40","top10","top1"],"description":"Global wealth tier."}}},"wealthGapRatio":{"type":["null","number"],"description":"wealthPercentile.withinCountry minus incomePercentile.withinCountry. Null unless both were available."},"nationalSalaryPercentile":{"type":["null","object"],"description":"Where annualIncome ranks against national wage-survey data specifically (a separate dataset from incomePercentile). Null if unavailable for this country.","properties":{"percentile":{"type":"number","description":"Percentile within national earnings data, 0-100."},"multipleOfMeanWage":{"type":"number","description":"annualIncome divided by the country's mean annual wage."}}},"retirementReadiness":{"type":"object","description":"Projected retirement outcome under current savings behaviour.","properties":{"projectedPotAtRetirement":{"type":"number","description":"Projected savings balance at retirementAge."},"monthlyIncomeFromPot":{"type":"number","description":"Sustainable monthly income from the pot at a 4% withdrawal rate."},"desiredMonthlyIncome":{"type":"number","description":"Echo of desiredMonthlyRetirementIncome from the request."},"yearsSavingsWillLast":{"type":["null","number"],"description":"How many years the pot lasts under withdrawal at desiredMonthlyIncome. Null if it lasts effectively indefinitely (100+ years)."},"countryLifeExpectancy":{"type":["null","number"],"description":"The country's average life expectancy (both sexes). Null if unavailable for this country."},"longevityAdjustedRetirementYearsNeeded":{"type":["null","number"],"description":"countryLifeExpectancy minus retirementAge, floored at 0. Null if life expectancy was unavailable."},"longevityAdjustedSurplusYears":{"type":["null","number"],"description":"yearsSavingsWillLast minus longevityAdjustedRetirementYearsNeeded. Null if either input is null (including when the pot lasts indefinitely)."},"verdict":{"type":"string","enum":["surplus","shortfall","balanced"],"description":"\"balanced\" if within 1 year of the longevity-adjusted need; \"surplus\" also covers the case where surplus years is null (pot lasts indefinitely, or need is unknown)."}}},"tenPercentMoreSavings":{"type":"object","description":"The same retirement projection with monthlyContribution increased by 10%, for comparison.","properties":{"newMonthlyContribution":{"type":"number","description":"monthlyContribution increased by 10%."},"projectedPotAtRetirement":{"type":"number","description":"Projected pot at retirementAge under the increased contribution."},"yearsSavingsWillLast":{"type":["null","number"],"description":"Same semantics as retirementReadiness.yearsSavingsWillLast, under the increased contribution."},"additionalYearsOfRunway":{"type":["null","number"],"description":"tenPercentMoreSavings.yearsSavingsWillLast minus retirementReadiness.yearsSavingsWillLast. Null if either is null."}}},"aheadOfMedianPeer":{"type":["null","boolean"],"description":"Whether the average of income and wealth within-country percentiles is at least 50. Null unless both incomePercentile and wealthPercentile were available."},"caveat":{"type":"string","description":"Explains that the peer comparison is against the general adult population, not an age-matched cohort."},"missingComponents":{"type":"array","items":{"type":"string"},"description":"Which sub-components returned no data for this country (and were skipped rather than blocking the whole response). Empty when every dimension had data."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually returned data for this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"low\" if any sub-component was missing, \"high\" otherwise."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}}}},"examples":{"UsAge35Professional":{"summary":"A 35-year-old US household earning $95,000/yr with $180,000 net worth","value":{"result":{"financialPositionScore":83.7,"incomePercentile":{"withinCountry":91.1,"global":98.8},"wealthPercentile":{"withinCountry":60.1,"global":91.8,"tier":"top10"},"wealthGapRatio":-31,"nationalSalaryPercentile":{"percentile":91.7,"multipleOfMeanWage":2.09},"retirementReadiness":{"projectedPotAtRetirement":2437944.89,"monthlyIncomeFromPot":8126.48,"desiredMonthlyIncome":5000,"yearsSavingsWillLast":null,"countryLifeExpectancy":76.4,"longevityAdjustedRetirementYearsNeeded":11.4,"longevityAdjustedSurplusYears":null,"verdict":"surplus"},"tenPercentMoreSavings":{"newMonthlyContribution":1320,"projectedPotAtRetirement":2584341.41,"yearsSavingsWillLast":null,"additionalYearsOfRunway":null},"aheadOfMedianPeer":true,"caveat":"\"Ahead/behind peer\" compares against the general within-country adult population, not an age-matched cohort — no age-segmented income or wealth reference dataset exists in this platform to compute a true same-age comparison.","missingComponents":[]},"components":["income-percentile","wealth-percentile","national-salary-percentile","retirement-savings"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/health-adjusted-retirement-horizon":{"get":{"summary":"Project a health-adjusted personalized retirement horizon","tags":["Composite"],"description":"Combines a biological age estimate with a personalized life-table lookup to project how long retirement savings need to last, instead of using a flat national life expectancy. Use this when a user wants a retirement projection that accounts for their actual health and lifestyle. Returns biological age, personalized retirement horizon, and whether current savings are projected to last.","parameters":[{"schema":{"type":"string"},"in":"query","name":"age","required":true,"description":"Chronological age. Example: 45"},{"schema":{"type":"string","enum":["M","F"]},"in":"query","name":"sex","required":true,"description":"Biological sex. Example: \"M\""},{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code, for the life table lookup. Example: \"USA\""},{"schema":{"type":"string"},"in":"query","name":"totalCholesterol","required":true,"description":"Total cholesterol in mg/dL. Example: 190"},{"schema":{"type":"string"},"in":"query","name":"hdlCholesterol","required":true,"description":"HDL (\"good\") cholesterol in mg/dL. Example: 55"},{"schema":{"type":"string"},"in":"query","name":"systolicBP","required":true,"description":"Systolic blood pressure in mmHg. Example: 120"},{"schema":{"type":"string"},"in":"query","name":"onBPMedication","required":true,"description":"Whether currently on blood pressure medication. Example: false"},{"schema":{"type":"string"},"in":"query","name":"smoker","required":true,"description":"Whether a current smoker. Example: false"},{"schema":{"type":"string"},"in":"query","name":"diabetes","required":true,"description":"Whether diagnosed with diabetes. Example: false"},{"schema":{"type":"string"},"in":"query","name":"exerciseMinPerWeek","required":true,"description":"Minutes of exercise per week. Example: 150"},{"schema":{"type":"string"},"in":"query","name":"sleepHours","required":true,"description":"Average hours of sleep per night. Example: 7"},{"schema":{"type":"string"},"in":"query","name":"bmi","required":true,"description":"Body mass index. Example: 24"},{"schema":{"type":"string","enum":["poor","fair","good","excellent"]},"in":"query","name":"diet","required":true,"description":"Overall diet quality. Example: \"good\""},{"schema":{"type":"string","enum":["low","medium","high"]},"in":"query","name":"stress","required":true,"description":"Typical stress level. Example: \"low\""},{"schema":{"type":"string"},"in":"query","name":"alcoholUnitsPerWeek","required":true,"description":"Alcohol units consumed per week. Example: 6"},{"schema":{"type":"string"},"in":"query","name":"currentSavings","required":true,"description":"Current retirement savings balance. Example: 250000"},{"schema":{"type":"string"},"in":"query","name":"monthlyContribution","required":true,"description":"Monthly retirement contribution. Example: 1500"},{"schema":{"type":"string"},"in":"query","name":"retirementAge","required":true,"description":"Planned retirement age. Example: 65"},{"schema":{"type":"string"},"in":"query","name":"expectedAnnualReturn","required":true,"description":"Expected annual investment return as a percentage. Example: 6"},{"schema":{"type":"string"},"in":"query","name":"desiredMonthlyIncome","required":true,"description":"Desired monthly income during retirement. Example: 4500"}],"responses":{"200":{"description":"A health-adjusted, personalized retirement horizon projection.","content":{"application/json":{"schema":{"type":"object","description":"A health-adjusted, personalized retirement horizon projection.","properties":{"result":{"type":"object","description":"The projection result.","properties":{"chronologicalAge":{"type":"number","description":"The age given in the request."},"biologicalAge":{"type":"object","description":"Estimated biological age from lifestyle factors.","properties":{"estimated":{"type":"number","description":"Estimated biological age."},"deltaYears":{"type":"number","description":"estimated minus chronologicalAge; negative means biologically younger than chronological age."},"topFactorsToImprove":{"type":"array","items":{"type":"string"},"description":"Up to 3 lifestyle factors with the largest aging impact, worst first."}}},"cardiacRisk":{"type":["null","object"],"description":"Framingham 10-year cardiovascular disease risk, informational only. Null if age is outside the model's validated 30-79 range.","properties":{"tenYearRiskPercent":{"type":"number","description":"10-year cardiovascular disease risk, as a percentage."},"riskCategory":{"type":"string","description":"\"low\", \"moderate\", or \"high\"."},"vsAverage":{"type":"number","description":"Percentage points vs an average-profile peer of the same age/sex."}}},"survivalProbability":{"type":["null","object"],"description":"Survival probability from the country life table, using biological age as the effective age. Null if the life-table lookup was unavailable.","properties":{"to80Percent":{"type":["null","number"],"description":"Probability of reaching age 80, as a percentage. Null if already past that target age."},"to90Percent":{"type":["null","number"],"description":"Probability of reaching age 90, as a percentage. Null if already past that target age."},"expectedRemainingYears":{"type":["null","number"],"description":"Expected remaining years of life from the life table."}}},"personalizedRetirementHorizon":{"type":"object","description":"How long retirement is projected to last, personalized by biological age.","properties":{"personalizedLifeExpectancy":{"type":["null","number"],"description":"Chronological age plus expected remaining years from the life table. Null if survivalProbability was unavailable."},"retirementHorizonYears":{"type":["null","number"],"description":"personalizedLifeExpectancy minus retirementAge, floored at 0. Null if unavailable."},"yearsSavingsWillLast":{"type":["null","number"],"description":"How many years the projected retirement pot lasts at the desired monthly income. Null if it's projected to last over 100 years or desiredMonthlyIncome is 0."},"verdict":{"type":"string","enum":["surplus","shortfall","balanced"],"description":"Whether savings are projected to outlast, fall short of, or roughly match the personalized retirement horizon."}}},"retirementProjection":{"type":"object","description":"Projected retirement savings outcome.","properties":{"projectedPotAtRetirement":{"type":"number","description":"Projected savings balance at retirement age."},"monthlyIncomeFromPot":{"type":"number","description":"Estimated monthly income the pot can sustain, at a 4% withdrawal rate."},"desiredMonthlyIncome":{"type":"number","description":"The desired monthly income given in the request."}}},"whatIfHalvedAlcohol":{"type":["null","object"],"description":"A recomputed scenario halving weekly alcohol units, showing its effect on biological age and retirement horizon. Null if the scenario could not be computed.","properties":{"newAlcoholUnitsPerWeek":{"type":"number","description":"Half the original alcoholUnitsPerWeek."},"newBiologicalAge":{"type":"number","description":"Recomputed estimated biological age at the halved alcohol intake."},"newRetirementHorizonYears":{"type":["null","number"],"description":"Recomputed retirementHorizonYears at the halved alcohol intake. Null if unavailable."},"additionalRetirementYears":{"type":["null","number"],"description":"newRetirementHorizonYears minus the original retirementHorizonYears. Null if either horizon is unavailable."}}},"caveat":{"type":"string","description":"Explains why cardiac risk is shown for context but does not drive the retirement-horizon number."},"missingComponents":{"type":"array","items":{"type":"string"},"description":"Which sub-components returned no data and were skipped rather than blocking the whole response. Empty when every dimension had data."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually returned data for this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"high\" when every component had data; \"low\" if any component was missing."}}}}},"examples":{"Age45MaleUsaModerateHealth":{"summary":"A 45-year-old male in the USA with moderate cardiac markers, planning to retire at 65","value":{"result":{"chronologicalAge":45,"biologicalAge":{"estimated":40.48,"deltaYears":-4.52,"topFactorsToImprove":["Alcohol","Smoking","Exercise"]},"cardiacRisk":{"tenYearRiskPercent":4.6,"riskCategory":"low","vsAverage":-0.7},"survivalProbability":{"to80Percent":41.8,"to90Percent":12.5,"expectedRemainingYears":35.9},"personalizedRetirementHorizon":{"personalizedLifeExpectancy":80.9,"retirementHorizonYears":15.9,"yearsSavingsWillLast":null,"verdict":"surplus"},"retirementProjection":{"projectedPotAtRetirement":1520612.46,"monthlyIncomeFromPot":5068.71,"desiredMonthlyIncome":4500},"whatIfHalvedAlcohol":{"newAlcoholUnitsPerWeek":3,"newBiologicalAge":40.24,"newRetirementHorizonYears":15.9,"additionalRetirementYears":0},"caveat":"Cardiac risk is shown for context but does not drive the retirement-horizon number below — no clinically validated model in this platform converts a change in Framingham 10-year risk into a change in life-expectancy years, so that conversion is not fabricated here. The horizon is adjusted using biological age instead, which alcohol-impact and biological-age together do support (see whatIfHalvedAlcohol).","missingComponents":[]},"components":["biological-age","heart-disease-risk","survival-probability","retirement-savings","alcohol-impact"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/investment-quality-dashboard":{"get":{"summary":"Get a combined dividend-stock, bond, and savings-growth dashboard","tags":["Composite"],"description":"Combines a Gordon Growth Model stock valuation, a bond pricing calculation, and a compound-savings projection into one dashboard. Use this when a user wants a single view across a dividend stock, a bond, and a savings plan they are comparing as investment options. Returns intrinsic stock value, bond price, and projected savings growth.","parameters":[{"schema":{"type":"string"},"in":"query","name":"nextYearDividend","required":true,"description":"Expected dividend per share next year. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"dividendGrowthRate","required":true,"description":"Expected long-run dividend growth rate as a percentage. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"requiredReturn","required":true,"description":"Required rate of return as a percentage. Example: 9"},{"schema":{"type":"string"},"in":"query","name":"currentSharePrice","required":true,"description":"Current market share price, for comparison against intrinsic value. Example: 45"},{"schema":{"type":"string"},"in":"query","name":"bondFaceValue","required":true,"description":"Face (par) value of the bond. Example: 1000"},{"schema":{"type":"string"},"in":"query","name":"bondCouponRate","required":true,"description":"Annual bond coupon rate as a percentage. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"bondYearsToMaturity","required":true,"description":"Years until the bond matures. Example: 10"},{"schema":{"type":"string"},"in":"query","name":"bondMarketYield","required":true,"description":"Market yield (discount rate) as a percentage. Example: 6"},{"schema":{"type":"string"},"in":"query","name":"investmentHorizonYears","required":true,"description":"Years to project savings growth over. Example: 15"},{"schema":{"type":"string"},"in":"query","name":"inflationRate","required":true,"description":"Annual inflation rate as a percentage, for real-return context. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"initialCapital","required":true,"description":"Starting savings amount. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"savingsRatePercent","required":true,"description":"Percentage of income saved, for context. Example: 20"}],"responses":{"200":{"description":"A combined dividend-stock, bond, and savings-growth dashboard.","content":{"application/json":{"schema":{"type":"object","description":"A combined dividend-stock, bond, and savings-growth dashboard.","properties":{"result":{"type":"object","description":"The dashboard result.","properties":{"share":{"type":"object","description":"Gordon Growth Model stock valuation vs the given market price.","properties":{"intrinsicValue":{"type":"number","description":"Intrinsic value per share from the Gordon Growth Model."},"currentPrice":{"type":"number","description":"The current market share price, as given in the request."},"marginOfSafetyPercent":{"type":"number","description":"How far intrinsicValue is above (or below) currentPrice, as a percentage of intrinsicValue."},"verdict":{"type":"string","enum":["undervalued","overvalued","fairlyValued"],"description":"Valuation verdict, based on a +/-5% margin-of-safety band."}}},"bond":{"type":"object","description":"Bond pricing at the given market yield.","properties":{"price":{"type":"number","description":"Bond price."},"duration":{"type":"number","description":"Macaulay duration, in years."},"yieldToMaturity":{"type":"number","description":"Yield to maturity, solved numerically as a correctness check on the price, as a percentage."}}},"npvVsCash":{"type":"object","description":"NPV of the stock and bond legs (each sized to initialCapital) discounted at requiredReturn.","properties":{"stock":{"type":"object","description":"NPV summary for the stock leg's projected dividend + exit-price cash flows.","properties":{"npv":{"type":"number","description":"Net present value."},"irr":{"type":["null","number"],"description":"Internal rate of return, as a percentage. Null if no real root exists in the search range."},"paybackPeriod":{"type":["null","number"],"description":"Periods (fractional) to recoup the initial investment. Null if never recouped."}}},"bond":{"type":"object","description":"NPV summary for the bond leg's projected coupon + face-value/resale cash flows.","properties":{"npv":{"type":"number","description":"Net present value."},"irr":{"type":["null","number"],"description":"Internal rate of return, as a percentage. Null if no real root exists in the search range."},"paybackPeriod":{"type":["null","number"],"description":"Periods (fractional) to recoup the initial investment. Null if never recouped."}}},"discountRateUsed":{"type":"number","description":"The discount rate used, equal to requiredReturn."}}},"realReturn":{"type":"object","description":"Inflation-adjusted return comparison across stock, bond, and cash/savings options.","properties":{"stock":{"type":"object","description":"Real-return summary using requiredReturn as the nominal rate.","properties":{"nominalReturnPercent":{"type":"number","description":"Nominal annual return used, as a percentage."},"realReturnPercent":{"type":"number","description":"Inflation-adjusted annual return, as a percentage."},"realValueOfInitialCapital":{"type":"number","description":"Real (inflation-adjusted) value of initialCapital after investmentHorizonYears."}}},"bond":{"type":"object","description":"Real-return summary using the bond's yieldToMaturity as the nominal rate.","properties":{"nominalReturnPercent":{"type":"number","description":"Nominal annual return used, as a percentage."},"realReturnPercent":{"type":"number","description":"Inflation-adjusted annual return, as a percentage."},"realValueOfInitialCapital":{"type":"number","description":"Real (inflation-adjusted) value of initialCapital after investmentHorizonYears."}}},"cash":{"type":"object","description":"Real-return summary using savingsRatePercent as the nominal rate.","properties":{"nominalReturnPercent":{"type":"number","description":"Nominal annual return used, as a percentage."},"realReturnPercent":{"type":"number","description":"Inflation-adjusted annual return, as a percentage."},"realValueOfInitialCapital":{"type":"number","description":"Real (inflation-adjusted) value of initialCapital after investmentHorizonYears."}}}}},"compoundGrowthComparison":{"type":"object","description":"Final nominal amount if initialCapital compounded annually at each option's rate over investmentHorizonYears.","properties":{"stock":{"type":"number","description":"Final amount at requiredReturn."},"bond":{"type":"number","description":"Final amount at the bond's yieldToMaturity."},"cash":{"type":"number","description":"Final amount at savingsRatePercent."}}},"rankedByRealReturn":{"type":"array","description":"stock/bond/cash ranked by realReturnPercent, best first.","items":{"type":"object","properties":{"option":{"type":"string","enum":["stock","bond","cash"],"description":"Which option this entry ranks."},"realReturnPercent":{"type":"number","description":"The option's inflation-adjusted return, as a percentage."}}}},"caveat":{"type":"string","description":"Explains that ranking is by real return only, not a risk-adjusted (e.g. Sharpe-style) ranking."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-functions were used to compute this response. Always all five for this endpoint — this composite has no external reference-data dependency, so there is no partial-failure mode."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"Always \"high\" for this endpoint — see the components note above."}}}}},"examples":{"DividendStockVsBondVsSavings":{"summary":"A $2 dividend stock, a 10-year 5% coupon bond, and a savings plan, compared over a 15-year horizon","value":{"result":{"share":{"intrinsicValue":33.33,"currentPrice":45,"marginOfSafetyPercent":-35.01,"verdict":"overvalued"},"bond":{"price":926.4,"duration":8.02,"yieldToMaturity":6},"npvVsCash":{"stock":{"npv":-2592.91,"irr":6,"paybackPeriod":14.2},"bond":{"npv":-1976.54,"irr":6,"paybackPeriod":9.45},"discountRateUsed":9},"realReturn":{"stock":{"nominalReturnPercent":9,"realReturnPercent":5.83,"realValueOfInitialCapital":23379.7},"bond":{"nominalReturnPercent":6,"realReturnPercent":2.91,"realValueOfInitialCapital":15382.6},"cash":{"nominalReturnPercent":20,"realReturnPercent":16.5,"realValueOfInitialCapital":98891.8}},"compoundGrowthComparison":{"stock":36424.82,"bond":23965.58,"cash":154070.22},"rankedByRealReturn":[{"option":"cash","realReturnPercent":16.5},{"option":"stock","realReturnPercent":5.83},{"option":"bond","realReturnPercent":2.91}],"caveat":"Ranked by real (inflation-adjusted) return only — no volatility or standard-deviation model exists in this platform for an arbitrary user-specified share or bond, so a true risk-adjusted (e.g. Sharpe-style) ranking is not fabricated here."},"components":["share-price","bond-price","npv","inflation-adjusted-return","compound-interest"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/composite/carbon-optimised-lifestyle":{"get":{"summary":"Estimate a carbon footprint with country grid intensity, personalized","tags":["Composite"],"description":"Estimates annual carbon footprint from flights, car use, diet, and home energy, using the country's real electricity grid carbon intensity. Use this when a user wants a personalized carbon footprint with country-specific context, not a generic global average. Returns total tCO2e/year, category breakdown, and grid intensity context.","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-3 country code. Example: \"GBR\""},{"schema":{"type":"string","enum":["vegan","vegetarian","omnivore","heavyMeat"]},"in":"query","name":"diet","required":true,"description":"Typical diet type. Example: \"omnivore\""},{"schema":{"type":"string","enum":["petrol","diesel","hybrid","electric","none"]},"in":"query","name":"carType","required":true,"description":"Type of car driven, or \"none\". Example: \"petrol\""},{"schema":{"type":"string"},"in":"query","name":"annualCarKm","required":true,"description":"Kilometres driven per year. Example: 10000"},{"schema":{"type":"string"},"in":"query","name":"flightsShortHaulPerYear","required":true,"description":"Number of short-haul flights per year. Example: 2"},{"schema":{"type":"string"},"in":"query","name":"flightsLongHaulPerYear","required":true,"description":"Number of long-haul flights per year. Example: 1"},{"schema":{"type":"string"},"in":"query","name":"homeEnergyKwhPerMonth","required":true,"description":"Home electricity consumption in kWh per month. Example: 300"}],"deprecated":true,"responses":{"200":{"description":"A personalized annual carbon footprint using the country's real electricity grid intensity, with reduction levers and lower-carbon-and-lower-cost country suggestions.","content":{"application/json":{"schema":{"type":"object","description":"A personalized annual carbon footprint using the country's real electricity grid intensity, with reduction levers and lower-carbon-and-lower-cost country suggestions.","properties":{"result":{"type":"object","description":"The footprint result.","properties":{"totalCarbonFootprint":{"type":"object","description":"The overall footprint and how it compares to the country average.","properties":{"totalTonnesCo2ePerYear":{"type":"number","description":"Total estimated tonnes CO2e per year across all categories."},"breakdown":{"type":"array","description":"Per-category contribution.","items":{"type":"object","properties":{"category":{"type":"string","description":"Category name, e.g. \"Flights\", \"Car\", \"Diet\", \"Home energy\"."},"tonnesCo2e":{"type":"number","description":"Tonnes CO2e per year attributed to this category."}}}},"countryAveragePerCapitaTonnes":{"type":"number","description":"The country's average per-capita CO2 emissions, tonnes/year."},"vsCountryAverage":{"type":"number","description":"totalTonnesCo2ePerYear minus countryAveragePerCapitaTonnes. Not a statistical percentile — see caveat."}}},"gridIntensity":{"type":"object","description":"How much of the footprint is tied to the country's electricity grid.","properties":{"gCo2PerKwh":{"type":"number","description":"The country's electricity grid carbon intensity, grams CO2 per kWh."},"gridRelatedTonnes":{"type":"number","description":"Tonnes CO2e per year from home energy, plus car if electric."},"gridRelatedSharePercent":{"type":"number","description":"gridRelatedTonnes as a percentage of totalTonnesCo2ePerYear."}}},"biggestLevers":{"type":"array","description":"One-variable-at-a-time reduction scenarios, ranked by CO2 saved, largest first.","items":{"type":"object","properties":{"lever":{"type":"string","description":"Which input was changed: \"diet\", \"car\", \"flights\", or \"homeEnergy\"."},"description":{"type":"string","description":"Human-readable description of the scenario."},"co2ReductionTonnes":{"type":"number","description":"Tonnes CO2e per year saved versus the baseline footprint. Can be 0 if the lever doesn't apply (e.g. already driving electric)."}}}},"betterCountries":{"type":"array","description":"Up to 5 candidate countries where the same personal habits would produce both lower carbon and lower electricity cost than the origin country, best first. Can be empty if no candidate beats the origin on both dimensions.","items":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-3 candidate country code."},"totalTonnesCo2ePerYear":{"type":"number","description":"Recomputed footprint for the same habits in this country."},"carbonReductionPercent":{"type":"number","description":"Percent lower than the origin country's footprint."},"monthlyElectricityCostUSD":{"type":"number","description":"Monthly electricity cost in USD for the same usage in this country."},"costReductionPercent":{"type":"number","description":"Percent lower than the origin country's monthly electricity cost. 0 if origin electricity cost was unavailable."}}}},"caveat":{"type":"string","description":"Explains why no statistical percentile vs national average is computed."},"missingComponents":{"type":"array","items":{"type":"string"},"description":"Which sub-components returned no data (e.g. origin electricity cost unavailable for the given country). Empty when everything was available."}}},"components":{"type":"array","items":{"type":"string"},"description":"Which underlying sub-services actually returned data for this response."},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed."},"calculationClass":{"type":"string","description":"How this result was derived. Always \"composite\" for this endpoint."},"confidence":{"type":"string","description":"\"low\" if any sub-component was missing, \"high\" otherwise."}}},"provenance":{"type":"array","description":"What the reference data behind this response actually is. `status` is \"sourced\" (the publisher's own figures), \"derived\" (computed by us from a real source) or \"illustrative\" (a curated estimate approximating the named publisher, not their published figures).","items":{"type":"object","properties":{"dataset":{"type":"string","description":"Dataset identifier. Example: \"ppp_factors\""},"status":{"type":"string","enum":["sourced","derived","illustrative"],"description":"How much the values can be relied on as the publisher's own."},"publisher":{"type":"string","description":"The named source. For derived and illustrative data this is the publisher being approximated, not the origin of the values served."},"method":{"type":"string","description":"How the values were produced. Present for derived and illustrative datasets."},"vintage":{"type":"string","description":"Period the data represents. Example: \"2023\""},"lastVerified":{"type":"string","description":"ISO date the entry was last checked by a human."}}}},"deprecation":{"type":"object","description":"Present only on deprecated endpoints. States when the endpoint stops serving and why. See the Deprecation and Sunset response headers (RFC 8594).","properties":{"sunset":{"type":"string","description":"ISO date after which this endpoint stops serving. Example: \"2027-02-28\""},"reason":{"type":"string","description":"Why the endpoint is being withdrawn."},"replacement":{"type":["null","string"],"description":"Path of a replacement endpoint, or null where there is none."}}}}},"examples":{"UkOmnivoreCommuter":{"summary":"A UK omnivore driving petrol, 300 kWh/month home energy","value":{"result":{"totalCarbonFootprint":{"totalTonnesCo2ePerYear":6.45,"breakdown":[{"category":"Flights","tonnesCo2e":1.6},{"category":"Car","tonnesCo2e":1.7},{"category":"Diet","tonnesCo2e":2.5},{"category":"Home energy","tonnesCo2e":0.65}],"countryAveragePerCapitaTonnes":5,"vsCountryAverage":1.45},"gridIntensity":{"gCo2PerKwh":180,"gridRelatedTonnes":0.65,"gridRelatedSharePercent":10.08},"biggestLevers":[{"lever":"car","description":"Switch to an electric vehicle","co2ReductionTonnes":1.38},{"lever":"diet","description":"Switch to a vegan diet","co2ReductionTonnes":1},{"lever":"flights","description":"Halve your short- and long-haul flights","co2ReductionTonnes":0.8},{"lever":"homeEnergy","description":"Halve your home energy use","co2ReductionTonnes":0.33}],"betterCountries":[{"country":"ETH","totalTonnesCo2ePerYear":5.91,"carbonReductionPercent":8.37,"monthlyElectricityCostUSD":3,"costReductionPercent":96.55},{"country":"NOR","totalTonnesCo2ePerYear":5.87,"carbonReductionPercent":8.99,"monthlyElectricityCostUSD":36,"costReductionPercent":58.62},{"country":"CAN","totalTonnesCo2ePerYear":6.23,"carbonReductionPercent":3.41,"monthlyElectricityCostUSD":39,"costReductionPercent":55.17},{"country":"BRA","totalTonnesCo2ePerYear":6.12,"carbonReductionPercent":5.12,"monthlyElectricityCostUSD":42,"costReductionPercent":51.72},{"country":"FIN","totalTonnesCo2ePerYear":6.12,"carbonReductionPercent":5.12,"monthlyElectricityCostUSD":54,"costReductionPercent":37.93}],"caveat":"No carbon-footprint percentile vs national average is computed — the reference data has a country AVERAGE only, not a distribution, so a statistical percentile would require a fabricated standard deviation. vsCountryAverage (your footprint minus the country average, a real figure) is reported instead.","missingComponents":[]},"components":["carbon-footprint","electricity-cost-by-country"],"meta":{"computedAt":"2026-08-08T12:00:00.000Z","calculationClass":"composite","confidence":"high"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/earned-value":{"get":{"summary":"Calculate earned value management (EVM) metrics","tags":["Project Management"],"description":"Calculates the full EVM dashboard from BAC, PV, EV and AC: schedule and cost variance, SPI, CPI, three EAC methods, ETC, VAC, and TCPI. Use this when a project manager wants a standard earned value performance snapshot. Returns SV, CV, SPI, CPI, EAC, ETC, VAC, and TCPI with RAG status indicators.","parameters":[{"schema":{"type":"string"},"in":"query","name":"bac","required":true,"description":"Budget at Completion — total approved project budget. Example: 500000"},{"schema":{"type":"string"},"in":"query","name":"pv","required":true,"description":"Planned Value — budgeted cost of work scheduled to be done by now. Example: 250000"},{"schema":{"type":"string"},"in":"query","name":"ev","required":true,"description":"Earned Value — budgeted cost of work actually completed so far. Example: 225000"},{"schema":{"type":"string"},"in":"query","name":"ac","required":true,"description":"Actual Cost — what's actually been spent so far. Example: 200000"}],"responses":{"200":{"description":"The full EVM dashboard: schedule/cost variance, SPI/CPI, three EAC estimates, ETC, VAC, and TCPI, with RAG status indicators.","content":{"application/json":{"schema":{"type":"object","description":"The full EVM dashboard: schedule/cost variance, SPI/CPI, three EAC estimates, ETC, VAC, and TCPI, with RAG status indicators.","properties":{"result":{"type":"object","description":"The earned value management calculation.","properties":{"sv":{"type":"number","description":"Schedule Variance = EV - PV. Example: -25000"},"cv":{"type":"number","description":"Cost Variance = EV - AC. Example: 25000"},"spi":{"type":"number","description":"Schedule Performance Index = EV / PV. Example: 0.9"},"cpi":{"type":"number","description":"Cost Performance Index = EV / AC. Example: 1.13"},"spiStatus":{"type":"string","description":"\"ahead\", \"onTrack\", or \"behind\", derived from SPI. Example: \"behind\""},"cpiStatus":{"type":"string","description":"\"underBudget\", \"onBudget\", or \"overBudget\", derived from CPI. Example: \"underBudget\""},"spiRag":{"type":"string","description":"\"green\", \"amber\", or \"red\" status for SPI. Example: \"amber\""},"cpiRag":{"type":"string","description":"\"green\", \"amber\", or \"red\" status for CPI. Example: \"green\""},"eacCpiBased":{"type":"number","description":"EAC = BAC / CPI — assumes current cost efficiency continues. Example: 444444.44"},"eacPlannedRateBased":{"type":"number","description":"EAC = AC + (BAC - EV) — assumes remaining work proceeds at the planned rate. Example: 475000"},"eacCurrentEfficiencyBased":{"type":"number","description":"EAC = AC + (BAC - EV) / CPI — assumes current efficiency continues for remaining work. Example: 444444.44"},"etc":{"type":"number","description":"Estimate to Complete = eacCpiBased - AC. Example: 244444.44"},"vac":{"type":"number","description":"Variance at Completion = BAC - eacCpiBased. Example: 55555.56"},"vacRag":{"type":"string","description":"\"green\", \"amber\", or \"red\" status for VAC. Example: \"green\""},"tcpi":{"type":"number","description":"To-Complete Performance Index = (BAC - EV) / (BAC - AC). Example: 0.92"},"tcpiRag":{"type":"string","description":"\"green\", \"amber\", or \"red\" status for TCPI. Example: \"green\""},"caveat":{"type":"string","description":"Explains that ETC/VAC use the CPI-based EAC as the default of the three methods."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"MidProjectSnapshot":{"summary":"EVM snapshot with BAC 500k, PV 250k, EV 225k, AC 200k","value":{"result":{"sv":-25000,"cv":25000,"spi":0.9,"cpi":1.13,"spiStatus":"behind","cpiStatus":"underBudget","spiRag":"amber","cpiRag":"green","eacCpiBased":444444.44,"eacPlannedRateBased":475000,"eacCurrentEfficiencyBased":444444.44,"etc":244444.44,"vac":55555.56,"vacRag":"green","tcpi":0.92,"tcpiRag":"green","caveat":"ETC and VAC use the CPI-based EAC (BAC / CPI) as the default method — see eacPlannedRateBased and eacCurrentEfficiencyBased for the other two independent EAC estimates."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/earned-schedule":{"post":{"summary":"Calculate earned schedule metrics (SPI(t), time-based schedule variance)","tags":["Project Management"],"description":"Calculates earned schedule metrics — a time-based alternative to the cost-based SPI from classic earned value management, which becomes unreliable near project end. Use this when a project manager wants an accurate schedule performance read late in a project. Returns the earned schedule, SPI(t), and time-based schedule variance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plannedDurationMonths":{"type":"number","description":"Total planned project duration in months. Example: 12"},"currentTimeNow":{"type":"number","description":"Current elapsed time in months since project start. Example: 7"},"pvCurvePoints":{"type":"array","items":{"type":"number"},"description":"Cumulative planned value at each month, one entry per month from project start. Example: [10, 25, 40, 55, 70, 85, 100]"},"ev":{"type":"number","description":"Current cumulative earned value. Example: 60"},"projectStartDate":{"type":"string","description":"Optional project start date, YYYY-MM-DD, used to compute a projected finish date. Example: \"2026-01-01\""}},"required":["plannedDurationMonths","currentTimeNow","pvCurvePoints","ev"]}}}},"responses":{"200":{"description":"Earned schedule, SPI(t), time-based schedule variance, and a projected completion date interpolated from the PV S-curve.","content":{"application/json":{"schema":{"type":"object","description":"Earned schedule, SPI(t), time-based schedule variance, and a projected completion date interpolated from the PV S-curve.","properties":{"result":{"type":"object","description":"The earned schedule calculation.","properties":{"earnedSchedule":{"type":"number","description":"ES — time at which the planned value curve would reach current EV, interpolated from pvCurvePoints, in months. Example: 4.33"},"actualTime":{"type":"number","description":"AT — actual elapsed time, echoed from currentTimeNow. Example: 7"},"svt":{"type":"number","description":"SV(t) = ES - AT. Negative means behind schedule. Example: -2.67"},"spit":{"type":"number","description":"SPI(t) = ES / AT. Below 1.0 means behind schedule. Example: 0.62"},"scheduleStatus":{"type":"string","description":"\"ahead\", \"onTrack\", or \"behind\", derived from SPI(t). Example: \"behind\""},"independentEacTimeMonths":{"type":["null","number"],"description":"IEAC(t) = plannedDurationMonths / SPI(t); null if SPI(t) is 0. Example: 19.38"},"predictedCompletionDate":{"type":["null","string"],"description":"Calendar date the project is predicted to finish; null unless projectStartDate was supplied. Example: \"2027-08-13\""},"caveat":{"type":"string","description":"Explains why Earned Schedule is preferred to SPI late in a project."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"BehindScheduleProject":{"summary":"7 months into a 12-month project, EV of 60 against a 12-point PV S-curve","value":{"result":{"earnedSchedule":4.33,"actualTime":7,"svt":-2.67,"spit":0.62,"scheduleStatus":"behind","independentEacTimeMonths":19.38,"predictedCompletionDate":"2027-08-13","caveat":"Earned Schedule interpolates time-based progress from your PV S-curve — more accurate than SPI (a cost-based ratio) for predicting completion dates, especially as SPI trends toward 1.0 near project end regardless of true schedule health. Interpolation between months is linear within each segment."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/pert-estimate":{"get":{"summary":"Calculate a PERT three-point task duration estimate","tags":["Project Management"],"description":"Calculates a weighted expected duration and standard deviation from optimistic, most likely, and pessimistic time estimates (the PERT technique). Use this when a project manager wants a single expected duration for a task with uncertain timing. Returns the expected duration and standard deviation.","parameters":[{"schema":{"type":"string"},"in":"query","name":"optimistic","required":true,"description":"Optimistic (best-case) duration estimate. Example: 3"},{"schema":{"type":"string"},"in":"query","name":"mostLikely","required":true,"description":"Most likely duration estimate. Example: 5"},{"schema":{"type":"string"},"in":"query","name":"pessimistic","required":true,"description":"Pessimistic (worst-case) duration estimate. Example: 10"}],"responses":{"200":{"description":"The PERT-weighted expected duration, standard deviation, variance, and P80/P90 estimates.","content":{"application/json":{"schema":{"type":"object","description":"The PERT-weighted expected duration, standard deviation, variance, and P80/P90 estimates.","properties":{"result":{"type":"object","description":"The PERT estimate.","properties":{"weightedAverage":{"type":"number","description":"(O + 4M + P) / 6 — the PERT expected duration. Example: 5.5"},"standardDeviation":{"type":"number","description":"(P - O) / 6. Example: 1.17"},"variance":{"type":"number","description":"standardDeviation squared. Example: 1.36"},"p80":{"type":"number","description":"80th-percentile duration under a normal approximation. Example: 6.48"},"p90":{"type":"number","description":"90th-percentile duration under a normal approximation. Example: 7"},"caveat":{"type":"string","description":"Explains that P80/P90 use a normal approximation, not an exact beta-distribution quantile."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"ThreePointEstimate":{"summary":"Optimistic 3, most likely 5, pessimistic 10 days","value":{"result":{"weightedAverage":5.5,"standardDeviation":1.17,"variance":1.36,"p80":6.48,"p90":7,"caveat":"P80/P90 assume a normal approximation to the PERT beta distribution — a common simplification, not an exact beta-distribution quantile."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/contingency-reserve":{"post":{"summary":"Calculate a project contingency reserve from a risk register","tags":["Project Management"],"description":"Calculates a recommended contingency reserve using expected monetary value (probability x impact) summed across a project's risk register. Use this when a project manager is budgeting for known risks and wants a data-driven reserve figure rather than an arbitrary percentage. Returns the recommended reserve and its percentage of total budget.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"risks":{"type":"array","description":"The project risk register. Example: [{\"probability\": 0.3, \"impact\": 20000}, {\"probability\": 0.1, \"impact\": 50000}]","items":{"type":"object","properties":{"probability":{"type":"number","description":"Probability of the risk occurring, 0-1. Example: 0.3"},"impact":{"type":"number","description":"Cost impact if the risk occurs. Example: 20000"}},"required":["probability","impact"]}},"totalBudget":{"type":"number","description":"Optional total project budget, used to express the reserve as a percentage. Example: 100000"}},"required":["risks"]}}}},"responses":{"200":{"description":"The recommended contingency reserve, computed from expected monetary value across the risk register.","content":{"application/json":{"schema":{"type":"object","description":"The recommended contingency reserve, computed from expected monetary value across the risk register.","properties":{"result":{"type":"object","description":"The contingency reserve calculation.","properties":{"riskExpectedValues":{"type":"array","description":"Each risk's probability, impact, and expected value (probability x impact).","items":{"type":"object","properties":{"probability":{"type":"number","description":"Probability of the risk occurring, 0-1. Example: 0.3"},"impact":{"type":"number","description":"Cost impact if the risk occurs. Example: 20000"},"expectedValue":{"type":"number","description":"probability x impact. Example: 6000"}}}},"totalContingencyReserve":{"type":"number","description":"Sum of expected values across all risks. Example: 11000"},"recommendedReservePercentOfBudget":{"type":["null","number"],"description":"totalContingencyReserve as a percentage of totalBudget; null if totalBudget was not supplied. Example: 11"},"caveat":{"type":"string","description":"Explains the expected-monetary-value technique and its limits."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"TwoRiskRegister":{"summary":"Reserve for a two-risk register against a $100k budget","value":{"result":{"riskExpectedValues":[{"probability":0.3,"impact":20000,"expectedValue":6000},{"probability":0.1,"impact":50000,"expectedValue":5000}],"totalContingencyReserve":11000,"recommendedReservePercentOfBudget":11,"caveat":"Contingency reserve is the sum of probability x impact across known risks (expected monetary value) — a standard PMI technique, not a guarantee; unknown-unknowns typically need a separate management reserve on top of this."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/risk-exposure-score":{"get":{"summary":"Calculate a project risk exposure score","tags":["Project Management"],"description":"Calculates a risk exposure score (probability x impact) on a chosen scale. Use this when a project manager wants a single comparable score for ranking risks in a risk register. Returns the exposure score and a severity classification.","parameters":[{"schema":{"type":"string"},"in":"query","name":"probability","required":true,"description":"Probability of the risk occurring. Example: 0.3"},{"schema":{"type":"string"},"in":"query","name":"impact","required":true,"description":"Impact if the risk occurs, on the chosen scale. Example: 4"},{"schema":{"type":"string","enum":["1","5","10"]},"in":"query","name":"scale","required":true,"description":"The scale probability/impact are scored on: 1, 5, or 10. Example: 5"}],"responses":{"200":{"description":"The risk exposure score, its position on the probability/impact matrix, and a recommended response.","content":{"application/json":{"schema":{"type":"object","description":"The risk exposure score, its position on the probability/impact matrix, and a recommended response.","properties":{"result":{"type":"object","description":"The risk exposure calculation.","properties":{"score":{"type":"number","description":"probability x impact. Example: 1.2"},"matrixPosition":{"type":"string","description":"\"low\", \"medium\", \"high\", or \"critical\" — quartile band of score relative to the scale's maximum. Example: \"low\""},"recommendedResponse":{"type":"string","description":"\"accept\", \"transfer\", \"mitigate\", or \"avoid\", derived from matrixPosition. Example: \"accept\""},"caveat":{"type":"string","description":"Explains matrixPosition banding and that recommendedResponse is general guidance."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"LowExposureRisk":{"summary":"Probability 0.3, impact 4, on a 1-5 scale","value":{"result":{"score":1.2,"matrixPosition":"low","recommendedResponse":"accept","caveat":"Matrix position is quartile-banded on probability x impact relative to the scale's maximum possible score. The recommended response is a general PMI-style guideline (accept/transfer/mitigate/avoid), not a substitute for a qualified risk assessment."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/burn-rate":{"get":{"summary":"Calculate project burn rate and projected completion date","tags":["Project Management"],"description":"Calculates how fast a budget is being spent and projects when it will run out. Use this when a project manager wants to know if a project is on track to finish within budget. Returns the burn rate, projected total spend, and days remaining at the current rate.","parameters":[{"schema":{"type":"string"},"in":"query","name":"totalBudget","required":true,"description":"Total approved project budget. Example: 100000"},{"schema":{"type":"string"},"in":"query","name":"spent","required":true,"description":"Amount spent so far. Example: 45000"},{"schema":{"type":"string"},"in":"query","name":"elapsedDays","required":true,"description":"Days elapsed since project start. Example: 60"},{"schema":{"type":"string"},"in":"query","name":"totalDays","required":true,"description":"Total planned project duration in days. Example: 180"},{"schema":{"type":"string"},"in":"query","name":"projectStartDate","required":false,"description":"Optional project start date, YYYY-MM-DD, used to compute a projected completion date. Example: \"2026-01-01\""}],"responses":{"200":{"description":"The project burn rate, projected total spend, and projected budget-exhaustion date.","content":{"application/json":{"schema":{"type":"object","description":"The project burn rate, projected total spend, and projected budget-exhaustion date.","properties":{"result":{"type":"object","description":"The burn rate calculation.","properties":{"dailyBurnRate":{"type":"number","description":"Average spend per elapsed day. Example: 750"},"projectedTotalSpend":{"type":"number","description":"Daily burn rate projected across totalDays. Example: 135000"},"varianceAtCompletion":{"type":"number","description":"totalBudget minus projectedTotalSpend. Positive = under budget, negative = over. Example: -35000"},"status":{"type":"string","description":"Budget status derived from varianceAtCompletion. Example: \"overBudget\""},"daysUntilBudgetExhausted":{"type":["null","number"],"description":"Days from now until the budget runs out at the current rate; null if the burn rate is 0. Example: 73.33"},"budgetExhaustionDate":{"type":["null","string"],"description":"Calendar date the budget is projected to run out; null unless projectStartDate was supplied. Example: \"2026-05-14\""},"caveat":{"type":"string","description":"Explains the linear-projection assumption behind the forecast."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"OverBudgetProject":{"summary":"60 days into a 180-day, $100k project, $45k spent","value":{"result":{"dailyBurnRate":750,"projectedTotalSpend":135000,"varianceAtCompletion":-35000,"status":"overBudget","daysUntilBudgetExhausted":73.33,"budgetExhaustionDate":"2026-05-14","caveat":"Projects the current average daily spend rate forward linearly — does not account for planned spend changes (e.g. a final procurement burst or wind-down)."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cost-benefit-analysis":{"post":{"summary":"Run a cost-benefit analysis with discounted costs and benefits","tags":["Project Management"],"description":"Discounts a series of future costs and benefits back to present value and compares them. Use this when a user is deciding whether a project or investment is worth pursuing based on its full cost/benefit timeline. Returns net present value, benefit-cost ratio, and whether the project is worthwhile.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"costs":{"type":"array","description":"Costs by period. Example: [{\"period\": 0, \"amount\": 50000}, {\"period\": 1, \"amount\": 10000}]","items":{"type":"object","properties":{"period":{"type":"number","description":"Period number (0 = now). Example: 0"},"amount":{"type":"number","description":"Cost amount in that period. Example: 50000"}},"required":["period","amount"]}},"benefits":{"type":"array","description":"Benefits by period. Example: [{\"period\": 1, \"amount\": 20000}, {\"period\": 2, \"amount\": 20000}]","items":{"type":"object","properties":{"period":{"type":"number","description":"Period number. Example: 1"},"amount":{"type":"number","description":"Benefit amount in that period. Example: 20000"}},"required":["period","amount"]}},"discountRate":{"type":"number","description":"Discount rate as a percentage, e.g. 10 for 10%. Example: 10"}},"required":["costs","benefits","discountRate"]}}}},"responses":{"200":{"description":"Discounted present values of costs and benefits, net present value, benefit-cost ratio, ROI, and undiscounted payback period.","content":{"application/json":{"schema":{"type":"object","description":"Discounted present values of costs and benefits, net present value, benefit-cost ratio, ROI, and undiscounted payback period.","properties":{"result":{"type":"object","description":"The cost-benefit analysis.","properties":{"presentValueOfCosts":{"type":"number","description":"Costs discounted to present value at discountRate. Example: 59090.91"},"presentValueOfBenefits":{"type":"number","description":"Benefits discounted to present value at discountRate. Example: 34710.74"},"npvOfNetBenefits":{"type":"number","description":"presentValueOfBenefits minus presentValueOfCosts. Example: -24380.17"},"benefitCostRatio":{"type":["null","number"],"description":"presentValueOfBenefits / presentValueOfCosts; null if present value of costs is 0. Example: 0.59"},"roiPercent":{"type":["null","number"],"description":"npvOfNetBenefits as a percentage of presentValueOfCosts; null if present value of costs is 0. Example: -41.26"},"paybackPeriod":{"type":["null","number"],"description":"Undiscounted period at which cumulative cash flow turns non-negative; null if never recouped. Example: null"},"caveat":{"type":"string","description":"Explains that BCR/ROI are discounted while payback period is undiscounted."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"SimpleTwoYearProject":{"summary":"Cost-benefit analysis at a 10% discount rate","value":{"result":{"presentValueOfCosts":59090.91,"presentValueOfBenefits":34710.74,"npvOfNetBenefits":-24380.17,"benefitCostRatio":0.59,"roiPercent":-41.26,"paybackPeriod":null,"caveat":"BCR and ROI use present-value (discounted) costs and benefits; the payback period uses undiscounted cumulative cash flow, the conventional simple-payback definition."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/resource-utilisation":{"get":{"summary":"Calculate resource utilisation percentage","tags":["Project Management"],"description":"Calculates what percentage of available capacity a resource (a person, team, or machine) is being used. Use this when a project or resource manager wants to check for over- or under-utilisation. Returns the utilisation percentage and a status label.","parameters":[{"schema":{"type":"string"},"in":"query","name":"availableHours","required":true,"description":"Total available hours in the period. Example: 160"},{"schema":{"type":"string"},"in":"query","name":"usedHours","required":true,"description":"Hours actually used/booked in the period. Example: 140"}],"responses":{"200":{"description":"The resource utilisation percentage and a benchmark status label.","content":{"application/json":{"schema":{"type":"object","description":"The resource utilisation percentage and a benchmark status label.","properties":{"result":{"type":"object","description":"The utilisation calculation.","properties":{"utilisationPercent":{"type":"number","description":"usedHours / availableHours as a percentage. Example: 87.5"},"benchmark":{"type":"string","description":"\"underUtilised\", \"optimal\", or \"atRiskOfBurnout\", derived from utilisationPercent. Example: \"atRiskOfBurnout\""},"caveat":{"type":"string","description":"Explains the utilisation bands are general guidance, not a fixed rule."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"HighUtilisation":{"summary":"140 of 160 available hours used","value":{"result":{"utilisationPercent":87.5,"benchmark":"atRiskOfBurnout","caveat":"Under 70% is generally under-utilised, 70-85% is a commonly cited optimal range, and over 85% risks burnout — general guidance, not a fixed rule for every role or team."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/project-payback-period":{"post":{"summary":"Calculate a project payback period from cash flows","tags":["Project Management"],"description":"Calculates how many periods it takes for cumulative cash flows to recover an initial investment. Use this when a user wants a simple payback-period read on a project, alongside or instead of NPV/IRR. Returns the payback period and cumulative cash flow by period.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"initialInvestment":{"type":"number","description":"Upfront investment (positive number). Example: 50000"},"periodicCashFlows":{"type":"array","items":{"type":"number"},"description":"Cash flow for each period, starting at period 1. Example: [15000, 15000, 15000, 15000, 15000]"}},"required":["initialInvestment","periodicCashFlows"]}}}},"responses":{"200":{"description":"The payback period, breakeven period, and cumulative cash flow schedule.","content":{"application/json":{"schema":{"type":"object","description":"The payback period, breakeven period, and cumulative cash flow schedule.","properties":{"result":{"type":"object","description":"The payback period calculation.","properties":{"paybackPeriod":{"type":["null","number"],"description":"Fractional period at which cumulative cash flow reaches zero; null if never recouped. Example: 3.33"},"breakevenPeriod":{"type":["null","number"],"description":"First whole period at or after which cumulative cash flow is non-negative; null if never recouped. Example: 4"},"schedule":{"type":"array","description":"Cash flow and running cumulative cash flow for each period.","items":{"type":"object","properties":{"period":{"type":"number","description":"Period number, starting at 1. Example: 1"},"cashFlow":{"type":"number","description":"Cash flow in this period. Example: 15000"},"cumulativeCashFlow":{"type":"number","description":"Running total including the initial investment. Example: -35000"}}}}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"FiveEqualPeriods":{"summary":"$50k investment recouped by five equal $15k cash flows","value":{"result":{"paybackPeriod":3.33,"breakevenPeriod":4,"schedule":[{"period":1,"cashFlow":15000,"cumulativeCashFlow":-35000},{"period":2,"cashFlow":15000,"cumulativeCashFlow":-20000},{"period":3,"cashFlow":15000,"cumulativeCashFlow":-5000},{"period":4,"cashFlow":15000,"cumulativeCashFlow":10000},{"period":5,"cashFlow":15000,"cumulativeCashFlow":25000}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/critical-path":{"post":{"summary":"Find the critical path through a project schedule","tags":["Project Management"],"description":"Runs the Critical Path Method (CPM) over a list of project activities with durations and dependencies. Use this when a project manager wants to know the minimum project duration and which activities have zero slack. Returns the critical path, project duration, and slack for every activity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","description":"Project activities with durations and dependencies. Example: [{\"id\": \"A\", \"duration\": 5, \"dependsOn\": []}, {\"id\": \"B\", \"duration\": 3, \"dependsOn\": [\"A\"]}]","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique activity id. Example: \"A\""},"duration":{"type":"number","description":"Activity duration in days. Example: 5"},"dependsOn":{"type":"array","items":{"type":"string"},"description":"Ids of activities that must finish before this one starts. Example: [\"A\"]"}},"required":["id","duration"]}}},"required":["activities"]}}}},"responses":{"200":{"description":"The critical path, project duration, and forward/backward-pass schedule (early/late start/finish, float) for every activity.","content":{"application/json":{"schema":{"type":"object","description":"The critical path, project duration, and forward/backward-pass schedule (early/late start/finish, float) for every activity.","properties":{"result":{"type":"object","description":"The critical path method result.","properties":{"activities":{"type":"array","description":"Every activity with its computed schedule and float, in topological order.","items":{"type":"object","properties":{"id":{"type":"string","description":"Activity id. Example: \"A\""},"duration":{"type":"number","description":"Activity duration in days. Example: 5"},"earlyStart":{"type":"number","description":"Earliest this activity can start. Example: 0"},"earlyFinish":{"type":"number","description":"Earliest this activity can finish. Example: 5"},"lateStart":{"type":"number","description":"Latest this activity can start without delaying the project. Example: 0"},"lateFinish":{"type":"number","description":"Latest this activity can finish without delaying the project. Example: 5"},"float":{"type":"number","description":"Slack: lateStart minus earlyStart. Zero means the activity is critical. Example: 0"},"isCritical":{"type":"boolean","description":"True if float is zero. Example: true"}}}},"criticalPath":{"type":"array","items":{"type":"string"},"description":"One connected zero-float chain of activity ids from a critical start to a critical end. Example: [\"A\", \"B\"]"},"projectDuration":{"type":"number","description":"Minimum total project duration. Example: 8"},"caveat":{"type":"string","description":"Explains that no resource constraints/calendars are modelled and that multiple parallel critical chains may exist."}}},"meta":{"type":"object","description":"Metadata about how the result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp the result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"TwoActivityChain":{"summary":"Two dependent activities, A (5 days) then B (3 days)","value":{"result":{"activities":[{"id":"A","duration":5,"earlyStart":0,"earlyFinish":5,"lateStart":0,"lateFinish":5,"float":0,"isCritical":true},{"id":"B","duration":3,"earlyStart":5,"earlyFinish":8,"lateStart":5,"lateFinish":8,"float":0,"isCritical":true}],"criticalPath":["A","B"],"projectDuration":8,"caveat":"Duration and dependencies only — no resource constraints or calendars are modelled. If a network has multiple parallel zero-float chains, criticalPath shows one of them (chosen deterministically by activity id); check the isCritical flag on every activity for the complete set."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/timezone-conversion":{"get":{"summary":"Convert a date and time from one IANA timezone to up to 5 target timezones.","tags":["Dates & Time"],"description":"Convert a date and time from one IANA timezone to up to 5 target timezones. Use this when a user wants to know what time it is (or will be) somewhere else. Returns the converted time with UTC offset, DST status, and day difference for each target. Example: \"What time is 3pm in London on 15 June in New York and Tokyo?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"datetime","required":true,"description":"Wall-clock date/time in the source timezone, YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss. Example: \"2026-06-15T15:00:00\""},{"schema":{"type":"string"},"in":"query","name":"sourceTimezone","required":true,"description":"IANA timezone name for datetime. Example: \"Europe/London\""},{"schema":{"type":"string"},"in":"query","name":"targetTimezones","required":true,"description":"IANA timezone names to convert into (1-5). Example: [\"America/New_York\", \"Asia/Tokyo\"]"}],"responses":{"200":{"description":"The source date/time converted into each target timezone, with UTC offset, DST status, and day difference.","content":{"application/json":{"schema":{"type":"object","description":"The source date/time converted into each target timezone, with UTC offset, DST status, and day difference.","properties":{"result":{"type":"object","description":"The source time and its conversions.","properties":{"sourceDateTime":{"type":"string","description":"The source wall-clock date/time, echoed back. Example: \"2026-06-15T15:00:00\""},"sourceTimezone":{"type":"string","description":"The source IANA timezone. Example: \"Europe/London\""},"sourceUtcOffset":{"type":"string","description":"The source timezone's UTC offset at this instant. Example: \"+01:00\""},"sourceDstActive":{"type":"boolean","description":"Whether daylight saving time is active in the source timezone at this instant. Example: true"},"utcDateTime":{"type":"string","description":"The source instant, converted to UTC ISO 8601. Example: \"2026-06-15T14:00:00.000Z\""},"targets":{"type":"array","description":"The converted date/time in each target timezone.","items":{"type":"object","properties":{"timezone":{"type":"string","description":"Target IANA timezone. Example: \"America/New_York\""},"convertedDateTime":{"type":"string","description":"Wall-clock date/time in the target timezone. Example: \"2026-06-15T10:00:00\""},"utcOffset":{"type":"string","description":"Target timezone's UTC offset at this instant. Example: \"-04:00\""},"dstActive":{"type":"boolean","description":"Whether daylight saving time is active in the target timezone at this instant. Example: true"},"dayDifference":{"type":"number","description":"Target calendar date minus source calendar date, in days. Example: 0"}}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"LondonToNewYorkAndTokyo":{"summary":"Convert 3pm London on 15 June 2026 to New York and Tokyo","value":{"result":{"sourceDateTime":"2026-06-15T15:00:00","sourceTimezone":"Europe/London","sourceUtcOffset":"+01:00","sourceDstActive":true,"utcDateTime":"2026-06-15T14:00:00.000Z","targets":[{"timezone":"America/New_York","convertedDateTime":"2026-06-15T10:00:00","utcOffset":"-04:00","dstActive":true,"dayDifference":0},{"timezone":"Asia/Tokyo","convertedDateTime":"2026-06-15T23:00:00","utcOffset":"+09:00","dstActive":false,"dayDifference":0}]},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/unix-timestamp":{"get":{"summary":"Convert a Unix timestamp to a human-readable date, or a date to a Unix timestamp.","tags":["Dates & Time"],"description":"Convert a Unix timestamp to a human-readable date, or a date to a Unix timestamp. Use this when a user has a raw timestamp from logs or an API and wants it in a readable date, or vice versa. Returns the converted value with ISO 8601, RFC 2822, and relative time. Example: \"What date is Unix timestamp 1735689600?\"","parameters":[{"schema":{"type":"string","enum":["toHuman","toUnix"]},"in":"query","name":"direction","required":true,"description":"'toHuman' converts a Unix timestamp to a date, 'toUnix' converts a date to a Unix timestamp. Example: \"toHuman\""},{"schema":{"type":"string"},"in":"query","name":"unixTimestamp","required":false,"description":"Required for direction 'toHuman'. Example: 1735689600"},{"schema":{"type":"string","enum":["seconds","milliseconds"]},"in":"query","name":"unit","required":false,"description":"Unit of unixTimestamp. Defaults to 'seconds'. Example: \"seconds\""},{"schema":{"type":"string"},"in":"query","name":"datetime","required":false,"description":"Required for direction 'toUnix' — wall-clock date/time in `timezone`. Example: \"2026-01-01T00:00:00\""},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name. Defaults to 'UTC'. Example: \"UTC\""}],"responses":{"200":{"description":"The converted value between a Unix timestamp and a human-readable date, in several formats.","content":{"application/json":{"schema":{"type":"object","description":"The converted value between a Unix timestamp and a human-readable date, in several formats.","properties":{"result":{"type":"object","description":"The conversion result.","properties":{"unixSeconds":{"type":"number","description":"The instant as Unix seconds. Example: 1735689600"},"unixMilliseconds":{"type":"number","description":"The instant as Unix milliseconds. Example: 1735689600000"},"datetimeUTC":{"type":"string","description":"The instant, UTC wall-clock, no offset suffix. Example: \"2025-01-01T00:00:00\""},"datetimeLocal":{"type":["null","string"],"description":"Wall-clock time in `timezone`, or null if no timezone was given. Example: null"},"timezone":{"type":["null","string"],"description":"The IANA timezone used, or null if none was given. Example: null"},"utcOffset":{"type":["null","string"],"description":"UTC offset of `timezone` at this instant, or null if none was given. Example: null"},"iso8601":{"type":"string","description":"The instant as full ISO 8601. Example: \"2025-01-01T00:00:00.000Z\""},"rfc2822":{"type":"string","description":"The instant as an RFC 2822-style timestamp. Example: \"Wed, 01 Jan 2025 00:00:00 GMT\""},"relativeTime":{"type":"string","description":"Human-readable relative time from now. Example: \"1 year ago\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"UnixToHuman":{"summary":"Convert Unix timestamp 1735689600 to a human-readable date","value":{"result":{"unixSeconds":1735689600,"unixMilliseconds":1735689600000,"datetimeUTC":"2025-01-01T00:00:00","datetimeLocal":null,"timezone":null,"utcOffset":null,"iso8601":"2025-01-01T00:00:00.000Z","rfc2822":"Wed, 01 Jan 2025 00:00:00 GMT","relativeTime":"1 year ago"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/meeting-planner":{"get":{"summary":"Find overlapping working hours across up to 8 cities and suggest the best meeting times.","tags":["Dates & Time"],"description":"Find overlapping working hours across up to 8 cities and suggest the best meeting times. Use this when a user is scheduling a meeting across time zones and wants to know when everyone is available. Returns overlapping time slots and a 24-hour UTC availability grid. Example: \"When can a team in London, New York, and Tokyo all meet during working hours?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"cities","required":true,"description":"Cities to compare (1-8). Example: [{\"name\": \"London\", \"timezone\": \"Europe/London\"}, {\"name\": \"New York\", \"timezone\": \"America/New_York\"}]"},{"schema":{"type":"string"},"in":"query","name":"workingHoursStart","required":false,"description":"Local working-hours start, 24h clock. Defaults to 9. Example: 9"},{"schema":{"type":"string"},"in":"query","name":"workingHoursEnd","required":false,"description":"Local working-hours end, 24h clock. Defaults to 17. Example: 17"}],"responses":{"200":{"description":"Each city's current local time, a 24-hour UTC availability grid, and the best suggested meeting slots.","content":{"application/json":{"schema":{"type":"object","description":"Each city's current local time, a 24-hour UTC availability grid, and the best suggested meeting slots.","properties":{"result":{"type":"object","description":"The cross-timezone availability analysis.","properties":{"cities":{"type":"array","description":"Each city's current local time and UTC offset.","items":{"type":"object","properties":{"name":{"type":"string","description":"City label as given in the request. Example: \"London\""},"timezone":{"type":"string","description":"IANA timezone name. Example: \"Europe/London\""},"currentDateTime":{"type":"string","description":"Current wall-clock date/time in this city. Example: \"2026-06-17T14:00:00\""},"utcOffset":{"type":"string","description":"Current UTC offset. Example: \"+01:00\""}}}},"grid":{"type":"array","description":"24 hourly slots (UTC), each showing which cities are within working hours.","items":{"type":"object","properties":{"utcHour":{"type":"number","description":"Hour of the day in UTC, 0-23. Example: 13"},"availableCities":{"type":"array","items":{"type":"string"},"description":"Names of cities within working hours at this UTC hour. Example: [\"London\", \"New York\"]"},"availableCount":{"type":"number","description":"Number of cities available at this hour. Example: 2"},"totalCities":{"type":"number","description":"Total number of cities compared. Example: 2"},"status":{"type":"string","description":"'all' if every city is available, 'partial' if some are, 'none' if none are. Example: \"all\""}}}},"suggestedSlots":{"type":"array","description":"Up to 3 UTC hours with the highest city availability, each with per-city local times.","items":{"type":"object","properties":{"utcHour":{"type":"number","description":"Hour of the day in UTC, 0-23. Example: 13"},"availableCount":{"type":"number","description":"Number of cities available at this hour. Example: 2"},"localTimes":{"type":"array","description":"Local wall-clock time in each city at this slot.","items":{"type":"object","properties":{"name":{"type":"string","description":"City label. Example: \"London\""},"localTime":{"type":"string","description":"Local wall-clock time. Example: \"2026-06-17T14:00:00\""},"withinWorkingHours":{"type":"boolean","description":"Whether this local time falls within that city's working hours. Example: true"}}}}}}},"caveat":{"type":"string","description":"Note on the assumptions used (working-hour window, weekday-only, no holiday awareness)."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-06-17T00:00:00.000Z\""}}}}},"examples":{"LondonNewYorkOverlap":{"summary":"Overlapping working hours between London and New York","value":{"result":{"cities":[{"name":"London","timezone":"Europe/London","currentDateTime":"2026-06-17T01:00:00","utcOffset":"+01:00"},{"name":"New York","timezone":"America/New_York","currentDateTime":"2026-06-16T20:00:00","utcOffset":"-04:00"}],"grid":[{"utcHour":0,"availableCities":[],"availableCount":0,"totalCities":2,"status":"none"},{"utcHour":8,"availableCities":["London"],"availableCount":1,"totalCities":2,"status":"partial"},{"utcHour":13,"availableCities":["London","New York"],"availableCount":2,"totalCities":2,"status":"all"},{"utcHour":14,"availableCities":["London","New York"],"availableCount":2,"totalCities":2,"status":"all"},{"utcHour":15,"availableCities":["London","New York"],"availableCount":2,"totalCities":2,"status":"all"},{"utcHour":16,"availableCities":["New York"],"availableCount":1,"totalCities":2,"status":"partial"},{"utcHour":21,"availableCities":[],"availableCount":0,"totalCities":2,"status":"none"}],"suggestedSlots":[{"utcHour":13,"availableCount":2,"localTimes":[{"name":"London","localTime":"2026-06-17T14:00:00","withinWorkingHours":true},{"name":"New York","localTime":"2026-06-17T09:00:00","withinWorkingHours":true}]},{"utcHour":14,"availableCount":2,"localTimes":[{"name":"London","localTime":"2026-06-17T15:00:00","withinWorkingHours":true},{"name":"New York","localTime":"2026-06-17T10:00:00","withinWorkingHours":true}]},{"utcHour":15,"availableCount":2,"localTimes":[{"name":"London","localTime":"2026-06-17T16:00:00","withinWorkingHours":true},{"name":"New York","localTime":"2026-06-17T11:00:00","withinWorkingHours":true}]}],"caveat":"Working hours are 9:00-17:00 local time, Monday-Friday, evaluated against today's date in each city's timezone — public holidays are not accounted for."},"meta":{"computedAt":"2026-06-17T00:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/date-format-converter":{"get":{"summary":"Convert a date string into every common format at once.","tags":["Dates & Time"],"description":"Convert a date string into every common format at once. Use this when a user has a date in one format and needs it in another — DD/MM/YYYY, MM/DD/YYYY, ISO 8601, DD-MMM-YYYY, RFC 2822, Unix timestamp, ordinal, or long form. Example: \"Convert 03/04/2026 to ISO 8601 format.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"dateString","required":true,"description":"A date in almost any common format. Example: \"03/04/2026\""},{"schema":{"type":"string","enum":["DMY","MDY","ISO","auto"]},"in":"query","name":"detectedFormat","required":false,"description":"How to interpret an ambiguous numeric date. Defaults to auto. Example: \"DMY\""}],"responses":{"200":{"description":"The parsed date, rendered in every common format at once.","content":{"application/json":{"schema":{"type":"object","description":"The parsed date, rendered in every common format at once.","properties":{"result":{"type":"object","description":"The date rendered in each supported format.","properties":{"parsedDate":{"type":"string","description":"The resolved date, ISO 8601 date-only. Example: \"2026-04-03\""},"ddmmyyyy":{"type":"string","description":"DD/MM/YYYY format. Example: \"03/04/2026\""},"mmddyyyy":{"type":"string","description":"MM/DD/YYYY format. Example: \"04/03/2026\""},"iso8601":{"type":"string","description":"ISO 8601 date-only format. Example: \"2026-04-03\""},"ddMmmYyyy":{"type":"string","description":"DD-MMM-YYYY format. Example: \"03-Apr-2026\""},"rfc2822":{"type":"string","description":"RFC 2822-style format. Example: \"Fri, 03 Apr 2026 00:00:00 GMT\""},"unixTimestamp":{"type":"number","description":"Seconds since the Unix epoch. Example: 1775174400"},"ordinal":{"type":"string","description":"Long form with an ordinal day suffix. Example: \"April 3rd, 2026\""},"longForm":{"type":"string","description":"Long form without an ordinal suffix. Example: \"April 3, 2026\""},"dayOfWeek":{"type":"string","description":"Full weekday name. Example: \"Friday\""},"caveat":{"type":"string","description":"Note on how ambiguous numeric dates are disambiguated."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"DdMmYyyyToIso":{"summary":"Convert 03/04/2026 (DD/MM/YYYY) to every format","value":{"result":{"parsedDate":"2026-04-03","ddmmyyyy":"03/04/2026","mmddyyyy":"04/03/2026","iso8601":"2026-04-03","ddMmmYyyy":"03-Apr-2026","rfc2822":"Fri, 03 Apr 2026 00:00:00 GMT","unixTimestamp":1775174400,"ordinal":"April 3rd, 2026","longForm":"April 3, 2026","dayOfWeek":"Friday","caveat":"Ambiguous numeric dates (e.g. '01/02/2026') are disambiguated by detectedFormat if given, otherwise by whichever segment exceeds 12, defaulting to MM/DD/YYYY when still ambiguous."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/week-number":{"get":{"summary":"Find the ISO week number, US week number, week of month, day of year and quarter for a date — or reverse-lookup a date range from an ISO year and week.","tags":["Dates & Time"],"description":"Find the ISO week number, US week number, week of month, day of year and quarter for a date — or reverse-lookup a date range from an ISO year and week. Use this when a user asks what week number a date falls in, or what dates a given week covers. Example: \"What ISO week number is 15 October 2026?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"date","required":false,"description":"YYYY-MM-DD — forward mode: date to week info. Example: \"2026-10-15\""},{"schema":{"type":"string"},"in":"query","name":"reverseYear","required":false,"description":"ISO year — reverse mode, used with reverseWeek. Example: 2026"},{"schema":{"type":"string"},"in":"query","name":"reverseWeek","required":false,"description":"ISO week number 1-53 — reverse mode, used with reverseYear. Example: 42"}],"responses":{"200":{"description":"The ISO/US week number and calendar position for a date (forward mode), or the date range covered by an ISO year/week (reverse mode).","content":{"application/json":{"schema":{"type":"object","description":"The ISO/US week number and calendar position for a date (forward mode), or the date range covered by an ISO year/week (reverse mode).","properties":{"result":{"type":"object","description":"Forward-mode fields are null in reverse mode, and vice versa.","properties":{"date":{"type":["null","string"],"description":"The resolved date, YYYY-MM-DD (forward mode only). Example: \"2026-10-15\""},"isoWeek":{"type":["null","number"],"description":"ISO 8601 week number, 1-53 (forward mode only). Example: 42"},"isoYear":{"type":["null","number"],"description":"ISO week-numbering year, which can differ from the calendar year near year boundaries (forward mode only). Example: 2026"},"usWeek":{"type":["null","number"],"description":"US-style week number, Sunday-start (forward mode only). Example: 42"},"weekOfMonth":{"type":["null","number"],"description":"Week number within the calendar month, Monday-start (forward mode only). Example: 3"},"dayOfYear":{"type":["null","number"],"description":"Ordinal day within the calendar year, 1-366 (forward mode only). Example: 288"},"dayOfWeek":{"type":["null","string"],"description":"Full weekday name (forward mode only). Example: \"Thursday\""},"quarter":{"type":["null","number"],"description":"Calendar quarter, 1-4 (forward mode only). Example: 4"},"reverseLookup":{"type":["null","object"],"description":"The date range covered by reverseYear/reverseWeek (reverse mode only, otherwise null).","properties":{"isoYear":{"type":"number","description":"The ISO year requested. Example: 2026"},"isoWeek":{"type":"number","description":"The ISO week requested. Example: 42"},"weekStartDate":{"type":"string","description":"Monday of that ISO week, YYYY-MM-DD. Example: \"2026-10-12\""},"weekEndDate":{"type":"string","description":"Sunday of that ISO week, YYYY-MM-DD. Example: \"2026-10-18\""}}}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"ForwardLookup":{"summary":"Week info for 15 October 2026","value":{"result":{"date":"2026-10-15","isoWeek":42,"isoYear":2026,"usWeek":42,"weekOfMonth":3,"dayOfYear":288,"dayOfWeek":"Thursday","quarter":4,"reverseLookup":null},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/countdown":{"get":{"summary":"Count down to (or show elapsed time since) a target date and time in a given timezone.","tags":["Dates & Time"],"description":"Count down to (or show elapsed time since) a target date and time in a given timezone. Use this when a user wants to know exactly how long until an event, deadline, or launch — or how long ago something happened. Returns the difference broken down into years, months, weeks, days, hours, minutes and seconds. Example: \"How long until 1 January 2027 at midnight in New York?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"targetDate","required":true,"description":"Target date, YYYY-MM-DD. Example: \"2027-01-01\""},{"schema":{"type":"string"},"in":"query","name":"targetTime","required":false,"description":"Target time, HH:mm:ss. Defaults to 00:00:00. Example: \"00:00:00\""},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name for targetDate/targetTime. Defaults to 'UTC'. Example: \"America/New_York\""},{"schema":{"type":"string"},"in":"query","name":"eventName","required":false,"description":"Optional label for the event. Example: \"New Year\""}],"responses":{"200":{"description":"The time remaining until (or elapsed since) the target date/time, broken down into calendar units.","content":{"application/json":{"schema":{"type":"object","description":"The time remaining until (or elapsed since) the target date/time, broken down into calendar units.","properties":{"result":{"type":"object","description":"The countdown/elapsed breakdown.","properties":{"eventName":{"type":["null","string"],"description":"The label passed in, or null if none was given. Example: \"New Year\""},"targetDateTimeUTC":{"type":"string","description":"The target instant, converted to UTC ISO 8601. Example: \"2027-01-01T05:00:00.000Z\""},"isPast":{"type":"boolean","description":"Whether the target date/time is already in the past. Example: false"},"totalDays":{"type":"number","description":"Whole days between now and the target. Example: 145"},"totalSeconds":{"type":"number","description":"Total seconds between now and the target. Example: 12603825"},"years":{"type":"number","description":"Years component of the breakdown. Example: 0"},"months":{"type":"number","description":"Months component of the breakdown. Example: 4"},"weeks":{"type":"number","description":"Weeks component of the breakdown. Example: 3"},"days":{"type":"number","description":"Days component of the breakdown. Example: 2"},"hours":{"type":"number","description":"Hours component of the breakdown. Example: 21"},"minutes":{"type":"number","description":"Minutes component of the breakdown. Example: 3"},"seconds":{"type":"number","description":"Seconds component of the breakdown. Example: 46"}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"NewYearCountdown":{"summary":"Countdown to midnight New Year's in New York","value":{"result":{"eventName":"New Year","targetDateTimeUTC":"2027-01-01T05:00:00.000Z","isPast":false,"totalDays":145,"totalSeconds":12603825,"years":0,"months":4,"weeks":3,"days":2,"hours":21,"minutes":3,"seconds":46},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/time-duration":{"get":{"summary":"Calculate the exact duration between a start and end datetime, each with its own timezone.","tags":["Dates & Time"],"description":"Calculate the exact duration between a start and end datetime, each with its own timezone. Use this when a user needs a precise cross-timezone duration — e.g. how long a flight, call, or event spans in real elapsed time. Returns years, months, weeks, days, hours, minutes, seconds, and working days vs calendar days. Example: \"How long between 9am New York time on 1 March and 5pm London time on 15 March?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"startDatetime","required":true,"description":"Wall-clock start date/time in startTimezone. Example: \"2026-03-01T09:00:00\""},{"schema":{"type":"string"},"in":"query","name":"startTimezone","required":true,"description":"IANA timezone name for startDatetime. Example: \"America/New_York\""},{"schema":{"type":"string"},"in":"query","name":"endDatetime","required":true,"description":"Wall-clock end date/time in endTimezone. Example: \"2026-03-15T17:00:00\""},{"schema":{"type":"string"},"in":"query","name":"endTimezone","required":true,"description":"IANA timezone name for endDatetime. Example: \"Europe/London\""}],"responses":{"200":{"description":"The exact duration between a start and end datetime, each converted from its own timezone, broken down into calendar units and totals.","content":{"application/json":{"schema":{"type":"object","description":"The exact duration between a start and end datetime, each converted from its own timezone, broken down into calendar units and totals.","properties":{"result":{"type":"object","description":"The duration breakdown.","properties":{"startUTC":{"type":"string","description":"Start instant, converted to UTC ISO 8601. Example: \"2026-03-01T14:00:00.000Z\""},"endUTC":{"type":"string","description":"End instant, converted to UTC ISO 8601. Example: \"2026-03-15T17:00:00.000Z\""},"isNegative":{"type":"boolean","description":"Whether the end instant is before the start instant. Example: false"},"years":{"type":"number","description":"Years component of the breakdown. Example: 0"},"months":{"type":"number","description":"Months component of the breakdown. Example: 0"},"weeks":{"type":"number","description":"Weeks component of the breakdown. Example: 2"},"days":{"type":"number","description":"Days component of the breakdown. Example: 0"},"hours":{"type":"number","description":"Hours component of the breakdown. Example: 3"},"minutes":{"type":"number","description":"Minutes component of the breakdown. Example: 0"},"seconds":{"type":"number","description":"Seconds component of the breakdown. Example: 0"},"totalDays":{"type":"number","description":"Total whole days spanned. Example: 14"},"totalWeeks":{"type":"number","description":"Total whole weeks spanned. Example: 2"},"totalHours":{"type":"number","description":"Total whole hours spanned. Example: 339"},"totalMinutes":{"type":"number","description":"Total whole minutes spanned. Example: 20340"},"totalSeconds":{"type":"number","description":"Total whole seconds spanned. Example: 1220400"},"workingDays":{"type":"number","description":"Monday-Friday weekday count within the span, no holiday awareness. Example: 10"},"calendarDays":{"type":"number","description":"Total calendar days spanned, evaluated against the start timezone's calendar dates. Example: 14"},"caveat":{"type":"string","description":"Note on how workingDays is computed."}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"NewYorkToLondon":{"summary":"Duration from 9am New York on 1 March to 5pm London on 15 March 2026","value":{"result":{"startUTC":"2026-03-01T14:00:00.000Z","endUTC":"2026-03-15T17:00:00.000Z","isNegative":false,"years":0,"months":0,"weeks":2,"days":0,"hours":3,"minutes":0,"seconds":0,"totalDays":14,"totalWeeks":2,"totalHours":339,"totalMinutes":20340,"totalSeconds":1220400,"workingDays":10,"calendarDays":14,"caveat":"Working days are a simple Monday-Friday count with no public-holiday awareness, evaluated against the start timezone's calendar dates."},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/fiscal-year":{"get":{"summary":"Find the fiscal year, quarter, fiscal month and week, and days remaining, for a date and fiscal year start month.","tags":["Dates & Time"],"description":"Find the fiscal year, quarter, fiscal month and week, and days remaining, for a date and fiscal year start month. Use this when a user needs to map a calendar date onto their company's fiscal calendar. Example: \"What fiscal quarter is 15 October 2026 in, if our fiscal year starts in April?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"date","required":true,"description":"Date in YYYY-MM-DD format. Example: \"2026-10-15\""},{"schema":{"type":"string"},"in":"query","name":"fiscalYearStartMonth","required":true,"description":"Fiscal year start month, 1-12 (e.g. 4 for a UK-style April start). Example: 4"}],"responses":{"200":{"description":"The fiscal year, quarter, fiscal month and week, and days remaining, for the given date and fiscal year start month.","content":{"application/json":{"schema":{"type":"object","description":"The fiscal year, quarter, fiscal month and week, and days remaining, for the given date and fiscal year start month.","properties":{"result":{"type":"object","description":"The fiscal calendar position of the date.","properties":{"fiscalYearLabel":{"type":"string","description":"The fiscal year label. Example: \"FY2027\""},"quarter":{"type":"string","description":"Fiscal quarter: Q1, Q2, Q3 or Q4. Example: \"Q3\""},"fiscalMonth":{"type":"number","description":"1-indexed month number within the fiscal year. Example: 7"},"fiscalWeek":{"type":"number","description":"1-indexed week number within the fiscal year. Example: 29"},"daysRemainingInFiscalYear":{"type":"number","description":"Days from the given date until the fiscal year ends. Example: 167"},"fiscalYearStartDate":{"type":"string","description":"First day of the fiscal year, YYYY-MM-DD. Example: \"2026-04-01\""},"fiscalYearEndDate":{"type":"string","description":"Last day of the fiscal year, YYYY-MM-DD. Example: \"2027-03-31\""}}},"meta":{"type":"object","description":"Metadata about how this result was computed.","properties":{"computedAt":{"type":"string","description":"ISO 8601 timestamp of when this result was computed. Example: \"2026-08-08T12:00:00.000Z\""}}}}},"examples":{"AprilStartFiscalYear":{"summary":"15 October 2026 in a fiscal year starting April","value":{"result":{"fiscalYearLabel":"FY2027","quarter":"Q3","fiscalMonth":7,"fiscalWeek":29,"daysRemainingInFiscalYear":167,"fiscalYearStartDate":"2026-04-01","fiscalYearEndDate":"2027-03-31"},"meta":{"computedAt":"2026-08-08T12:00:00.000Z"}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/validate/email":{"get":{"summary":"Validate an email address: RFC 5322 syntax check plus a live MX record lookup.","tags":["Developer Tools"],"description":"Validate an email address: RFC 5322 syntax check plus a live MX record lookup. Use this when a user wants to check if an email address is well-formed and can actually receive mail, or wants a typo suggestion. Returns validity, MX check result, and common-typo domain suggestions (e.g. gmial.com -> gmail.com). Example: \"Is jane@gmial.com a valid email address?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"email","required":true,"description":"The email address to validate. Example: \"jane@gmial.com\""}],"responses":{"200":{"description":"The email address's syntax and deliverability validity.","content":{"application/json":{"schema":{"type":"object","description":"The email address's syntax and deliverability validity.","properties":{"valid":{"type":"boolean","description":"Whether the address is both syntactically valid and has a mail exchanger."},"syntaxValid":{"type":"boolean","description":"Whether the address is RFC 5322 syntactically valid."},"mxValid":{"type":"boolean","description":"Whether the domain has at least one MX record."},"domain":{"type":["null","string"],"description":"The address's domain part, or null if syntax is invalid. Example: \"gmial.com\""},"suggestedFix":{"type":["null","string"],"description":"A corrected full address if the domain matches a known common typo, otherwise null. Example: \"jane@gmail.com\""}}},"examples":{"TypoDomain":{"summary":"Email with a common typo domain (gmial.com)","value":{"valid":false,"syntaxValid":true,"mxValid":false,"domain":"gmial.com","suggestedFix":"jane@gmail.com"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/validate/phone":{"get":{"summary":"Validate a phone number and return its E.164 form, country, calling code, and type.","tags":["Developer Tools"],"description":"Validate a phone number and return its E.164 form, country, calling code, and type. Use this when a user wants to check if a phone number is valid and get it in a standard format, or find out what kind of number it is (mobile, fixed line, toll-free, or premium rate). Example: \"Validate +44 7911 123456 and return its E.164 format.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"number","required":true,"description":"The phone number to validate, with or without a country code. Example: \"+44 7911 123456\""},{"schema":{"type":"string"},"in":"query","name":"country","required":false,"description":"ISO 3166-1 alpha-3 country code to assume when the number has no explicit country code. Example: \"GBR\""}],"responses":{"200":{"description":"The phone number's validity, standardised formats, and type.","content":{"application/json":{"schema":{"type":"object","description":"The phone number's validity, standardised formats, and type.","properties":{"valid":{"type":"boolean","description":"Whether the number is a valid, dialable phone number."},"e164":{"type":["null","string"],"description":"The number in E.164 format, or null if invalid. Example: \"+447911123456\""},"country":{"type":["null","string"],"description":"ISO 3166-1 alpha-3 country the number is registered to. Example: \"GGY\""},"countryCallingCode":{"type":["null","string"],"description":"The country calling code. Example: \"44\""},"type":{"type":"string","enum":["mobile","fixed_line","toll_free","premium_rate","unknown"],"description":"Simplified number type category."},"formattedNational":{"type":["null","string"],"description":"The number formatted for national dialling. Example: \"07911 123456\""},"formattedInternational":{"type":["null","string"],"description":"The number formatted for international dialling. Example: \"+44 7911 123456\""}}},"examples":{"UkMobile":{"summary":"Validate a UK mobile number","value":{"valid":true,"e164":"+447911123456","country":"GGY","countryCallingCode":"44","type":"mobile","formattedNational":"07911 123456","formattedInternational":"+44 7911 123456"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/validate/vat":{"get":{"summary":"Validate an EU VAT number against the official VIES registry.","tags":["Developer Tools"],"description":"Validate an EU VAT number against the official VIES registry. Format is checked locally against per-country rules before calling VIES. Pass the VAT number with its country prefix (e.g. DE811569869) or supply the prefix separately via the country parameter. Returns validity, company name and address when VIES responds, and a formatValid flag indicating structural correctness regardless of VIES availability.","parameters":[{"schema":{"type":"string"},"in":"query","name":"vat","required":true,"description":"The VAT number. Include the 2-letter VIES country prefix (e.g. \"DE811569869\") or omit it and supply the country parameter separately."},{"schema":{"type":"string"},"in":"query","name":"country","required":false,"description":"Optional. The 2-letter VIES country code (e.g. \"DE\"). Use this when passing the VAT number without its country prefix, or to explicitly specify the country. If the vat value already starts with this code, the prefix is stripped automatically."}],"responses":{"200":{"description":"The VAT number's validity per the official VIES registry, and company details where the member state shares them.","content":{"application/json":{"schema":{"type":"object","description":"The VAT number's validity per the official VIES registry, and company details where the member state shares them.","properties":{"valid":{"type":"boolean","description":"Whether VIES confirms this is a registered VAT number. false when VIES is unreachable — check formatValid and error to distinguish registry-invalid from service unavailability."},"formatValid":{"type":"boolean","description":"Whether the VAT number is structurally valid per the VIES per-country format rules. true even when VIES is unreachable. false only when error is invalid_format."},"countryCode":{"type":["null","string"],"description":"The 2-letter VIES country code (e.g. \"DE\"; \"EL\" for Greece; \"XI\" for Northern Ireland)."},"vatNumber":{"type":["null","string"],"description":"The VAT number without its country prefix."},"companyName":{"type":["null","string"],"description":"Registered company name, when the member state shares it via VIES. Some states (e.g. Germany) always return \"---\"."},"companyAddress":{"type":["null","string"],"description":"Registered company address, when the member state shares it via VIES."},"error":{"type":"string","enum":["invalid_format","service_unavailable"],"description":"Present only on failure. invalid_format: number does not match the expected per-country VIES format. service_unavailable: format is valid but VIES could not be reached — treat the response as non-authoritative."}}},"examples":{"WithPrefix":{"summary":"VAT number with country prefix (VIES live)","value":{"valid":true,"formatValid":true,"countryCode":"DE","vatNumber":"811569869","companyName":"---","companyAddress":"---"}},"WithCountryParam":{"summary":"VAT number without prefix, country supplied separately","value":{"valid":true,"formatValid":true,"countryCode":"DE","vatNumber":"811569869","companyName":"---","companyAddress":"---"}},"ViesUnavailable":{"summary":"VIES unreachable — non-authoritative format-only response","value":{"valid":false,"formatValid":true,"countryCode":"DE","vatNumber":"811569869","companyName":null,"companyAddress":null,"error":"service_unavailable"}},"InvalidFormat":{"summary":"Malformed VAT number — fails per-country format check","value":{"valid":false,"formatValid":false,"countryCode":null,"vatNumber":null,"companyName":null,"companyAddress":null,"error":"invalid_format"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/validate/iban":{"get":{"summary":"Validate an IBAN via the MOD-97 checksum, and decompose it into country, bank code, and account number where the country format is known.","tags":["Developer Tools"],"description":"Validate an IBAN via the MOD-97 checksum, and decompose it into country, bank code, and account number where the country format is known. Use this when a user wants to check if a bank account IBAN is valid before using it for a payment. Example: \"Is DE89370400440532013000 a valid IBAN?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"iban","required":true,"description":"The IBAN to validate, with or without spaces. Example: \"DE89370400440532013000\""}],"responses":{"200":{"description":"The IBAN's validity and, where the country format is known, its decomposed parts.","content":{"application/json":{"schema":{"type":"object","description":"The IBAN's validity and, where the country format is known, its decomposed parts.","properties":{"valid":{"type":"boolean","description":"Whether the IBAN passes the MOD-97 checksum."},"country":{"type":["null","string"],"description":"ISO 3166-1 alpha-3 country code. Example: \"DEU\""},"countryName":{"type":["null","string"],"description":"Full country name. Example: \"Germany\""},"bankCode":{"type":["null","string"],"description":"Bank identifier, only decoded for countries with a known format."},"accountNumber":{"type":["null","string"],"description":"Account number, only decoded for countries with a known format."},"checkDigits":{"type":["null","string"],"description":"The 2-digit IBAN check digits."},"formatted":{"type":["null","string"],"description":"The IBAN grouped in blocks of 4. Example: \"DE89 3704 0044 0532 0130 00\""},"bban":{"type":["null","string"],"description":"The Basic Bank Account Number (IBAN minus country code and check digits)."},"caveat":{"type":"string","description":"Note on decomposition coverage across countries."}}},"examples":{"GermanIban":{"summary":"Validate a German IBAN","value":{"valid":true,"country":"DEU","countryName":"Germany","bankCode":"37040044","accountNumber":"0532013000","checkDigits":"89","formatted":"DE89 3704 0044 0532 0130 00","bban":"370400440532013000","caveat":"Bank code / account number decomposition is only implemented for a subset of countries; the full BBAN is always returned regardless."}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/jwt-decode":{"post":{"summary":"Decode a JWT token — header, payload, expiry, and claims.","tags":["Developer Tools"],"description":"Decode a JWT token — header, payload, expiry, and claims. Use when a user wants to inspect the contents of a JWT without verifying its signature. Returns the decoded header and payload as objects, plus convenience fields for algorithm, expiry status, and key timestamps. No signature verification is performed. Example: \"What claims are in this JWT token?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The JWT token string (three base64url-encoded parts separated by dots). Example: \"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyXzEyMyJ9.sig\""},"secret":{"type":"string","description":"Optional. For HMAC algorithms (HS256/384/512): the signing secret. For RSA/EC algorithms (RS256, ES256, etc.): the PEM-encoded public key. If provided, the signature is verified and signatureVerified is set to true or false."}}}}}},"responses":{"200":{"description":"Decoded JWT header, payload, and convenience metadata.","content":{"application/json":{"schema":{"type":"object","description":"Decoded JWT header, payload, and convenience metadata.","properties":{"header":{"type":"object","additionalProperties":true,"description":"Decoded JWT header — algorithm, type, and any custom fields."},"payload":{"type":"object","additionalProperties":true,"description":"Decoded JWT payload — all registered and custom claims."},"algorithm":{"type":["null","string"],"description":"Signing algorithm from the header (e.g. \"HS256\"). Example: \"HS256\""},"isExpired":{"type":["null","boolean"],"description":"Whether the token has expired based on the exp claim. Null if no exp claim present."},"expiresAt":{"type":["null","string"],"description":"ISO 8601 expiry timestamp, or null if no exp claim. Example: \"2026-12-31T23:59:59.000Z\""},"issuedAt":{"type":["null","string"],"description":"ISO 8601 issued-at timestamp, or null if no iat claim."},"notBefore":{"type":["null","string"],"description":"ISO 8601 not-before timestamp, or null if no nbf claim."},"signatureVerified":{"type":["null","boolean"],"description":"Whether the signature was verified. Null if no secret was provided. True if valid, false if invalid."}}},"examples":{"TypicalJwt":{"summary":"Decode a typical HS256 JWT","value":{"header":{"alg":"HS256","typ":"JWT"},"payload":{"sub":"user_123","iat":1700000000,"exp":1700086400},"algorithm":"HS256","isExpired":true,"expiresAt":"2023-11-15T13:46:40.000Z","issuedAt":"2023-11-14T13:46:40.000Z","notBefore":null,"signatureVerified":null}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/cron-parser":{"get":{"summary":"Parse a cron expression — plain-English description and next run times.","tags":["Developer Tools"],"description":"Parse a cron expression — plain-English description and next run times. Use when a user wants to know what a cron schedule means or when it will next fire. Supports standard 5-field cron (minute hour day month weekday) and optional 6-field with seconds. Returns a human-readable description and the next N scheduled timestamps. Example: \"What does the cron expression '0 9 * * 1-5' mean and when will it next run?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"expression","required":true,"description":"Standard 5-field cron expression (minute hour day month weekday) or 6-field with leading seconds field. Example: \"0 9 * * 1-5\""},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name for next run times. Defaults to UTC. Example: \"Europe/London\""},{"schema":{"type":"string"},"in":"query","name":"count","required":false,"description":"Number of next run times to return (1–20). Defaults to 5. Example: \"5\""}],"responses":{"200":{"description":"Parsed cron expression with human-readable description and next run times.","content":{"application/json":{"schema":{"type":"object","description":"Parsed cron expression with human-readable description and next run times.","properties":{"expression":{"type":"string","description":"The cron expression as provided. Example: \"0 9 * * 1-5\""},"description":{"type":"string","description":"Plain-English description of the schedule. Example: \"At 09:00 AM, Monday through Friday\""},"timezone":{"type":"string","description":"Timezone used for next run times. Example: \"UTC\""},"nextRuns":{"type":"array","items":{"type":"string"},"description":"ISO 8601 timestamps of the next scheduled runs. Example: [\"2026-08-11T09:00:00.000Z\"]"}}},"examples":{"WeekdayMorning":{"summary":"Weekday 9am schedule","value":{"expression":"0 9 * * 1-5","description":"At 09:00 AM, Monday through Friday","timezone":"UTC","nextRuns":["2026-08-10T09:00:00.000Z","2026-08-11T09:00:00.000Z","2026-08-12T09:00:00.000Z","2026-08-13T09:00:00.000Z","2026-08-14T09:00:00.000Z"]}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/base64":{"post":{"summary":"Base64 encode or decode a string.","tags":["Developer Tools"],"description":"Base64 encode or decode a string. Use when a user needs to convert between plain text and Base64 representation — common in API authentication headers, email attachments, and data transfer. Specify mode as \"encode\" or \"decode\". Example: \"Base64-encode the string 'Hello, World!'\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input","mode"],"properties":{"input":{"type":"string","description":"The string to encode or decode. Example: \"Hello, World!\""},"mode":{"type":"string","enum":["encode","decode"],"description":"Whether to encode (plain text → Base64) or decode (Base64 → plain text). Example: \"encode\""}}}}}},"responses":{"200":{"description":"Base64 encode or decode result.","content":{"application/json":{"schema":{"type":"object","description":"Base64 encode or decode result.","properties":{"output":{"type":"string","description":"The encoded or decoded string. Example: \"SGVsbG8sIFdvcmxkIQ==\""},"mode":{"type":"string","description":"The mode used: \"encode\" or \"decode\"."},"inputLength":{"type":"number","description":"Character length of the input string. Example: 13"},"outputLength":{"type":"number","description":"Character length of the output string. Example: 20"}}},"examples":{"EncodeHello":{"summary":"Encode \"Hello, World!\"","value":{"output":"SGVsbG8sIFdvcmxkIQ==","mode":"encode","inputLength":13,"outputLength":20}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/hash":{"post":{"summary":"Generate a cryptographic hash (MD5, SHA-1, SHA-256, SHA-512).","tags":["Developer Tools"],"description":"Generate a cryptographic hash digest of any string. Use when a user needs to hash a value for data integrity checking, webhook signature verification, or password hashing research. Supports MD5, SHA-1, SHA-256, and SHA-512. Example: \"Generate the SHA-256 hash of 'Hello, World!'\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input","algorithm"],"properties":{"input":{"type":"string","description":"The string to hash. Example: \"Hello, World!\""},"algorithm":{"type":"string","enum":["md5","sha1","sha256","sha512"],"description":"Hash algorithm to use. Example: \"sha256\""}}}}}},"responses":{"200":{"description":"Hash digest result.","content":{"application/json":{"schema":{"type":"object","description":"Hash digest result.","properties":{"hash":{"type":"string","description":"Hex-encoded hash digest. Example: \"dffd6021bb2bd5b0af676290809ec3a5...\""},"algorithm":{"type":"string","description":"Algorithm used. Example: \"sha256\""},"inputLength":{"type":"number","description":"Character length of the input. Example: 13"},"hashLength":{"type":"number","description":"Character length of the hex hash string. Example: 64"}}},"examples":{"Sha256Hello":{"summary":"SHA-256 of \"Hello, World!\"","value":{"hash":"dffd6021bb2bd5b0af676290809ec3a53100d31ec1cfd55ba7961111d68f1d4","algorithm":"sha256","inputLength":13,"hashLength":64}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/dns/lookup":{"get":{"summary":"Look up DNS records for a domain — A, AAAA, MX, TXT, CNAME, NS, or SOA.","tags":["Developer Tools"],"description":"Look up DNS records for a domain — A, AAAA, MX, TXT, CNAME, NS, or SOA. Use this when a user wants to check a domain's mail servers, IP addresses, or DNS configuration. Returns the matching DNS records. Example: \"What are the MX records for gmail.com?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"domain","required":true,"description":"The domain name to look up. Example: \"gmail.com\""},{"schema":{"type":"string","enum":["A","AAAA","MX","TXT","CNAME","NS","SOA"]},"in":"query","name":"type","required":false,"description":"The DNS record type to query. Defaults to A. Example: \"MX\""}],"responses":{"200":{"description":"The matching DNS records for the queried domain and type.","content":{"application/json":{"schema":{"type":"object","description":"The matching DNS records for the queried domain and type.","properties":{"domain":{"type":"string","description":"The domain that was queried. Example: \"gmail.com\""},"type":{"type":"string","description":"The DNS record type that was queried. Example: \"MX\""},"records":{"type":"array","description":"The matching records. Shape varies by record type: A/AAAA/CNAME/NS return plain strings, MX returns {exchange, priority} objects, TXT returns strings (chunks joined), SOA returns a single detailed object as the only array element.","items":{}},"ttl":{"type":["null","number"],"description":"Time-to-live in seconds, only populated for A/AAAA/SOA lookups — null otherwise."}}},"examples":{"GmailMxRecords":{"summary":"MX records for gmail.com","value":{"domain":"gmail.com","type":"MX","records":[{"exchange":"gmail-smtp-in.l.google.com","priority":5},{"exchange":"alt1.gmail-smtp-in.l.google.com","priority":10},{"exchange":"alt2.gmail-smtp-in.l.google.com","priority":20},{"exchange":"alt3.gmail-smtp-in.l.google.com","priority":30},{"exchange":"alt4.gmail-smtp-in.l.google.com","priority":40}],"ttl":null}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/domain/ssl":{"get":{"summary":"Check a domain's SSL/TLS certificate.","tags":["Developer Tools"],"description":"Check a domain's SSL/TLS certificate. Use this when a user wants to know when a certificate expires, who issued it, or whether it's self-signed — useful for monitoring or due diligence. Returns issuer, subject, expiry date, days remaining, and whether it's self-signed. Example: \"When does the SSL certificate for example.com expire?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"domain","required":true,"description":"The domain name to check, without https:// or a path. Example: \"example.com\""}],"responses":{"200":{"description":"The domain's SSL/TLS certificate details.","content":{"application/json":{"schema":{"type":"object","description":"The domain's SSL/TLS certificate details.","properties":{"valid":{"type":"boolean","description":"Whether a certificate was successfully retrieved and is not expired."},"issuer":{"type":["null","string"],"description":"The certificate's issuing CA. Example: \"Cloudflare TLS Issuing ECC CA 3\""},"subject":{"type":["null","string"],"description":"The certificate's subject (usually the domain or a wildcard). Example: \"example.com\""},"validFrom":{"type":["null","string"],"description":"ISO 8601 timestamp the certificate becomes valid."},"validTo":{"type":["null","string"],"description":"ISO 8601 timestamp the certificate expires."},"daysRemaining":{"type":["null","number"],"description":"Days until expiry, negative if already expired."},"expired":{"type":"boolean","description":"Whether the certificate has already expired."},"selfSigned":{"type":"boolean","description":"Whether the certificate is self-signed."},"error":{"type":"string","enum":["timeout","connection_failed","no_certificate"],"description":"Present only when the check failed — omitted on success."}}},"examples":{"ExampleCom":{"summary":"SSL certificate check for example.com","value":{"valid":true,"issuer":"Cloudflare TLS Issuing ECC CA 3","subject":"example.com","validFrom":"2026-07-29T22:10:08.000Z","validTo":"2026-10-27T22:17:21.000Z","daysRemaining":80,"expired":false,"selfSigned":false}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/domain/age":{"get":{"summary":"Look up a domain's registration date, age, registrar, and status via RDAP (the modern successor to WHOIS).","tags":["Developer Tools"],"description":"Look up a domain's registration date, age, registrar, and status via RDAP (the modern successor to WHOIS). Use this when a user wants to know how old a domain is or who registered it — useful for due diligence on a website or business. Returns registration date, age, registrar, and status. Example: \"How old is the domain wikipedia.org?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"domain","required":true,"description":"The domain name to look up. Example: \"wikipedia.org\""}],"responses":{"200":{"description":"The domain's registration details from RDAP.","content":{"application/json":{"schema":{"type":"object","description":"The domain's registration details from RDAP.","properties":{"domain":{"type":"string","description":"The domain that was looked up. Example: \"wikipedia.org\""},"registeredDate":{"type":["null","string"],"description":"ISO 8601 date the domain was first registered, or null if unavailable."},"updatedDate":{"type":["null","string"],"description":"ISO 8601 date of the most recent registration record update, or null if unavailable."},"expiresDate":{"type":["null","string"],"description":"ISO 8601 date the current registration expires, or null if unavailable."},"ageDays":{"type":["null","number"],"description":"Days since registration, or null if the registration date is unavailable."},"registrar":{"type":["null","string"],"description":"The domain's registrar. Example: \"MarkMonitor Inc.\""},"status":{"type":"array","items":{"type":"string"},"description":"EPP domain status codes. Example: [\"client transfer prohibited\"]"},"error":{"type":"string","enum":["not_found","service_unavailable"],"description":"Present only when the lookup failed — omitted on success."}}},"examples":{"Wikipedia":{"summary":"Domain age lookup for wikipedia.org","value":{"domain":"wikipedia.org","registeredDate":"2001-01-13T00:12:14.754Z","updatedDate":"2025-12-17T09:26:13.643Z","expiresDate":"2027-01-13T00:12:14Z","ageDays":9338,"registrar":"MarkMonitor Inc.","status":["client delete prohibited","client transfer prohibited","client update prohibited"]}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ip/geo":{"get":{"summary":"Look up an IP address's country, region, city, coordinates, and timezone.","tags":["Developer Tools"],"description":"Look up an IP address's country, region, city, coordinates, and timezone. Use this when a user wants to know roughly where an IP address is located. Returns a database_not_configured error if the server's MaxMind database isn't set up yet. Example: \"Where is the IP address 8.8.8.8 located?\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"ip","required":true,"description":"The IPv4 or IPv6 address to look up. Example: \"8.8.8.8\""}],"responses":{"200":{"description":"The IP address's approximate geographic location.","content":{"application/json":{"schema":{"type":"object","description":"The IP address's approximate geographic location.","properties":{"ip":{"type":"string","description":"The IP address that was looked up. Example: \"8.8.8.8\""},"country":{"type":["null","string"],"description":"ISO 3166-1 alpha-3 country code. Example: \"USA\""},"countryName":{"type":["null","string"],"description":"Full country name. Example: \"United States\""},"region":{"type":["null","string"],"description":"Region or state name. Example: \"California\""},"city":{"type":["null","string"],"description":"City name. Example: \"Mountain View\""},"latitude":{"type":["null","number"],"description":"Approximate latitude."},"longitude":{"type":["null","number"],"description":"Approximate longitude."},"timezone":{"type":["null","string"],"description":"IANA timezone name. Example: \"America/Los_Angeles\""},"isp":{"type":["null","string"],"description":"Internet service provider, if known."},"organisation":{"type":["null","string"],"description":"Organisation associated with the IP block, if known."},"error":{"type":"string","enum":["database_not_configured","not_found"],"description":"Present only when the lookup failed — omitted on success."}}},"examples":{"GooglePublicDns":{"summary":"Geolocation for Google Public DNS (8.8.8.8)","value":{"ip":"8.8.8.8","country":"USA","countryName":"United States","region":"California","city":"Mountain View","latitude":37.4056,"longitude":-122.0775,"timezone":"America/Los_Angeles","isp":"Google LLC","organisation":"Google Public DNS"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ip/reputation":{"get":{"summary":"Check an IP address reputation (currently disabled)","tags":["Developer Tools"],"description":"IP reputation lookup. Currently disabled — always returns a 503 \"unavailable\" response rather than partial or misleading data, since this deployment has no reputation data source configured.","parameters":[{"schema":{"type":"string"},"in":"query","name":"ip","required":true,"description":"The IPv4 or IPv6 address to check. Example: \"8.8.8.8\""}],"responses":{"200":{"description":"This endpoint is currently disabled and never actually returns 200 — every request receives a 503 with the shape shown below instead. Documented here (rather than left untyped) so integrations checking against this contract see a stable, honest shape if the service is ever re-enabled.","content":{"application/json":{"schema":{"type":"object","description":"This endpoint is currently disabled and never actually returns 200 — every request receives a 503 with the shape shown below instead. Documented here (rather than left untyped) so integrations checking against this contract see a stable, honest shape if the service is ever re-enabled.","properties":{"status":{"type":"string","enum":["unavailable"],"description":"Always \"unavailable\" while this service has no reputation data source configured."},"message":{"type":"string","description":"Human-readable explanation."}}},"examples":{"ServiceDisabled":{"summary":"The only response this endpoint currently produces (served as HTTP 503, not 200)","value":{"status":"unavailable","message":"IP reputation service is not currently enabled"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/ip/validate":{"get":{"summary":"Validate an IP address format","tags":["Developer Tools"],"description":"Validates whether a string is a well-formed IPv4 or IPv6 address, and classifies its type. Use this when a user wants to check if an IP address string is valid before using it elsewhere. Returns validity, IP version, and address type (e.g. public, private, loopback).","parameters":[{"schema":{"type":"string"},"in":"query","name":"ip","required":true,"description":"The IPv4 or IPv6 address to validate. Example: \"192.168.1.1\""}],"responses":{"200":{"description":"The IP address's validity, version, and classification.","content":{"application/json":{"schema":{"type":"object","description":"The IP address's validity, version, and classification.","properties":{"valid":{"type":"boolean","description":"Whether the string is a well-formed IPv4 or IPv6 address."},"version":{"type":["null","number"],"enum":[4,6,null],"description":"IP version, or null if invalid."},"type":{"type":["null","string"],"description":"Address classification, e.g. \"public\", \"private\", \"loopback\", \"link-local\", \"multicast\". Null if invalid."},"cidrClass":{"type":["null","string"],"description":"Legacy IPv4 class (A/B/C/D/E) — IPv4 only, null for IPv6 or invalid input."},"compressed":{"type":["null","string"],"description":"The address in its canonical/compressed form. Example: \"192.168.1.1\""}}},"examples":{"PrivateIPv4":{"summary":"Validate a private IPv4 address","value":{"valid":true,"version":4,"type":"private","cidrClass":"C","compressed":"192.168.1.1"}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/running-pace":{"get":{"summary":"Calculate running pace, finish time, km splits, and training zone paces for any race distance.","tags":["Health"],"description":"Calculate running pace, finish time, km splits, and training zone paces for any race distance. Given a goal finish time, returns pace per km/mile. Given a target pace, returns projected finish time. Example: \"What pace do I need for a sub-4-hour marathon?\"","parameters":[{"schema":{"type":"string","enum":["time-to-pace","pace-to-time"]},"in":"query","name":"mode","required":true,"description":"Whether to derive pace from a goal time, or finish time from a target pace."},{"schema":{"type":"string"},"in":"query","name":"distanceKm","required":true,"description":"Race distance in kilometres. Example: \"42.195\""},{"schema":{"type":"string"},"in":"query","name":"goalTimeSeconds","required":false,"description":"Total goal finish time in seconds. Required when mode is \"time-to-pace\". Example: \"14400\""},{"schema":{"type":"string"},"in":"query","name":"targetPaceSecondsPerKm","required":false,"description":"Target pace in seconds per km. Required when mode is \"pace-to-time\". Example: \"300\""},{"schema":{"type":"string","enum":["km","mi"]},"in":"query","name":"units","required":false,"description":"Display units for pace. Defaults to \"km\"."}],"responses":{"200":{"description":"Pace, finish time, per-km splits, and training zone paces.","content":{"application/json":{"schema":{"type":"object","description":"Pace, finish time, per-km splits, and training zone paces.","properties":{"result":{"type":"object","properties":{"pacePerKmSeconds":{"type":"number"},"pacePerMileSeconds":{"type":"number"},"finishTimeSeconds":{"type":"number"},"distanceKm":{"type":"number"},"splits":{"type":"array","items":{"type":"object","properties":{"km":{"type":"number"},"splitTimeSeconds":{"type":"number"},"cumulativeTimeSeconds":{"type":"number"}}}},"trainingPaces":{"type":"object","properties":{"easy":{"type":"number"},"aerobic":{"type":"number"},"threshold":{"type":"number"},"interval":{"type":"number"}}},"units":{"type":"string","enum":["km","mi"]}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string"}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/home-renovation":{"get":{"summary":"Estimate home renovation cost range by room type, finish level, and region.","tags":["Finance"],"description":"Estimate home renovation cost range by room type (kitchen, bathroom, bedroom, living-room, loft-conversion, extension), finish level (budget, mid, premium), and region (uk, us). Returns a low/high cost range, materials/labour breakdown, typical resale ROI, and caveats. Example: \"How much does a mid-range kitchen renovation cost in the US?\"","parameters":[{"schema":{"type":"string","enum":["kitchen","bathroom","bedroom","living-room","loft-conversion","extension"]},"in":"query","name":"roomType","required":true,"description":"The room or project type."},{"schema":{"type":"string","enum":["budget","mid","premium"]},"in":"query","name":"finishLevel","required":true,"description":"The finish quality tier."},{"schema":{"type":"string","enum":["uk","us"]},"in":"query","name":"region","required":true,"description":"Region for cost basis and currency. Example: \"uk\""},{"schema":{"type":"string"},"in":"query","name":"roomSizeM2","required":false,"description":"Optional room size in square metres. Uses a typical size for the room type if omitted."}],"responses":{"200":{"description":"Renovation cost range, materials/labour breakdown, and typical resale ROI.","content":{"application/json":{"schema":{"type":"object","description":"Renovation cost range, materials/labour breakdown, and typical resale ROI.","properties":{"result":{"type":"object","properties":{"roomType":{"type":"string"},"finishLevel":{"type":"string"},"region":{"type":"string"},"roomSizeM2":{"type":"number"},"currency":{"type":"string","enum":["GBP","USD"]},"lowEstimate":{"type":"number"},"highEstimate":{"type":"number"},"midEstimate":{"type":"number"},"breakdown":{"type":"object","properties":{"materials":{"type":"object","properties":{"low":{"type":"number"},"high":{"type":"number"}}},"labour":{"type":"object","properties":{"low":{"type":"number"},"high":{"type":"number"}}}}},"roiPercent":{"type":"object","properties":{"low":{"type":"number"},"high":{"type":"number"}}},"notes":{"type":"array","items":{"type":"string"}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string"}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/readability":{"post":{"summary":"Score any text for readability using Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI, and more.","tags":["Developer Tools"],"description":"Score any text for readability using Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog, SMOG, Coleman-Liau, and ARI. Returns text statistics, all six scores, a consensus grade level, and a plain-language label. Example: \"What grade level is this paragraph written at?\"","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","description":"The text to analyse. Any length."}}}}}},"responses":{"200":{"description":"Text statistics and six readability scores, with a consensus grade level and label.","content":{"application/json":{"schema":{"type":"object","description":"Text statistics and six readability scores, with a consensus grade level and label.","properties":{"result":{"type":"object","properties":{"wordCount":{"type":"number"},"sentenceCount":{"type":"number"},"syllableCount":{"type":"number"},"complexWordCount":{"type":"number"},"characterCount":{"type":"number"},"avgWordsPerSentence":{"type":"number"},"avgSyllablesPerWord":{"type":"number"},"fleschReadingEase":{"type":"number"},"fleschKincaidGrade":{"type":"number"},"gunningFog":{"type":"number"},"smog":{"type":"number"},"colemanLiau":{"type":"number"},"ari":{"type":"number"},"averageGradeLevel":{"type":"number"},"readabilityLabel":{"type":"string"},"targetAudience":{"type":"string"},"smogReliable":{"type":"boolean"}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string"}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/pet-age":{"get":{"summary":"Convert a dog or cat's age to human-equivalent years using AAFP/AAHA life-stage guidelines.","tags":["Health"],"description":"Convert a dog or cat's age to human-equivalent years using AAFP/AAHA life-stage guidelines. Dogs use size-adjusted conversion tables. Returns human-equivalent age, life stage, typical lifespan, and age-appropriate health notes. Example: \"How old is my 5-year-old medium dog in human years?\"","parameters":[{"schema":{"type":"string","enum":["dog","cat"]},"in":"query","name":"petType","required":true,"description":"The type of pet."},{"schema":{"type":"string","enum":["small","medium","large","giant"]},"in":"query","name":"dogSize","required":false,"description":"Required when petType is \"dog\". small: <10kg, medium: 10-25kg, large: 25-45kg, giant: >45kg."},{"schema":{"type":"string"},"in":"query","name":"ageYears","required":true,"description":"Whole years of age, 0-25. Example: \"5\""},{"schema":{"type":"string"},"in":"query","name":"ageMonths","required":false,"description":"Additional months of age, 0-11. Defaults to 0."}],"responses":{"200":{"description":"Human-equivalent age, life stage, typical lifespan, and health notes.","content":{"application/json":{"schema":{"type":"object","description":"Human-equivalent age, life stage, typical lifespan, and health notes.","properties":{"result":{"type":"object","properties":{"petType":{"type":"string","enum":["dog","cat"]},"dogSize":{"type":"string","enum":["small","medium","large","giant"]},"petAgeYears":{"type":"number"},"humanAge":{"type":"number"},"lifeStage":{"type":"string"},"lifeStageDescription":{"type":"string"},"typicalLifespanYears":{"type":"number"},"percentOfLifespan":{"type":"number"},"nextLifeStageAge":{"type":"number"},"healthNotes":{"type":"array","items":{"type":"string"}}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string"}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/password-generator":{"get":{"summary":"Generate cryptographically secure passwords with configurable length, character sets, and quantity.","tags":["Developer Tools"],"description":"Generate cryptographically secure passwords with configurable length, character sets, and quantity. Returns entropy and a crack-time estimate. Example: \"Generate 3 strong 16-character passwords.\"","parameters":[{"schema":{"type":"string"},"in":"query","name":"length","required":true,"description":"Password length, 8-128. Example: \"16\""},{"schema":{"type":"string"},"in":"query","name":"uppercase","required":false,"description":"Include A-Z. Defaults to \"true\"."},{"schema":{"type":"string"},"in":"query","name":"lowercase","required":false,"description":"Include a-z. Defaults to \"true\"."},{"schema":{"type":"string"},"in":"query","name":"numbers","required":false,"description":"Include 0-9. Defaults to \"true\"."},{"schema":{"type":"string"},"in":"query","name":"symbols","required":false,"description":"Include symbols. Defaults to \"false\"."},{"schema":{"type":"string"},"in":"query","name":"count","required":false,"description":"Number of passwords to generate, 1-10. Defaults to \"1\"."},{"schema":{"type":"string"},"in":"query","name":"excludeAmbiguous","required":false,"description":"Exclude ambiguous characters (0, O, 1, l, I). Defaults to \"false\"."}],"responses":{"200":{"description":"Generated passwords, with entropy and crack-time estimate.","content":{"application/json":{"schema":{"type":"object","description":"Generated passwords, with entropy and crack-time estimate.","properties":{"result":{"type":"object","properties":{"passwords":{"type":"array","items":{"type":"string"}},"length":{"type":"number"},"charsetSize":{"type":"number"},"entropyBits":{"type":"number"},"crackTimeLabel":{"type":"string"},"crackTimeSeconds":{"type":"number"},"strengthLabel":{"type":"string","enum":["Weak","Fair","Strong","Very Strong"]}}},"meta":{"type":"object","properties":{"computedAt":{"type":"string"}}}}}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/solar-yield":{"get":{"summary":"Estimate annual solar PV yield for a location and system.","tags":["Energy"],"description":"Returns annual energy yield (kWh/year), monthly breakdown, in-plane irradiation, specific yield, and performance ratio using EU JRC PVGIS v5.3 radiation data. Results are cached by location and system parameters for 30 days. Azimuth uses compass bearing convention: 0=north, 90=east, 180=south (default), 270=west.","parameters":[{"schema":{"type":"string"},"in":"query","name":"lat","required":true,"description":"Latitude in decimal degrees (-90 to 90)."},{"schema":{"type":"string"},"in":"query","name":"lon","required":true,"description":"Longitude in decimal degrees (-180 to 180)."},{"schema":{"type":"string"},"in":"query","name":"peakpower","required":true,"description":"System nominal power in kWp (e.g. 5)."},{"schema":{"type":"string"},"in":"query","name":"angle","required":false,"description":"Panel tilt from horizontal in degrees (0–90, default 35)."},{"schema":{"type":"string"},"in":"query","name":"azimuth","required":false,"description":"Panel azimuth as compass bearing (0=N, 90=E, 180=S, 270=W; default 180)."},{"schema":{"type":"string"},"in":"query","name":"loss","required":false,"description":"System losses in percent (default 14)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/benchmark-rates":{"get":{"summary":"Compute a compounded or simple average of SOFR, €STR, or SONIA for a date range.","tags":["Business Finance"],"description":"Returns the compounded or simple average of the requested overnight benchmark rate (SOFR for USD, €STR for EUR, SONIA for GBP) over the specified period. Compounding follows the ISDA/ARRC standard: each overnight rate applies for its actual number of calendar days (1 on weekdays, 3 on Fridays). Day count: ACT/360 for SOFR and €STR; ACT/365 for SONIA. If startDate/endDate are omitted, returns the 30 most recent daily rates.","parameters":[{"schema":{"type":"string","enum":["USD","EUR","GBP"]},"in":"query","name":"currency","required":true,"description":"USD=SOFR, EUR=€STR, GBP=SONIA"},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false,"description":"Period start in YYYY-MM-DD (inclusive)."},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false,"description":"Period end in YYYY-MM-DD (inclusive)."},{"schema":{"type":"string","enum":["compounded","simple","spot"]},"in":"query","name":"method","required":false,"description":"Averaging method (default: compounded)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/take-home-pay":{"get":{"summary":"Calculate net (take-home) pay after US federal or UK income tax and deductions.","tags":["Finance"],"description":"Calculates take-home pay from an annual gross salary. For the US, applies federal income tax (after the standard deduction), Social Security (6.2% up to the wage base), and Medicare (1.45% plus a 0.9% surtax above the threshold) — US state/local tax is not included. For the UK, applies income tax (with Personal Allowance taper above £100,000) and Class 1 employee National Insurance for England, Wales, and Northern Ireland — Scotland uses different bands and is not covered. Always uses the latest tax year available in the dataset.","parameters":[{"schema":{"type":"string","enum":["us","uk"]},"in":"query","name":"country","required":true,"description":"Tax jurisdiction."},{"schema":{"type":"string"},"in":"query","name":"gross","required":true,"description":"Annual gross salary. Example: \"75000\""},{"schema":{"type":"string","enum":["single","married_joint"]},"in":"query","name":"filingStatus","required":false,"description":"US filing status (ignored for UK; default \"single\")."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/employer-cost":{"get":{"summary":"Calculate an employer's true cost of a salary, including employer social security contributions, for any OECD country.","tags":["Business Finance"],"description":"Returns the employer social security contribution (SSC) amount, total employer cost, and effective on-cost rate for a gross annual salary in any of the 38 OECD member countries, using OECD Taxing Wages employer SSC rates for a single worker at the average wage. Also returns the 5 cheapest and 5 most expensive OECD countries by employer SSC rate for context.","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-2 country code, one of the 38 OECD members. Example: \"GB\""},{"schema":{"type":"string"},"in":"query","name":"gross","required":true,"description":"Annual gross salary in the country's local currency. Example: \"50000\""}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}},"/v1/historical-index-volatility":{"get":{"summary":"VIX historical volatility lookup — percentile rank, regime, and rolling averages.","tags":["Finance"],"description":"Returns the CBOE VIX close for a given trading day (default: most recent), its percentile rank in the full history since January 1990, volatility regime classification (Calm / Normal / Elevated / Stressed / Extreme), 30-day / 90-day / 1-year rolling average VIX, and all-time high / low / mean. Data refreshed daily from CBOE.","parameters":[{"schema":{"type":"string"},"in":"query","name":"date","required":false,"description":"Trading day in ISO 8601 format (YYYY-MM-DD). Defaults to the most recent trading day in the database. Non-trading days (weekends, US market holidays) fall back to the nearest prior trading day — the resolved date is returned as result.date, with result.requestedDate showing what was asked for. Returns 400 only if the date is before the start of the dataset (January 1990)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The request was invalid — a required parameter was missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-0"}}}},"401":{"description":"No valid API key was provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/def-1"}}}}}}}},"servers":[{"url":"https://api.stupidlyclever.com","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Dates & Time","description":"Date arithmetic, business days, public holidays, timezone tools"},{"name":"Finance","description":"Mortgage, investment, tax, and personal finance calculators"},{"name":"Business Finance","description":"Startup, SaaS, and corporate finance tools"},{"name":"Income & Wealth","description":"Salary, income percentile, and wealth comparison"},{"name":"Health & Life","description":"Health metrics, sleep, longevity, and lifestyle calculators"},{"name":"Science & Stats","description":"Statistics, physics, and engineering calculators"},{"name":"Global","description":"Cross-country comparison, currency, electricity, and carbon tools"},{"name":"Composite","description":"Multi-factor analysis combining several data sources"},{"name":"Project Management","description":"EVM, critical path, burn rate, and PERT tools"},{"name":"Developer Tools","description":"Phone, email, IBAN, VAT validation; DNS, IP, SSL lookups"}]}