API Documentation

Complete reference for the YieldWatch REST API

Rate Limiting

All endpoints are limited to 100 requests per minute per IP address. Responses include X-RateLimit-Remaining and X-RateLimit-Limit headers.

GET Latest Rates

/api/rates/latest GET 100/min

Returns the most recent yield curve data available. This is the primary endpoint for displaying current treasury rates.

Response

Example Response
{
  "success": true,
  "data": {
    "date": "2026-03-20",
    "dateFormatted": "March 20, 2026",
    "rates": [
      { "maturity": "4WK", "rate": 3.73 },
      { "maturity": "6WK", "rate": 3.71 },
      { "maturity": "2MO", "rate": 3.72 },
      { "maturity": "3MO", "rate": 3.74 },
      { "maturity": "4MO", "rate": 3.73 },
      { "maturity": "6MO", "rate": 3.79 },
      { "maturity": "1YR", "rate": 3.8 },
      { "maturity": "2YR", "rate": 3.88 },
      { "maturity": "3YR", "rate": 3.9 },
      { "maturity": "5YR", "rate": 4.01 },
      { "maturity": "7YR", "rate": 4.24 },
      { "maturity": "10YR", "rate": 4.39 },
      { "maturity": "20YR", "rate": 4.97 },
      { "maturity": "30YR", "rate": 4.96 }
    ]
  }
}

GET Historical Rates

/api/rates?from=&to=&maturity= GET 100/min

Returns historical yield curve data filtered by date range and optional maturity. Dates are in ISO 8601 format (YYYY-MM-DD).

Query Parameters

from string Start date (YYYY-MM-DD). Defaults to earliest available date if not specified.
to string End date (YYYY-MM-DD). Defaults to latest available date if not specified.
maturity string Filter by specific maturity (e.g., "10YR", "2YR"). Defaults to all maturities.

Example Requests

Last 3 months
/api/rates?from=2025-12-20&to=2026-03-20
Specific maturity over time
/api/rates?from=2025-01-01&to=2026-03-20&maturity=10YR
All available data
/api/rates

Response

Example Response
{
  "success": true,
  "data": [
    {
      "date": "2026-03-20",
      "rates": [
        { "maturity": "10YR", "rate": 4.39 },
        { "maturity": "2YR", "rate": 3.88 }
      ]
    },
    {
      "date": "2026-03-19",
      "rates": [
        { "maturity": "10YR", "rate": 4.41 },
        { "maturity": "2YR", "rate": 3.9 }
      ]
    }
  ],
  "meta": {
    "from": "2026-03-19",
    "to": "2026-03-20",
    "maturity": "all",
    "count": 2
  }
}

GET Available Maturities

/api/rates/maturities GET 100/min

Returns a list of all available maturity periods and their labels.

Response

Example Response
{
  "success": true,
  "data": [
    { "value": "4WK", "label": "4 Week", "type": "short" },
    { "value": "6WK", "label": "6 Week", "type": "short" },
    { "value": "2MO", "label": "2 Month", "type": "short" },
    { "value": "3MO", "label": "3 Month", "type": "short" },
    { "value": "4MO", "label": "4 Month", "type": "short" },
    { "value": "6MO", "label": "6 Month", "type": "short" },
    { "value": "1YR", "label": "1 Year", "type": "medium" },
    { "value": "2YR", "label": "2 Year", "type": "medium" },
    { "value": "3YR", "label": "3 Year", "type": "medium" },
    { "value": "5YR", "label": "5 Year", "type": "medium" },
    { "value": "7YR", "label": "7 Year", "type": "long" },
    { "value": "10YR", "label": "10 Year", "type": "long" },
    { "value": "20YR", "label": "20 Year", "type": "long" },
    { "value": "30YR", "label": "30 Year", "type": "long" }
  ]
}

GET Rate Statistics

/api/rates/stats GET 100/min

Returns year-to-date and all-time high/low rates for each maturity, with the dates when those records occurred. All-time stats are populated after the scheduler runs for sufficient time.

Response

Example Response
{
  "success": true,
  "data": [
    {
      "maturity": "10YR",
      "yearHigh": 4.39,
      "yearHighDate": "2026-03-20",
      "yearLow": 3.97,
      "yearLowDate": "2026-02-27",
      "allTimeHigh": null,
      "allTimeHighDate": null,
      "allTimeLow": null,
      "allTimeLowDate": null
    }
  ]
}

GET Health Check

/health GET

Simple health check endpoint. Returns server status and current timestamp. Not rate limited.

Response

Example Response
{
  "status": "ok",
  "timestamp": "2026-03-23T19:00:00.000Z"
}

Response Codes

Code Description
200 Success
400 Bad Request - Invalid parameters
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Rate Limit Headers

All API responses include rate limit information in the headers:

Header Description
X-RateLimit-Limit Maximum requests allowed per window (100)
X-RateLimit-Remaining Requests remaining in current window
Retry-After Seconds to wait before retrying (only on 429)