Quickstart

Key in header, JSON out.

Seven read-only endpoints over the ratefeed database, plus an MCP server exposing the same queries as agent tools. Every response record carries provenance: the regulator URL it came from and when we retrieved it.

Authentication
Rate limits
Responses & pagination
GET /v1/health
GET /v1/filings
GET /v1/filings/{tracking}
GET /v1/rate-events
GET /v1/nonrenewals
GET /v1/zip-premiums
GET /v1/carriers
Errors
MCP server

01Authentication

One bearer key.

Email hello@ratefeed.io and we mint you a key, usually the same day. Keys start with rf_ and go in the Authorization header of every request. Every endpoint requires a key except /v1/health.

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/filings?state=CA&limit=5"

We store only a SHA-256 hash of your key, so keep your copy safe; lost keys are revoked and re-minted, never recovered.

02Rate limits

Metered by tier, reset at midnight UTC.

Tier	Price	Requests per day	Over quota
Free	$0	100	`429` with a message stating usage and the UTC reset
Design partner	$199/mo	10,000	`429` with a message stating usage and the UTC reset

Quotas count requests, not records: one call returning 500 records costs one request. Tiers and pricing are on the pricing section of the front page.

03Responses

Envelope, pagination, provenance.

List endpoints return a data array and a pagination object. Page with limit (default 50, max 500) and offset. Date filters take ISO YYYY-MM-DD. Records carry their source citation as a nested provenance object.

{
  "data": [
    {
      "serff_tracking_number": "USAA-134974273",
      "state": "CA",
      "carrier_name": "USAA Casualty Insurance Company",
      "filing_type": "Rate",
      "provenance": {
        "source_url": "https://filingaccess.serff.com/sfa/search/filingSummary.xhtml?...",
        "retrieved_at": "2026-07-08T04:08:36Z"
      }
    }
  ],
  "pagination": { "total": 735, "limit": 50, "offset": 0 }
}

04Endpoints

The seven endpoints.

GET/v1/health

Liveness check. The only endpoint that needs no key.

curl "https://api.ratefeed.io/v1/health"
# {"status": "ok", "service": "ratefeed"}

GET/v1/filings

List rate and rule filings, newest submission first.

statetwo-letter state code
carriercase-insensitive substring of the carrier name
naic_codeexact NAIC company code
since / untilinclusive bounds on the submission date (YYYY-MM-DD)
filing_typeexact filing type, case-insensitive (e.g. Rate, Rule)
limit / offsetpagination

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/filings?state=TX&since=2026-06-01&filing_type=Rate&limit=10"

GET/v1/filings/{tracking_number}

One filing by SERFF tracking number, with its rate_events and documents attached. Returns 404 for unknown tracking numbers.

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/filings/USAA-134974273"

GET/v1/rate-events

Rate-change events extracted from filings, most recently retrieved first. Each record includes indicated_vs_requested_spread_pct: indicated minus requested, in percentage points. A positive spread means the carrier asked for less than its own actuarial indication.

statetwo-letter state code
min_requested_pct / max_requested_pctbounds on the requested rate change (percent, e.g. 5 means +5%)
sincebounds retrieved_at: "what is new since my last pull" (YYYY-MM-DD)
limit / offsetpagination

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/rate-events?state=CA&min_requested_pct=5"

GET/v1/nonrenewals

County-level homeowners non-renewal data (US Senate Budget Committee, 2018–2023). Rates are percent units as published: 1.19 means 1.19%.

statetwo-letter state code
countycase-insensitive substring of the published county name (some rows are merged multi-county groups)
yeardata year, 2018–2023
limit / offsetpagination

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/nonrenewals?state=FL&year=2023&limit=10"

GET/v1/zip-premiums

ZIP-level homeowners premium and claims metrics (US Treasury FIO, 2018–2022). Rate fields here are fractions as published: 0.0092 means 0.92%.

zipfive-digit ZIP code
yeardata year, 2018–2022
limit / offsetpagination

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/zip-premiums?zip=01001&year=2022"

GET/v1/carriers

The carrier registry: NAIC company code, canonical name, and every alias accumulated from ingested filings. Use it to join carrier names across states.

limit / offsetpagination

curl -H "Authorization: Bearer rf_your_key_here" \
  "https://api.ratefeed.io/v1/carriers?limit=100"

05Errors

Errors are JSON with a detail string.

Status	Meaning
401	Missing, invalid, or revoked key. Pass `Authorization: Bearer <key>`.
404	Unknown resource, e.g. a tracking number we have never seen.
422	Invalid parameter, e.g. a malformed date or a `limit` above 500.
429	Daily quota exhausted. The detail states your usage and that the quota resets at midnight UTC.

06MCP server

The same queries, as agent tools.

The MCP server exposes five tools backed by the identical query layer as the REST API, so filter semantics never drift between the two: search_filings, get_filing, search_rate_events, county_nonrenewals, and zip_premiums.

Today the server runs over stdio: we ship design partners the server package with a nightly data snapshot, and it plugs into Claude Desktop, Claude Code, or any MCP client with a config entry like this:

{
  "mcpServers": {
    "ratefeed": {
      "command": "ratefeed",
      "args": ["mcp"],
      "env": { "RATEFEED_DB": "/path/to/ratefeed.sqlite" }
    }
  }
}

A hosted remote MCP endpoint, fronting the same API keys and metering as the REST API, is on the roadmap. roadmap Email hello@ratefeed.io to be notified when it ships.