API Reference

Reference material for Rates API endpoints, request parameters, responses, OpenAPI tooling, and AI integration.

Use this section when you know which data you need and want endpoint-level details. If you are new to the API, start with the Quickstart, then read AI Integration and Core Concepts.

Base URL

https://ratesapi.nz

Local development uses:

http://localhost:8787

Authentication

No API key is required.

Interactive Reference

The generated OpenAPI experience is available at:

Resource	URL
Scalar API client	`/openapi`
OpenAPI JSON	`/openapi/json`

AI Integration

Rates API is designed for AI assistants and agent workflows:

Resource	URL	Purpose
MCP endpoint	`POST /api/v1/mcp`	Tool discovery and tool calls for MCP-compatible clients
OpenAPI JSON	`/openapi/json`	Tool generation, SDK generation, and contract inspection
LLM docs feed	`/llms.txt`	Plain-text docs context for assistants and retrieval systems

Read AI Integration for MCP behavior, llms.txt, and recommended agent patterns.

Endpoint Groups

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`

Response Conventions

All successful responses return JSON. Error responses use a stable shape:

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

Each response includes an x-request-id header. Send your own x-request-id when you want to correlate client logs with API logs.

Time Series Rules

Parameter	Description
`date`	Single historical snapshot date in `YYYY-MM-DD` format
`startDate`	Range start date in `YYYY-MM-DD` format
`endDate`	Range end date in `YYYY-MM-DD` format
`institutionId`	Filter results by a specific institution ID
`issuerId`	Filter credit card results by a specific issuer ID
`termInMonths`	Filter mortgage results by term length

Use either date or the startDate and endDate pair. Do not combine a single date with a range.