Core Concepts

Data Freshness

The API collects data from interest.co.nz each hour. It saves a dataset only when the data changes. Cloudflare D1 keeps the newest version of each dataset and snapshots of earlier versions.

To see the freshness of each dataset, send a request to the health endpoint:

curl https://www.ratesapi.nz/api/v1/health

For each dataset, the health response has these fields:

Field	Value
lastUpdated	The time of the last change to the data.
lastChecked	The time of the last successful data collection, also when the data did not change. The value is null if the time is not known.
stale	true if no data collection was successful in the last 3 hours. false if a data collection was successful in the last 3 hours. null if lastChecked is null.

In the health response, lastUpdated and lastChecked have the format YYYY-MM-DD HH:MM:SS (UTC). In the rate responses, lastUpdated has the ISO 8601 format.

An old lastUpdated value has two possible causes: the rates did not change, or the data collection failed. To find the cause, examine stale. If stale is false, the data collection operates correctly and the rates did not change.

Identifiers

Use the IDs from the list endpoints in detail requests and time-series requests.

Identifier	Endpoints	Example
institutionId	Mortgage, personal loan, and car loan endpoints	institution:anz
issuerId	Credit card endpoints	issuer:amex

The ID of an institution or an issuer does not change when the API collects new data. You can use upper-case or lower-case letters in an ID.

Product names and products can change when an institution changes its rates page. Product IDs and rate IDs identify items in a response. No endpoint uses them as a parameter.

Newest Data and Earlier Data

Data	Endpoint
The newest rates of all institutions or issuers	A list endpoint, for example, /api/v1/mortgage-rates
The newest rates of one institution or issuer	A detail endpoint, for example, /api/v1/mortgage-rates/{institutionId}
One snapshot	A time-series endpoint with date
All snapshots in a range	A time-series endpoint with startDate and endDate
The dates that have a snapshot	A time-series endpoint with no date

The API keeps a maximum of one snapshot for each dataset on each UTC date. If the data changes again on the same date, the new snapshot replaces the earlier snapshot.

A date on which the data did not change has no snapshot. On that date, the rates were the same as in the snapshot before it. Use the availableDates array in each time-series response to find the dates that have data. Some days do not have a snapshot.

Date Filters

Time-series endpoints use calendar dates in YYYY-MM-DD format (UTC).

Use either date or the startDate and endDate pair. Do not send date with startDate or endDate.

Parameters	Result
date only	One snapshot
startDate and endDate	All snapshots in the range. The range contains the two dates.
No date	No snapshots. The availableDates field shows the dates that have a snapshot.
startDate without endDate	Invalid request
endDate without startDate	Invalid request
date with startDate or endDate	Invalid request
startDate after endDate	Invalid request

An invalid request returns HTTP 400:

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

If startDate is after endDate, the message is Start date cannot be after end date.

If the API has no snapshot for the request, it returns HTTP 404. For example, the message can be No data available for date: 2020-01-01.

Request IDs

The API adds an x-request-id header to the responses of its endpoints. If a client sends x-request-id, the API returns the same value. If the client does not send it, the API makes a new value.

A response to a path that does not exist does not have this header. A 400 response for a parameter of the incorrect type also does not have it.

CORS

The /api/v1/* endpoints accept requests from all origins. A preflight response contains access-control-max-age: 600. A browser can keep the preflight result for 600 seconds.

AI Integration Items

Item	Use
POST /api/v1/mcp	The MCP endpoint. Clients use it to find tools and to use tools.
/openapi/json	A REST contract that SDK generators and tool generators can read
/llms.txt	A plain-text list of the documentation pages for assistants and search systems
/api/v1/*	JSON data endpoints for direct requests

The MCP server sends listChanged: false. This value means that the list of tools does not change while the API version stays the same. The rate data can change.

OpenAPI

The Scalar reference is at /openapi, and the OpenAPI document is at /openapi/json. The OpenAPI document also contains the MCP endpoint, POST /api/v1/mcp, with the MCP tag.