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 complete successful collection, and if that complete check is stale. Partial updates do not change the complete-check time.

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 in UTC, ISO 8601 format. A partial update keeps the previous timestamp when stored data exists, because some institutions were not checked successfully. For timestamp differences and retained records, read Data Freshness.

All error responses are JSON, also for a path that does not exist. An error response has this shape:

{
  "code": 400,
  "error": "invalid_request",
  "message": "Invalid request parameters",
  "hint": "Make sure that each parameter has the correct name and format. Dates use the YYYY-MM-DD format. For the parameters of each endpoint, refer to https://www.ratesapi.nz/openapi.json.",
  "documentationUrl": "https://www.ratesapi.nz/docs/api-reference#filters"
}

Field	Value
code	The HTTP status code
error	A code for the type of error. This code does not change, so you can use it in your code.
message	A message about the error. The text can change.
hint	Information that tells you how to correct the error
documentationUrl	The documentation page for this type of error

HTTP status	error	Cause	Example message
400	invalid_request	A parameter is not correct. For example, a date is not in YYYY-MM-DD format.	Invalid request parameters
404	institution_not_found or issuer_not_found	The institution or the issuer does not exist.	Institution not found
404	no_data	The API has no snapshot for the dates in the request.	No data available for date: 2020-01-01
404	not_found	No endpoint has this method and path.	No endpoint matches this method and path
500	server_error	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

The health endpoint gives a different error response for monitors: status is error, with message and timestamp.

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.