API Reference

Use this section when you know which data you must get. The OpenAPI reference shows the parameters, the response fields, and the errors of each endpoint. If Rates API is new to you, start with the Quickstart. Then read AI Integration and Core Concepts.

Base URL

https://www.ratesapi.nz

For local development, use this URL:

http://localhost:8787

Authentication

An API key is not necessary.

OpenAPI Reference

The OpenAPI reference shows all parameters, response fields, and errors of each endpoint. You can also send requests from it.

Resource	URL
OpenAPI reference (Scalar)	/openapi
OpenAPI JSON	/openapi/json

AI Integration

Resource	URL	Use
MCP endpoint	POST /api/v1/mcp	Find and use tools from an MCP client
OpenAPI JSON	/openapi/json	Make tools and SDKs, and examine the contract
Documentation list for LLMs	/llms.txt	Give an assistant a plain-text list of the documentation pages

For more information about MCP, llms.txt, and agent patterns, read AI Integration.

Endpoint Groups

Each category has three endpoints:

• The list endpoint gives the newest rates of all institutions or issuers.
• The detail endpoint gives the newest rates of one institution or issuer.
• The time-series endpoint gives snapshots of earlier rates.

Category	List Endpoint	Get By ID	Time Series
Mortgage Rates	GET /api/v1/mortgage-rates	GET /api/v1/mortgage-rates/{institutionId}	GET /api/v1/mortgage-rates/time-series
Personal Loan Rates	GET /api/v1/personal-loan-rates	GET /api/v1/personal-loan-rates/{institutionId}	GET /api/v1/personal-loan-rates/time-series
Car Loan Rates	GET /api/v1/car-loan-rates	GET /api/v1/car-loan-rates/{institutionId}	GET /api/v1/car-loan-rates/time-series
Credit Card Rates	GET /api/v1/credit-card-rates	GET /api/v1/credit-card-rates/{issuerId}	GET /api/v1/credit-card-rates/time-series

The health endpoint, GET /api/v1/health, shows if the API can read its database. For each dataset, it also shows the time of the last change, the time of the last successful data collection, and if the data collection stopped.

Filters

Parameter	Endpoints	Result
termInMonths	All mortgage endpoints	Only the fixed rates for this term, for example, 12. The response does not contain variable floating rates.
institutionId	The time series of mortgages, personal loans, and car loans	Only the data of this institution
issuerId	The time series of credit cards	Only the data of this issuer

The data contains mortgage terms of 6, 12, 18, 24, 36, 48, and 60 months. If you send a different term, the products arrays are empty.

An endpoint does not use a filter that it does not accept. For example, the credit card time series does not use institutionId, and it gives the data of all issuers. Make sure that you send the correct filter for each endpoint.

Responses

All successful responses are JSON. Each rate response has a lastUpdated field. This field gives the date and time (UTC, ISO 8601) at which the API collected the data.

An error response has this shape:

{
  "code": 400,
  "message": "Invalid request parameters"
}

HTTP status	Cause	Example message
400	A parameter is not correct. For example, a date is not in YYYY-MM-DD format.	Invalid request parameters
404	The institution, the issuer, or the snapshot does not exist.	Institution not found
500	An error occurred on the server. Send the request again. If the error continues, examine /api/v1/health.	An error occurred while retrieving mortgage rates data

Request IDs

The API adds an x-request-id header to the responses of its endpoints. If you send an x-request-id header, the API returns the same value. If you do not send it, the API makes a new value. Use this value to find a request in the logs.

Some responses do not have this header:

• A response to a path that does not exist
• A 400 response for a parameter of the incorrect type, for example, termInMonths=abc
• The Scalar page at /openapi

Time-Series Rules

Parameter	Description
date	The date of one snapshot, in YYYY-MM-DD format (UTC)
startDate	The first date of a range, in YYYY-MM-DD format (UTC)
endDate	The last date of a range, in YYYY-MM-DD format (UTC). The range contains this date.

Send date, or send startDate and endDate together. Do not send date with startDate or endDate.

If you send no date, the response contains no snapshots. The availableDates field shows the dates that have a snapshot.