---
title: "Total monthly cost (PITI) estimate"
method: POST
path: "/v1/monthly-cost"
tags: ["Data & Analytics"]
---

# Total monthly cost (PITI) estimate

`POST /v1/monthly-cost`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/monthly-cost`
- Auth: API key in header `X-API-Key`

Computes the full monthly housing cost: principal + interest plus property tax, homeowners insurance, and PMI/HOA, so affordability reflects real outlay. When no rate is supplied, the current best market rate for the state is resolved via the decision engine. This route is the single source of truth for the PITI math; the MCP `estimate_monthly_cost` tool and the consumer app call it.

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `home_price` number: Purchase price in dollars. Required unless loan_amount is given.
  - `down_payment` number: Cash down payment in dollars. Default 0.
  - `loan_amount` number: Optional explicit loan amount; overrides home_price - down_payment.
  - `rate` number: Annual interest rate (percent). If omitted, best market rate for the state is used.
  - `term_months` integer: Loan term in months. Default 360.
  - `state` string: 2-letter US state code. Default CA.
  - `property_tax_rate` number: Annual property tax as % of home value. Default 1.1.
  - `annual_insurance` number: Homeowners insurance dollars/year. Default max(800, 0.35% of home price).
  - `monthly_hoa` number: HOA dues dollars/month. Default 0.
  - `pmi_rate` number: Annual PMI as % of loan balance. Default 0.5, applied only when LTV > 80%.
  - `credit_score` integer: Optional borrower credit score used for the market-rate lookup.

## Response `200`

Full PITI breakdown.

- object
  - `home_price` string: Purchase price the costs were computed from, formatted as a US dollar string.
  - `loan_amount` string: Loan amount in US dollars.
  - `down_payment` string: Down payment in US dollars.
  - `ltv` string: Loan-to-value ratio, formatted as a percentage string.
  - `rate_used` string: The rate the calculation was run at, as an annual percentage.
  - `rate_source` 'provided' | 'market' | 'fallback': Where the rate used in this calculation came from: `provided` if the caller supplied it, `market` if it was taken from live offers, `fallback` if neither was available and a default was used.
  - `principal_and_interest` string: Monthly principal and interest, formatted as a US dollar string.
  - `monthly_property_tax` string: Monthly property tax, formatted as a US dollar string.
  - `monthly_insurance` string: Monthly homeowners insurance, formatted as a US dollar string.
  - `monthly_pmi` string: Monthly private mortgage insurance, formatted as a US dollar string. Zero when PMI does not apply.
  - `monthly_hoa` string: Monthly homeowners-association dues, formatted as a US dollar string.
  - `total_monthly_payment` string: Everything above added together, formatted as a US dollar string.
  - `pmi_applies` boolean: True when the loan-to-value ratio is high enough to require private mortgage insurance.
  - `annual_total` string: Twelve months of the total payment, formatted as a US dollar string.
  - `breakdown` object: The same components again, as numbers rather than formatted strings.
  - `assumed_defaults` object: Values filled in where the caller supplied none, so the result is reproducible.
  - `next_actions` object[]: Other endpoints or tools that are the natural next step from this result.
  - `disclosures` string[]: Statements that must be shown to a consumer alongside this result.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)