Core Concepts

Data Freshness

The collectors are scheduled to read institution websites every four hours. Runs can be delayed or fail. Each institution must pass its source and product checks before its data can replace stored records. Verified institutions can update even when another institution fails in the same category. Failed or unreconciled institutions keep their previous records. Stored institutions without a verified replacement also stay in the dataset.

The API saves the merged dataset only when its 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 complete successful collection, also when the data did not change. Partial updates do not change this time. The value is null if the time is not known.
stale	true if no complete collection was successful in the last 12 hours. false if a complete collection was successful in the last 12 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.

In a rate response, a partial update keeps the previous lastUpdated when a stored snapshot exists. This conservative time does not claim that retained records were checked again. It can differ from lastUpdated in the health response, which records changes to any institution in the dataset.

An old timestamp can mean that rates did not change or that some collection checks failed. A dataset can be stale while successful institutions continue to update. These fields do not give a separate check time for each institution.

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 with no saved change has no snapshot. This does not prove that lenders' rates stayed the same: collection can fail. Partial snapshots include retained records for institutions that could not be verified. Earlier dates are not rewritten. Use the availableDates array in each time-series response to find the dates that have data.

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,
  "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"
}

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, and error is no_data. For example, the message can be No data available for date: 2020-01-01. The hint field tells you how to find the dates that have a snapshot.

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 earlier path, /openapi/json, gives the same document. The OpenAPI document also contains the MCP endpoint, POST /api/v1/mcp, with the MCP tag.

Direct Rate Sources

Direct records include sourceUrl, which points to the institution website or its first-party rate feed. Historical records can omit this field. A dataset can contain earlier records for an institution until its direct sources and product checks pass. Retained records keep their original source information.

For loan rates, rateType is advertised, from, or range. For a range, rate is the lower value and rateMaximum is the upper value. These are published annual percentages, not a personalised quote. A zero rate is valid when the institution explicitly publishes it. Mortgage condition can describe equity requirements or a rate available only to existing customers.

Direct card records give primaryFeeNZD as an annual amount, even when the issuer charges it in two instalments. The legacy field interestFreePeriodInMonths still contains days. A null optional card value means the collected source did not provide it; do not treat it as zero.